Reference Guide
The ProgrammableWeb API lets you find and retrive APIs, mashups, member profiles and other content from the ProgrammableWeb repository. Our advanced write capabilities let you add new content and comment on existing entries via your own applications.
Contents
- Audience
- ProgrammableWeb API Query Parameters
- Mashup XML Elements Reference
- API XML Elements Reference
- Error Codes and Responses
- References
Audience
This guide is intended for programmers who want to see lists and explanations of available query parameters. It contains reference material; for an introduction and conceptual overview, see the developer's guide.
Query Parameters Reference
Refer to the following table as you make HTTP requests of the ProgrammableWeb API. An example of a query follows:
http://api.programmableweb.com/mashups/-/photo?apikey=123
These parameters can be supplied to any API query:
| Parameter | Meaning | Notes |
|---|---|---|
| apikey | Specify your apikey. | Required. Add apikey=123 to every API query. Replace 123 with your ProgrammableWeb-supplied API key. |
| username, password | Specify the ProgrammableWeb username/password. | If you wish, you can use your ProgrammableWeb username and password to access the API. This is not the preferred method since this is sent in the clear and your API provides a more consistent, secure authentication model. |
| alt | Specify the format returned. | The default format is Atom XML. Add alt=json to your queries to receive in json. JavaScript code to consume the json feed is available here. |
| version | Specify the version of the API to use. | This optional parameter specifies which version of the ProgrammableWeb API to use. If not specified, each call defaults to the latest version, which is currently 1.0. |
Mashup Feeds
We organize feeds that contain mashups in several ways. We have the sorted list, search by tag, search by keyword, user mashups, and favorites. All feeds are limited to displaying 30 entries by default. Paging querystrings are added to retrieve the next page of the list.
Mashups Feed
The mashup feed is accessed via the mashups url.http://api.programmableweb.com/mashups?apikey=123You can use query parameters to modify the display of the list:
| Parameter | Meaning | Notes |
|---|---|---|
| sort | Specifies the order of entries in a feed. | Add sort=popular to sort by number of visits. Add sort=rating to sort by average rating. Add sort=date to sort by date added. Add sort=name to sort by mashup name (default). |
| q | Specify a search term. | This is a full-text search on Mashups name and description. While it is slightly more resource intensive, it is much more likely to get a match than other methods. Sorting by popularity is a good combination with this search since it gives better matches. |
| pagesize | Specify the maximum number of mashups to return. | The default pagesize is 20. Users needing more are welcome to request up to 30 mashups. |
| page | Specify the page number to display. | This field is zero-based, so page=1 gives the second page. Omitting this field gives the first page. If you are not using the openSearch paging, you can simply increment the page number until you receive less than pagesize mashups in the feed. |
Tagged Mashup Feed
The Tagged Mashup Feed searches for mashups which are tagged with keywords.| /mashups/-/tag | Specify a tag to be searched for. | Multiple tags can be appended (up to two) for multiple tag search. For example, /mashups/-/photo/travel will search for mashups tagged photo and travel. |
| maxdays | Specify the maximum age of the mashup in days. | To show those added in the past 14 days add maxdays=14. This works well with other parameters such as tag, sort=popular and so on. |
| /mashups/name | Specify the label of the mashup to show. |
If you know the label of a mashup (which can be found in the
rel="self" links in the mashup feed), you can retrieve just
a single mashup. For example, to show the mashup labelled
wheel-of-food, specify /mashups/wheel-of-food
Labels are similar to the mashup name except that they
are optimized for url readability and contain few or no
special characters. Labels are always lowercase. |
| /mashups/name/comments | Show comments for the mashup labelled. | |
| apis | Specify an API or multiple APIs used by mashups to be shown. | The apis querystring must be encoded. Get encodings from the API Feeds or the website. To specify multiple apis, use %2C to delimit the entries. The %2C delimiter is a comma urlencoded. For example to find mashups that use Flickr and Google Maps, add apis=flickr%2Cgoogle-maps to the querystring. |
API Feeds
APIs Feed
http://api.programmableweb.com/apis
| Parameter | Meaning | Notes |
|---|---|---|
| sort | Specifies the order of entries in a feed. | Add sort=date to sort by newest. Add sort=mashups to sort by mashups using this API. Add sort=name to sort alphabetically (default). |
| q | Specify a search term. | This is a full-text search on APIs name and description. While it is slightly more resource intensive, it is much more likely to get a match than other methods. |
| pagesize | Specify the maximum number of apis to return. | The default pagesize is 20. Users needing more are welcome to request up to 30 APIs. |
| page | Specify the page number to display. | This field is zero-based, so page=1 gives the second page. Omitting this field gives the first page. If you are not using the openSearch paging, you can simply increment the page number until you receive less than pagesize APIs in the feed. |
| /apis/name | Retrieve the labeled API from the APIs Feed. | As above, API labels are simplified version of the API name. |
| /apis/name/comments | Retrieve comments for the labeled API. | |
| /apis/name/mashups | Retrieve a list of mashups that use the labeled API. | This is equivalent to the Mashup Feed: /mashups?apis=google-maps, but is added for consistency and ease of use. |
| /apis/name/links | Retrieve a list of links that refer to the labeled API. | These links are often HowTo's and guides which may be helpful to users. The list is moderated by admins. |
Tagged/Categorized API Feed
The Tagged/Categorized API Feed searches for mashups which are tagged with keywords and category names.| /apis/-/Category | List apis that are categorized with the given Category. | Each API has a single category, so they may not be exactly what you're looking for, but they are usually quite good. The list of categories can be found here. Categories start with an uppercase letter. |
| /apis/-/tag | List apis that are tagged with the given tag. | tags always start with a lowercase letter. |
| /apis/-/Category/tag | List apis that are categorized and tagged. | Multiple tags can be used as in the mashup feed. |
Widget Feeds
http://api.programmableweb.com/widgetsWidget Feed parameters are the same as mashup parameters except that they don't have apis or tags.
| Parameter | Meaning | Notes |
|---|---|---|
| sort | Specifies the order of entries in a feed. | Add sort=popular to sort by number of visits. Add sort=rating to sort by average rating. Add sort=date to sort by date added. Add sort=name to sort by widget name (default). |
| q | Specify a search term. | This is a full-text search on widget name and description. While it is slightly more resource intensive, it is much more likely to get a match than other methods. |
| pagesize | Specify the maximum number of widgets to return. | The default pagesize is 20. Users needing more are welcome to request up to 30 widgets. |
| page | Specify the page number to display. | This field is zero-based, so page=1 gives the second page. Omitting this field gives the first page. If you are not using the openSearch paging, you can simply increment the page number until you receive less than pagesize widgets in the feed. |
Member Feeds
http://api.programmableweb.com/members
| Parameter | Meaning | Notes |
|---|---|---|
| sort | Specifies the order of entries in a feed. | Add sort=date to sort by date registered. Add sort=name to sort by user name (default). |
| q | Specify a search term. | This is a full-text search on username and location. While it is slightly more resource intensive, it gives a very unique feature: find a member or developer in your city, region, or country. |
| filter | Filter members by attribute. | The only valid filters are mashups, wikis, or all. The default is all. The mashups filter lists only mashup developers. The wikis filter lists members with wikis. |
| apis | Show members with mashups that use the given api. | This parameter takes the full api name. |
| tags | Show members with mashups with the given tag. | This is a quite useful filter parameter. |
| pagesize | Specify the maximum number of members to return. | The default pagesize is 20. Users needing more are welcome to request up to 30 members. |
| page | Specify the page number to display. | This field is zero-based, so page=1 gives the second page. Omitting this field gives the first page. If you are not using the openSearch paging, you can simply increment the page number until you receive less than pagesize members in the feed. |
| /members/username | Specify the username to show. | Each member has a variety of data. |
| /members/username/mashups | Show mashups created by a given user. | If a user has created a mashup, it can be found here. |
| /members/username/favorites | Show favorite mashups by a given user. | |
| /members/username/friends | Show friends of a user. | Friendship on ProgrammableWeb is uni-directional, so a person may befriend anyone and it will only show up on their friend list. This is different from other social sites, though it adds the feature that a person can highlight developers or members that they like without requiring mutual friendship. |
Feed Feeds
http://api.programmableweb.com/feeds
Feed Feed parameters are the same as widget parameters.
| Parameter | Meaning | Notes |
|---|---|---|
| sort | Specifies the order of entries in a feed. | Add sort=popular to sort by number of visits. Add sort=rating to sort by average rating. Add sort=date to sort by date added. Add sort=name to sort by feed name (default). |
| q | Specify a search term. | This is a full-text search on feed name and description. While it is slightly more resource intensive, it is much more likely to get a match than other methods. |
| pagesize | Specify the maximum number of feeds to return. | The default pagesize is 20. Users needing more are welcome to request up to 30 feeds. |
| page | Specify the page number to display. | This field is zero-based, so page=1 gives the second page. Omitting this field gives the first page. If you are not using the openSearch paging, you can simply increment the page number until you receive less than pagesize feeds in the feed. |
XML Elements Reference for Mashup Responses
The following table contains descriptions of the XML elements for the mashup detail record we return. For example, when you enter http://api.programmableweb.com/mashups/wheel-of-food and then select View Source, the XML elements are shown.
| Element | Description | Examples |
|---|---|---|
| entry | Each mashup is an entry. | <entry> |
| id | URL of the mashup on the main ProgrammableWeb site. | <id>http://www.programmableweb.com/mashup/wheel-of-food</id> |
| title | The title of the mashup. Has an attribute called "type". | <title type="text">Wheel of Food</title> |
| link | Hyperlink to the mashup on the main ProgrammableWeb site. | <link href="http://www.programmableweb.com/mashup/wheel-of-food"></link> <link rel="self" href="http://api.programmableweb.com/mashups/wheel-of-food"></link> |
| author | ProgrammableWeb user ID of the mashup's author. | <author> <name>Unknown</name> </author> |
| summary | The friendly description of the mashup. Has an attribute called "type". | <summary type="html">The most fun way to pick a restaurant near you.</summary> |
| media:title | Title of the mashup. Has an attribute called "type". | <media:title type='plain'>Wheel of Food</media:title> |
| media:content | The image associated with the mashup. This is always a JPG image and always the medium-sized image (exact size is 300x250) that appears with a mashup on its ProgrammableWeb profile page. The JPG file always contains the letters "md" in the beginning of the JPG file. Has the following attributes: url, type, medium, and isDefault. | <media:content url='http://www.programmableweb.com/images/links/md6036.jpg' type='image/jpeg' medium='image' isDefault='true' /> |
| media:thumbnail | Same as the media:content element, except the JPG image is smaller (always 130x100). Has the following attributes: url, height, and width. | <media:thumbnail url='http://www.programmableweb.com/images/links/mt6036.jpg' height='32' width='32' /> |
| content | Container element that holds the pw:mashup element; the pw:mashup element then holds the mashup record details. Has an attribute of "type". | <content type="application/xml"> |
| pw:mashup | The parent element for all important details about a mashup. | <pw:mashup xmlns:pw="http://www.programmableweb.com/api/opensearch/1.0/"> |
| rating | Average rating of the mashup, as voted by ProgrammableWeb users. | <rating>4.4</rating> |
| name | Name of the mashup. | <name>Wheel of Food</name> |
| label | Label of the mashup. | <label>Wheel of Food</label> |
| author | User ID of the mashup's author. | <author>Unknown</author> |
| description | The friendly description of the mashup. | <description>The most fun way to pick a restaurant near you.</description> |
| type | <type></type> | |
| useCount | <useCount>1324</useCount> | |
| icon | URL to the thumbnail JPG image (size of 130x100). The JPG file always contains the letters "mt" in the beginning of the JPG file. | <icon>http://www.programmableweb.com/images/links/mt6036.jpg</icon> |
| sampleUrl | The URL that, when clicked, takes the user to where the mashup lives on the Internet. | <sampleUrl>http://www.coverpop.com/wheeloffood/</sampleUrl> |
| dateModified | Date that the ProgrammableWeb profile of the mashup was last modified. | <dateModified>2007-02-19T08:43:47Z</dateModified> |
| numComments | Number of comments that ProgrammableWeb users have added about the mashup. | <numComments>0</numComments> |
| CommentsURL | URL to comments about the mashup. | <commentsUrl> http://api.programmableweb.com/mashups/wheel-of-food/comments </commentsUrl> |
| tags | Container topic for "tag" elements. | <tags> |
| tag | Tags that ProgrammableWeb assigns to the mashup when we publish it. | <tag> <name>food</name> <url>http://www.programmableweb.com/tag/food</url> </tag> <tag> <name>fun</name> <url>http://www.programmableweb.com/tag/fun</url> </tag> <tag> <name>games</name> <url>http://www.programmableweb.com/tag/games</url> </tag> <tag> <name>search</name> <url>http://www.programmableweb.com/tag/search</url> </tag> |
| apis | Container topic for "api" elements. | <apis> |
| api | The API that the mashup uses. A mashup can use multiple APIs. | <api> <name>Yahoo Local Search</name> <url>http://www.programmableweb.com/api/yahoo-local-search</url> </api> |
XML Elements Reference for API Responses
The following table contains descriptions of the XML elements for the API profile response document. For example, when you enter http://api.programmableweb.com/apis/google-maps and then select View Source, the XML elements are shown.
| Element | Description | Examples |
|---|---|---|
| entry | Each api is an entry. | <entry> |
| id | URL of the API profile on the main ProgrammableWeb site. | <id>http://www.programmableweb.com/api/google-maps</id> |
| title | The title of the API profile. Has an attribute called "type". | <title type="text">Google Maps</title> |
| link | Hyperlink to the API profile on the main ProgrammableWeb site. | <link href="http://www.programmableweb.com/api/google-maps"></link> <link rel="self" href="http://api.programmableweb.com/apis/google-maps"></link> |
| author | <author> <name></name> </author> | |
| summary | Short description of this service. Often this is 3-7 words. This appears in the primary API list along with the API name. Has an attribute called "type". | <summary type="html">Mapping services</summary> or <summary type="html">Photo sharing service</summary> |
| content | Container element that holds the pw:api element; the pw:api element then holds the API profile's primary elements. Has an attribute of "type". | <content type="application/xml"> |
| pw:api | The parent element for all important details about the API profile. | <pw:api xmlns:pw="http://www.programmableweb.com/api/opensearch/1.0/"> |
| rating | Average rating of the api, as voted by ProgrammableWeb users. | <rating>4.2</rating> |
| name | Name of the API spotlighted in the profile. | <name>Google Maps</name> |
| label | Label of the API spotlighted in the profile. | <label>Google Maps</label> |
| package | <package></package> | |
| author | <author></author> | |
| version | <version></version> | |
| description | Short description of this service. Often this is 3-7 words. This appears in the primary API list along with the API name. | <description>Mapping services</description> or <description>Photo sharing service</description> |
| type | <type>1</type> | |
| downloads | <downloads></downloads> | |
| useCount | <useCount></useCount> | |
| icon | URL to the thumbnail JPG image. This is the logo image for this service. | <icon> http://www.programmableweb.com/images/apis/at22.jpg</icon > |
| sampleUrl | <sampleUrl></sampleUrl> | |
| downloadUrl | <downloadUrl></downloadUrl> | |
| dateModified | Date that the ProgrammableWeb API profile was last modified. | <dateModified>2005-12-05T05:52:02Z</dateModified> |
| remoteFeed | <remoteFeed>0</remoteFeed> | |
| numComments | Number of comments that ProgrammableWeb users have added about the API profile. | <numComments></numComments> |
| CommentsURL | URL to comments about the API profile. | <commentsUrl> http://www.programmableweb.com/api/google-maps/comments </commentsUrl> |
| tags | Container topic for "tag" elements. | <tags> |
| tag | Keywords that ProgrammableWeb assigns to the API profile when we publish it. Usually 1-4 tags. One of the tags usually repeats the category. | <tag>mapping</tag> |
| category | The hierarchical category this API profile is assigned to. API profiles on ProgrammableWeb are classified in two ways: one by Category and the other by Tags. Only one category per API profile is allowed (but multiple tags are allowed). | <category>Mapping</category> |
| protocols | The protocols or architectural styles that the API supports, such as SOAP, REST, XML-RPC, JavaScript, and so on. | <protocols>JavaScript</protocols> |
| wsdl | URL to the WSDL file for SOAP-based APIs. For all non-SOAP APIs this is blank. | <wsdl>http://api.google.com/GoogleSearch.wsdl</wsdl> |
| dataFormats | Response data formats supported by the API. | <dataFormats>XML, JSON, Atom</dataFormats> |
| apigroups | If the documentation for the API has any obvious groupings, those groups are listed. Otherwise, this is blank. | <apigroups>Uses a JavaScript object model</apigroups> |
| example | Example API Methods. Often, this is a link to a "get_something" method, or examples of REST syntax that you can put after the service endpoint to return some results. | <example>Search, Cache, Spelling</example> |
| clientInstall | If it's not a client-side application, this is No. | <clientInstall>No</clientInstall> |
| authentication | Authentication model used by the API. | <authentication>Via developer key</authentication> |
| ssl | Specifies whether SSL support is available for the API. | <ssl>No</ssl> |
| readonly | Specifies whether Read-only Without Login is available for the API. | <readonly>Yes</readonly> |
| VendorApiKits | Specifies available resources provided by vendors. | <VendorApiKits>JavaScript library</VendorApiKits> |
| CommunityApiKits | Specifies available resources provided by the Dev community. | <CommunityApiKits></CommunityApiKits> |
| blog | Specifies the URL to the official blog's API, if one exists. | <blog></blog> |
| forum | Specifies the URL to the official API forum, if one exists. | <forum></forum> |
| support | Specifies the URL, in wiki syntax, of where a developer can get support as they work with the API. | <support>[[http://groups.google.com/group/Google-Maps-API Discussion Group]]</support> |
| accountReq | Specifies whether Account with Service is Required. | <accountReq>No</accountReq> |
| commercial | Specifies whether Commercial Licensing is available. | <commercial> [[http://local.google.com/support/bin/request.py Contact provider]] </commercial> |
| provider | <provider></provider> | |
| nonCommercial | Specifies whether Non-commercial Licensing is available. | <nonCommercial>Upon request</nonCommercial> |
| dataLicensing | Specifies whether Data Licensing is available. | <dataLicensing></dataLicensing> |
| fees | Specifies whether there are any usage fees associated with the API. | <fees>None</fees> |
| limits | Specifies whether there are any usage limits associated with the API. | <limits>50,000 requests per day</limits> |
| terms | URL (in wiki syntax) to any Terms of Service that might exist. | <terms>[[http://www.google.com/apis/maps/signup.html See the signup page]]</terms> |
| company | <company>2</company> |
Errors and Responses
| Parameter | Meaning | Notes |
|---|---|---|
| 200 OK | The request succeeded. | Any page that is successful that does not insert data will return a HTTP/1.1 200 OK. Depending on the format, the Content-Type will vary. |
| 201 Created | The add succeeded. | A mashup, widget, feed, link, API, or comment has been added. It may not show up on the site until it is approved. |
| 400 Invalid input. Widget name must not be empty. | You have forgotten to fill out the name in an posted new widget. | Please take care to generate proper xml with the same data as the type you wish to create which is documented above. Content-Type: text/html. |
| 400 API limit exceeded: n | API limit has been exceeded. | The API limits ensure that the API cannot be abused. If you get this message, please use less resources or contact us to discuss your requirements. Content-Type: text/html. |
| 401 Login failed. | Username, password, or apikey is incorrect. | If you use any auth that is not correct, it will give you an HTTP/1.1 401 Login failed. It is Content-Type: text/html. |
| 404 Member not found. name | The given member cannot be found. | Giving an invalid username in the member feed will cause this. Content-Type: text/html. |
| 404 Link not found. name | The given link (mashup, widget, feed) cannot be found. | Giving an invalid unique name in the mashup, widget, or feed feeds will cause this. Content-Type: text/html. |
| 404 API not found. name | The given API cannot be found. | Giving an invalid API name in the API feed will cause this. Content-Type: text/html. |
| 501 Unable to move uploaded file. name | A server error has caused the file uploaded to /download/name to be unusable. | This is an unlikely error caused by a server misconfiguration. Please contact the admin if you receive this error. Content-Type: text/html. |
| 400 Widget is duplicate. Admin must delete or rename similar named item. | The widget, mashup, or feed has a name similar to one that already exists. | We need all names to be unique. We do not have an automatic system to generate unique names, so please rename your widget, mashup, or feed. Content-Type: text/html. |
| 400 Link was not found name. | The comment to be added does not have a valid link. | You need to specify a valid api, mashup, widget, or feed to add a comment. Content-Type: text/html. |
| 409 Conflict | Optimistic concurrency check failed. | If you use an outdated editversion parameter during an update to an api, mashup, widget, or feed. It will return the feed in the same way a success will. |