Skip to content
World Bank Group logo

API Basic Call Structures

← Developer Information

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:

Query Strings

The API support the following query strings in requests.

Date and Date-Range: Date-range by year, month or quarter that scopes the result-set.

Examples:

A range is indicated using the colon (:) separator.

Examples:

Requests additionally support year-to-date values (YTD), which is useful for querying high frequency data.

Output Format: The API supports the following four output formats.

Download Format: The API supports the following three download formats.

Page: For paging through large result-sets. This allows users to indicate the page number requested from the record-set.

Per_page: For determining the number of results per page. The default setting is 50 results per page.

MRV: Fetches most recent values based on the number specified.

MRNEV: For fetching most recent non-empty values based on the number specified.

Gap-fill: (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)

Frequency: For fetching quarterly (Q), monthly (M) or yearly (Y) values. This feature currently works along with MRV. This query string is useful for querying high frequency data.

Multiple Indicators: Data for multiple indicators can be queried from a single data source by providing the indicator codes separated by ";" (semicolon), as well as the source ID.

Note: A maximum of 60 indicators can be used. A maximum of 1,500 characters are allowed between two back-slashes (/). A maximum of 4,000 characters are allowed in the entire URL.

Footnote: For fetching footnote detail in data calls. "footnote=y" gives the footnote value for country, indicator and year.

Languages

The following query returns all the languages supported by the World bank API v2: https://api.worldbank.org/v2/languages

When no language is specified English is assumed. The following languages are available:

Code Language
en English
es Spanish
fr French
ar Arabic
zh Chinese

Local Languages

Local language translations are available for some countries. Any call to the API can be prefixed with a language code to retrieve localized results where available. The following local languages are available:

Code Language
bg Bulgarian
de German
hi Hindi
id Indonesian
ja Japanese
km Khmer
ko Korean
mk Macedonian
mn Mongolian
pl Polish
pt Portuguese
ro Romanian
ru Russian
sq Albanian
th Thai
tr Turkish
uk Ukrainian
vi Vietnamese

A backslash followed by the country code after http://api.worldbank.org/v2/ in an API call gives localized results.

For example, to retrieve the country name of Vietnam in Vietnamese language you would use the following query: https://api.worldbank.org/v2/vi/country/vn

Note: The translated local language country and region names are not available for all countries.

Delimiters

Range: Use a colon : to indicate a range (for numeric values only). For example, 5:10 specifies the numeric value range from 5 to 10.

Logical AND: Use a semicolon ; to represent logical “AND”. For example, us;ge specifies the United States AND Georgia.

Responses

Retrieving indicator data about countries is one common use of the API.

For example, the following is a call for 2006 data on the GDP of Brazil: https://api.worldbank.org/v2/country/br/indicator/NY.GDP.MKTP.CD?date=2006

Response Format

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

Sample valid request response:

<wb:sources xmlns:wb="http://www.worldbank.org" page="1" pages="1" per_page="50" total="30">
<wb:source id="11">
	<wb:name>Africa Development Indicators</wb:name>
	<wb:description/>
	<wb:url/>
	<wb:dataavailability>Y</wb:dataavailability>
	<wb:metadataavailability>Y</wb:metadataavailability>
</wb:source>

Sample invalid request response:

1.

<wb:error xmlns:wb="http://www.worldbank.org">
<wb:message id="150" key="Language is not yet supported in the API">Response requested in an unsupported language.</wb:message>
</wb:error>

2.

<wb:error xmlns:wb="http://www.worldbank.org">
<wb:message id="120" key="Invalid value">The provided parameter value is not valid</wb:message>
</wb:error>

Note: See Error Codes for a full listing of possible errors.

Limitations

You cannot currently sort any requests. Generally results are returned in a reasonable order (i.e. 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

(thinking…)