Basic Call Structure

REST based and Argument based Queries

The 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://open.worldbank.org/countries?per_page=10&incomeLevel=LIC&api_key=xxxx

URL based
http://open.worldbank.org/incomeLevel/LIC/countries

Request Format

Requests support the following parameters:

api_key – Your api key, provided when you given to you when you register.
http://open.worldbank.org/indicators?api_key=xxxxxxxxx

date – date-range by year that scopes the result-set. A range is indicated using the semicolon separator
http://open.worldbank.org/indicators?date=2000:2001

format – output format. Currently the API supports two formats: XML and JSON
http://open.worldbank.org/indicators?format=xml

page – utility parameter for paging through a large result-set. Indicates the page number requested from the recordset.
http://open.worldbank.org/indicators?page=2

per_page – number of results per page, for pagination of the result-set. Default setting is 50
http://open.worldbank.org/indicators?per_page=25

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.

Large numbers
Larger numbers can be abbreviated with: K for thousand, M for million and B for billion. Thus “5 million” can be represented by 5M.

Logical AND
comma “, “ represents logical AND. E.g.: “/keywords/lions,tigers” – calls both lions and tigers keywords.

Logical OR
semicolon “;” represents logical OR. E.g.: “us;ge” – calls either United States OR Georgia.

Examples

One common use of the API would be get indicator data about countries.

For a list of all indicators available for Brazil, use:
http://open.worldbank.org/countries/br/indicators?api_key=xxxxxxxxx

To get information about a specific indicator - for example, the 2006 data on the GDP of Brazil:
http://open.worldbank.org/countries/br/indicators[BNY.GNP.PCAP.CD]?date=2006:2006?api_key=xxxx

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:

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