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:

Code Language
en English
es Español
fr Français
ar العربية
zh 中文

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.

Help/Feedback

User Voice