API: Basic Call Structure

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:

CodeLanguage
enEnglish
esEspañol
frFranç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.

Thank you for visiting the World Bank's Data Help Desk. Please review the terms of use for this website. Your continued use of this website constitutes your acceptance of these terms and conditions.

Developer Info

Feedback and Knowledge Base