WordPress.org Plugin Information API Docs

In response to: “If only I had written some.. Sorry! -DD32″ – My tagline i left in the Plugins API for WordPress

(This was a copy-paste job from an email i sent to the wp-hackers list: http://comox.textdrive.com/pipermail/wp-hackers/2009-January/023505.html)

Some basic documentation for the Plugins API: http://api.wordpress.org/plugins/info/1.0/

Note: The request should look something similar to this: $_POST['action'] = The action to perform, $_POST['body'] => A Serialized Object (with properties which are explained below). The return values from the API should be a Object in all cases (Except if you visit it via a browser with a GET request with no valid action, Then it’ll return the bbPress friendly page)

Actions:

query_plugins
plugin_information
hot_tags

query_plugins

Accepts an object with a property of either:
browse – A bbPress View to “browse”, eg, “popular” = http://wordpress.org/extend/plugins/browse/popular/
search – The term to search for
tag – Browse by a tag
author – Browse by an author (Note: .org has a few plugins to extend the author search to include contributors/etc)

Other properties which the object can have:
page – the page of the results (duh..)
per_page – the number of results per page
fields – This is a bit.. odd.. an array of which fields to return, the API has defaults for requests, but it can be overridden from the client, send an array with the field as the key, and true|false as the value to return or not, The fields are: ‘description’, ‘sections’, ‘tested’ ,’requires’, ‘rating’, ‘downloaded’, ‘downloadlink’, ‘last_updated’ , ‘homepage’, ‘tags’

return array of objects:

An array of the same object that plugin_information returns

plugin_information

Takes an object with the property:
slug – The slug of the plugin to return the info for
fields – once again, Optional, Same deal as in the previous action, just its got different defaults (ie. this one will return all the sections of the readme, whilst the previous will only return the short description)

return object:

name – The plugins name
slug – the plugins slug
version – The latest version
author – The Author of the plugin – If a URL is available for the author, This will be a link

The following fields are optional, And are returned based on the fields param
requires – The required WordPress version
tested – The highest tested compatible WordPress version
rating – returns the % rating (ie, 10%, 100%) as a number.  (This is displayed on .org as a 1-5 scale)
num_ratings – If ratings is requested, this will be returned as well, Its the number of people that have rated the plugin
downloads – the number of times the plugin has been downloaded
last_updated – the date that the plugin was last updated, Excludes the time
homepage – The URL of the plugin
description – The short description of the plugin(s)
sections – An array of readme sections, ie. array( ‘faq’ => ‘FAQ… blah blah my plugin is great.. blah blah’, ‘installing’ => ‘fgfg…. If no readme sections are found, It returns  array(‘description’ => (description field here from above) )
downloadlink – The Download Link for the plugin (Theres a bug in this at present, Any version with a space in the URL returns the wrong URL: #8610
tags – an array of array( ‘tag_slug’ => ‘Tag Name, ‘slug2′ => ‘Pretty Butterflies’)hot_tags

Takes an object of:
number – The number of tags to return, Defaults to 100

return array of objects: (key will be tag slug)

name – The tags name
slug – The tags slug
count – The number of plugins

Final note, The API may also return an error object in the case of an error, It’ll be an object with a single property:
error – A Error string, ie. “Slug not provided” or “action not implemented”

47 thoughts on “WordPress.org Plugin Information API Docs”

  1. Does/can the “query_plugins” action also have “downloaded_today”, “downloaded_this_week”, and “downloaded_this_month” parameters?

    1. No it doesn’t, There was no reason to include it in the API at the time.

      Theres an XML file somewhere which the graph pulls the data from, You could probably use that to get the download count for each date..

      1. I know this post was quite a while ago, but is there any chance you could give any more info about this XML doc with by-date download info? It would be very useful for a project I’m working on, but so far I haven’t been able to find it.

  2. Hmm, I don’t think that would fly when trying to retrieve stats for multiple plugins.

    I’m working on a GET interface for your POST API ( http://api.uproot.us/1.0/ ), and one of my original goals was to be able to show the average downloads from creation date (total_downloads / days_since_creation).

    Any chance you could add some of the following parameters to the API’s “query_plugins” action? :: created, downloaded_today, downloaded_yesterday, downloaded_last_week. Maybe we could work something out instead if you’re busy. If I just had SELECT access to the DB, I could fully flesh out / document the GET API and pass you the source. Let me know your thoughts.

    1. Unfortunately, I don’t have access to change the API, and as it is, Its pretty much staying as it is until a new requirement is needed for the next version of the API (And as it is, General users accessing the API doesn’t appear to be a valid use case)

      So i don’t think i can help you there :/
      You could create a ticket on trac (under the component ‘WordPress.Org’ and see if anyone’s interested..

  3. So I’m correct in believing there is no way to order results by “most downloads / newest / recently updated” on a “query_plugins” called filtered on tag or search terms. I could really use this for filtering BuddyPress plugins on buddypress.org. Perhaps I will open a ticket.

  4. hello please solve my this issue i m getting this messege
    An Unexpected HTTP Error occurred during the API request.
    when i try to install theme or pluigun try to import anything

  5. Since you seem to know pretty much how the works on the server side, I would kindly ask you to check the ticket I posted last week on WordPress Forum : Communicating the WordPress way with server API.

    I am wondering how are handled the accents that are returned so that unserialize can work.

    I used this code :

    page = 1;
    $req->per_page= 30;
    $req->search = 'francais';
    $data = array('action' => 'query_plugins', 'request' => serialize($req));

    #print var_dump($data);

    $postdata = http_build_query(
    $data
    );

    $opts = array('http' =>
    array(
    'method' => 'POST',
    'header' => 'Content-type: application/x-www-form-urlencoded',
    'content' => $postdata
    )
    );
    $context = stream_context_create($opts);
    $result = file_get_contents('http://api.wordpress.org/plugins/info/1.0/', false, $context);

    print $result;

    And I see that “é” is handled with “ÂŽ” or “é”.

    How should I handled accent on my server API so that I return “é” as “ÂŽ” so that the unserialize work ?

    Thank you for your post!

    1. Make sure the page you’re printing that data on is using a utf8 character set, If you’re printing the data on a page with ansi/iso-8859 character sets, you’ll see unicode (double-byte characters such as an accented e) printed as 2 characters. That appears to be your problem to me.

  6. Oops… the line :
    And I see that “é” is handled with “ÂŽ” or “é”.

    … should read :

    And I see that “é” is handled with “ÂŽ” or “é”.

    Thank you.

  7. Last edit :

    Oops… the line :
    And I see that “é” is handled with “ÂŽ” or “é”.

    … should read :

    And I see that “é” is handled with “ÂŽ” or “& # 2 3 3 ;”. (without all spaces)

    Thank you.

  8. Hi Dion,

    First, great doc! Simple but efficient.

    How did you do your multibyte serialize when outputting data ? I would like to push the data I get to another service but when I serialize the data, I get weird characters. I test with slug ‘logosware-suite-uploader’.

    If var_dump my class, I see the data correctly. If I serialize then print, I get characters I can’t use.

    Did you have that problem ? How did you solve it ? I can’t find any information about multibyte serialization.

    Thank you.

    1. The data is UTF8 encoded, if the page it’s being displayed on is UTF8 as well, then everything will work fine. check out the WordPress header for the meta charset declarations (I think that’s it at least)

  9. An example of requesting plugin information, whilst also requesting the short description:

    
    $payload = array(
      'action' => 'plugin_information',
      'request' => serialize(
        (object)array(
            'slug' => 'add-from-server',
            'fields' => array('description' => true)
         )
       )
    );
    $body = wp_remote_post( 'http://api.wordpress.org/plugins/info/1.0/', array( 'body' => $payload) );
    
    var_dump( unserialize($body['body']) );
    
  10. I am trying to print out a page with all of the plugin-slugs in the repo. Using the following code seems like it should work but it just returns a list of the most recent 24. Any ideas?

    ` $payload = array(
    ‘action’ => ‘query_plugins’,
    ‘request’ => serialize(
    (object)array(
    ‘search’ => ”,
    )
    )
    );
    $body = wp_remote_post( ‘http://api.wordpress.org/plugins/info/1.0/’, array( ‘body’ => $payload) );

    ?>
    Info: http://dd32.id.au/projects/wordpressorg-plugin-information-api-docs/
    plugins));

    foreach ($stringData->plugins as $plugin) {
    echo(” . $plugin->slug . “”);
    }`

  11. I guess I can pull the slugs off of the SVN and then query the API?

    I have also noticed that it will return all of the plugins but they are split up into pages. I can return ~100 per page but then I get back an error. If I send the ‘page’ field I can return the next 100 and so on. Is there an easy query to do to know how many pages?

    I should clear up that I am actually looking to pull almost all of the data from the repo. I was at first going for the slugs just because it seemed that if I could do that I could do everything. Apparently not. =) Any info or direction you have would be very much appreciated. I’d be happy to write up anything I find out and provide it to you for documentation purposes.

    1. Simplest way i can say is this: (note, that it’s much simpler than the plugin api, I’m also not going to go into the Theme update API)

      endpoint: http://api.wordpress.org/themes/info/1.0/

      POST with
      ‘action’ => ‘feature_list’
      receive back a list of theme ‘filters’

      POST with
      ‘action’ => ‘theme_information’
      ‘request’ => serialize( array( ‘slug’ => ‘twentyten’ ) );
      receive back theme information (probably serialized)

      POST with
      ‘action’ => ‘query_themes’
      ‘request => serialize( array( ‘search’ => ‘search term’ ) )
      OR
      ‘request => serialize( array( ‘author’ => ‘wordpressdotorg’ ) )
      OR
      ‘request => serialize( array( ‘tag’ => array( ‘one-column’, ‘black’ ) ) )
      OR
      ‘request => serialize( array( ‘browse’ => ‘featured’ ) ) (accepts featured OR new OR updated)
      receive back search results.

      That should be enough to get most people going, if you have a problem with that, look up themes_api() in WordPres core, if you can’t understand that, throw some debugging in there, and make a few searches, watch the output.

      1. dd32: Thanks for the great post, I’m not finding the request for theme info is working however, do you have an example code? (im aiming for cli using curl/wget)

          1. Figured it out. Curl does it since it needs a POST
            For anyone wanting the info

            curl -s -d 'action=theme_information&request=O:8:"stdClass":1:{s:4:"slug";s:9:"twentyten";}' http://api.wordpress.org/themes/info/1.0/

            The s:9 before the theme name is number of letters in theme (twentyten has 9 letters)

      2. Anyone know how to do this in Ruby? I’m trying everything and its not working. It will only do the action but none of the additional arrays. Thanks!

        In pry I’m doing:

        By the way this is querying the plugins, but its the same idea..

        RestClient.post(“http://api.wordpress.org/plugins/info/1.0/”, action: “query_plugins”, request: PHP.serialize( search: “spam” ))

        It will query the plugins but only just the recent ones, I can’t pass in the search parameter at all.

  12. Nice post. I was checking continuously this blog and I
    am impressed! Extremely useful info specially the closing part :)
    I care for such info much. I used to be seeking this particular information for
    a very lengthy time. Thanks and good luck.

Comments are closed.