API: Basic Call Structure Worldbank

REST based and Argument based Queries

The Indicators API supports two basic ways to build queries: a url based structure and an argument based structure. For example, the following two requests will return the same data, a list of countries with income level classified as low income:
Argument based > http://api.worldbank.org/countries?per_page=10&incomeLevel=LIC
URL based > http://api.worldbank.org/incomeLevels/LIC/countries

Request Format

Requests support the following parameters:
date – date-range by year, month or quarter that scopes the result-set. A range is indicated using the colon separator
> http://api.worldbank.org/countries/all/indicators/SP.POP.TOTL?date=2000:2001
> http://api.worldbank.org/countries/chn;bra/indicators/DPANUSIFS?date=2009M01:2010M08
> http://api.worldbank.org/countries/chn;bra/indicators/DPANUSIFS?date=2009Q1:2010Q3
additionally supports, year to date values (YTD: ). Useful for querying high frequency data
> http://api.worldbank.org/countries/chn;bra/indicators/DPANUSIFS?date=YTD:2010
format – output format. API supports three formats: XML, JSON and JSONP
> http://api.worldbank.org/countries/all/indicators/SP.POP.TOTL?format=xml
> http://api.worldbank.org/countries/all/indicators/SP.POP.TOTL?format=json
> http://api.worldbank.org/countries/all/indicators/SP.POP.TOTL?format=jsonP&prefix=Getdata
Note: For JsonP format, 'prefix' parameter needs to be specified.
page – utility parameter for paging through a large result-set. Indicates the page number requested from the recordset.
> http://api.worldbank.org/countries/all/indicators/SP.POP.TOTL?page=2
per_page – number of results per page, for pagination of the result-set. Default setting is 50
> http://api.worldbank.org/countries/all/indicators/SP.POP.TOTL?per_page=25
MRV - fetches most recent values based on the number specified.
> http://api.worldbank.org/countries/chn;bra/indicators/DPANUSIFS?MRV=5
> http://api.worldbank.org/countries/chn;bra/indicators/DPANUSIFS?date=2008M05:2009M10&MRV=5
Gapfill - (Y/N) Works with MRV. Fills values, if not available, by back tracking to the next available period (max number of periods back tracked will be limited by MRV number)
> http://api.worldbank.org/countries/chn;bra/indicators/DPANUSIFS?MRV=5&Gapfill=Y
Frequency - for fetching quarterly (Q), monthly(M) or yearly (Y) values. Currently works along with MRV. Useful for querying high frequency data.
> http://api.worldbank.org/en/countries/ind;chn/indicators/DPANUSSPF?MRV=7&frequency=M
> http://api.worldbank.org/en/countries/ind;chn/indicators/DPANUSSPF?date=2000:2006&MRV=5&frequency=Q

Language

Any call to the API can be prefixed with a language code to retrieve localized results. When no language is specified English is assumed. The following languages are available:

To retrieve the full list of indicators in Spanish you would use the following query:
> http://api.worldbank.org/es/indicators

Delimiters

Range
Use a colon “:” to indicates a range (for numeric values only). For example, "5:10" – calls numeric value range from 5 to 10.
Logical AND
semicolon “;” represents logical AND. E.g.: “us;ge” – calls either United States AND Georgia.

Examples

One common use of the API would be get indicator data about countries.
To get information about a specific indicator - for example, the 2006 data on the GDP of Brazil: >http://api.worldbank.org/countries/br/indicators/NY.GDP.MKTP.CD?date=2006

Response Format

By default, all requests will respond with valid XML. To receive the response in JSON format, you may provide format=json in any request.

Sample API Response

A valid request returns this:

<rsp stat="ok">
    [xml-payload]
</rsp>

An invalid request returns this - see Error codes for a full listing of possible errors.

<rsp stat="fail">    
        <err code="[error-code]" msg="[error-message]">  
</err></rsp>  

Current limitations

You cannot currently sort any requests. Generally results are returned in a reasonable order (ie alpha), but that order cannot be controlled.