About the Climate Data API

The Climate Data API provides programmatic access to most of the climate data used on the World Bank’s Climate Change Knowledge Portal. Web developers can use this API to access the knowledge portal’s data in real time to support their own applications, so long as they abide by the World Bank’s Terms of Use.

About the Data

Except as noted, all the data in the Climate Data API are derived from 15 global circulation models (GCMs), the most comprehensive physically-based models of climate change available and used by the Intergovernmental Panel on Climate Change (IPCC) 4th Assessment Reports. The models simulate the response of the global climate system to increasing greenhouse gas concentrations. The data in the Climate Data API have been aggregated to both the country and basin levels, as explained below.

Note these data are modeled estimates of temperature and precipitation changes in different time periods under different GCMs and scenarios. They include changes for future time periods and also as “backcasting” (model representations of the past) set for past time periods. The latter should not be confused with any instrumental or observed data.

The Basic Request

The Climate Data API uses REST-based requests, in which the general form looks like this:

http://climatedataapi.worldbank.org/climateweb/rest/v1/country/type/var/start/end/ISO3[.ext]

All boldface variables except for ext in this instance are required. Note that all climate data API requests begin with http://climatedataapi.worldbank.org/climateweb/rest/, so for the sake of legibility, this portion of the URL will be assumed and omitted in the remaining code samples in this documentation.

type is one of:

mavg

Monthly average

annualavg

Annual average

manom

Average monthly change (anomaly).  The control period is 1961-1999 for temperature and precipitation variables, and 1961-2000 for derived statistics.

annualanom

Average annual change (anomaly). The control period is 1961-1999 for temperature and precipitation variables, and 1961-2000 for derived statistics.

var is one of:

pr

Precipitation (rainfall and assumed water equivalent), in millimeters

tas

Temperature, in degrees Celsius

The start and end time period variables must be paired as follows (note that past time periods are estimated and not actual values, as described previously):

Past

start end

1920

1939

1940

1959

1960

1979

1980

1999

Future

start end

2020

2039

2040

2059

2060

2079

2080

2099

ISO3 is an ISO3 country code, indicating the country for the data request.

ext is optional, and indicates the response type:  CSV, JSON or XML (the default is JSON). For JSONP support, add the query parameter "?callback=handler" where "handler" is the name of your callback function.

Basin-level Requests

Basin-level requests are structured similar to the country level, substituting “basin” for “country” and a basin ID for the ISO3 country code:

/v1/basin/type/var/start/end/basinID[.ext]

basinID is a number from 1 to 468 that represents a regional river basin somewhere in the world.  River basins were calculated based on definitions obtained from waterbase.org (using the level 2 boundaries). Click here for a complete basin map, or use the KML interface to get basin definitions that can be integrated with any mapping application that supports KML.

Response Format

For any request, the climate data API will return one or more objects or rows, each representing a unique combination of attributes such as GCM and SRES scenario for the requested country (or basin) and time period.  For monthly data requests, each object contains a 12-value array with one value for each month (January-December).  For annual requests, each object contains a single-value array representing an average year.  Here is a typical monthly data response in XML format:

<list>
  <domain.web.MonthlyGcmDatum>
    <scenario>a2</scenario>
    <gcm>bccr_bcm2_0</gcm>
    <variable>pr</variable>
    <monthVals>
      <double>185.9119307</double>
      <double>179.4912687</double>
      <double>201.9563387</double>
      <double>177.0913426</double>
      <double>141.9072026</double>
      <double>75.73041729</double>
      <double>25.36077901</double>
      <double>19.56156441</double>
      <double>46.01293487</double>
      <double>120.6003451</double>
      <double>164.9925405</double>
      <double>213.0492542</double>
    </monthVals>
    <fromYear>2020</fromYear>
    <toYear>2039</toYear>
  </domain.web.MonthlyGcmDatum>
  <domain.web.MonthlyGcmDatum>
    <scenario>a2</scenario>
    <gcm>cccma_cgcm3_1</gcm>
    <variable>pr</variable>
    <monthVals>
      <double>175.3399486</double>
      <double>149.1324675</double>
      <double>156.6887422</double>
      <double>112.9897196</double>
      <double>90.3763538</double>
      <double>68.36105859</double>
      <double>40.01162929</double>
      <double>37.79072858</double>
      <double>52.06211842</double>
      <double>88.35877702</double>
      <double>127.6709071</double>
      <double>159.1258626</double>
    </monthVals>
    <fromYear>2020</fromYear>
    <toYear>2039</toYear>
  </domain.web.MonthlyGcmDatum>
etc
</list>

And the same response in CSV:

GCM,var,scenario,from_year,to_year,Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec
bccr_bcm2_0,pr,a2,2020,2039,185.9119307,179.4912687,201.9563387,177.0913426,141.9072026,75.73041729,25.36077901,19.56156441,46.01293487,120.6003451,164.9925405,213.0492542
cccma_cgcm3_1,pr,a2,2020,2039,175.3399486,149.1324675,156.6887422,112.9897196,90.3763538,68.36105859,40.01162929,37.79072858,52.06211842,88.35877702,127.6709071,159.1258626
etc

Narrowing the Response

Optional parameters can reduce the API response by specifying a particular GCM and/or SRES scenario:

/v1/country/type[/GCM][/SRES]/var/start/end/ISO3
/v1/basin/type[/GCM][/SRES]/var/start/end/basinID

GCM is one of:

bccr_bcm2_0

BCM 2.0

csiro_mk3_5

CSIRO Mark 3.5

ingv_echam4

ECHAM 4.6

cccma_cgcm3_1

CGCM 3.1 (T47)

cnrm_cm3

CNRM CM3

gfdl_cm2_0

GFDL CM2.0

gfdl_cm2_1

GFDL CM2.1

ipsl_cm4

IPSL-CM4

microc3_2_medres

MIROC 3.2 (medres)

miub_echo_g

ECHO-G

mpi_echam5

ECHAM5/MPI-OM

mri_cgcm2_3_2a

MRI-CGCM2.3.2

inmcm3_0

INMCM3.0

ukmo_hadcm3

UKMO HadCM3

ukmo_hadgem1

UKMO HadGEM1

SRES is one of:

a2

A2 scenario

b1

B1 scenario

For example, this request will return a two-object response, one for each scenario:

/v1/country/mavg/bccr_bcm2_0/pr/2020/2039/bra

This request will return a 15-object response, one for each GCM:

/v1/country/mavg/a2/pr/2020/2039/bra

And this request will return a single-object response:

/v1/country/mavg/bccr_bcm2_0/a2/pr/2020/2039/bra

Limitations

The Climate Data API has a few limitations, owing to the nature and meaning of the underlying data:

  • Anomaly data types (manom and annualanom) are only relevant to future time periods. Using these parameters for time periods before 2000 will return empty responses.
  • SRES scenarios (a2 and b1) are only relevant to future time periods. Using these optional parameters for time periods before 2000 will return empty responses. (19XX time periods actually use an implied scenario “20c3m” which can substitute for 19XX time periods—but not 20XX time periods.  However, since the SRES parameter is optional, it’s typically easier to simply omit it from requests for 19XX time periods.)
  • “ingv_echam4” and “ukmo_hadgem1” models do not have B1 scenario data.

Ensemble Requests

The Climate Data API can also report GCM results as an “ensemble.”  Ensemble requests return results for the 10th, 50th (median) and 90th percentile values of all models together (15 models for the A2 scenario, and 13 for the B1 scenario), instead of individual model results.  Basic ensemble requests look like this:

/v1/country/type/ensemble/var/start/end/ISO3[.ext]
/v1/basin/type/ensemble/var/start/end/basinID[.ext]

Ensemble requests return one object or row for each scenario and percentile, for instance:

<list>
  <domain.web.MonthlyEnsembleDatum>
    <scenario>a2</scenario>
    <monthVals>
      <double>184.8479445634642</double>
      <double>173.72065899435358</double>
      <double>192.05951129440894</double>
      <double>147.28657264202167</double>
      <double>95.7940443047413</double>
      <double>53.750569196933505</double>
      <double>31.623741395705366</double>
      <double>27.20792244572352</double>
      <double>40.574594601853946</double>
      <double>88.40907575306669</double>
      <double>139.39022016525834</double>
      <double>171.49016152441982</double>
    </monthVals>
    <percentile>50</percentile>
    <fromYear>2020</fromYear>
    <toYear>2039</toYear>
  </domain.web.MonthlyEnsembleDatum>
  <domain.web.MonthlyEnsembleDatum>
    <scenario>b1</scenario>
    <monthVals>
      <double>96.57011374754501</double>
      <double>94.84967311294484</double>
      <double>96.58570285814521</double>
      <double>69.26159838447259</double>
      <double>41.933933816718856</double>
      <double>18.915518205953415</double>
      <double>8.900329730938152</double>
      <double>6.331185105651406</double>
      <double>9.890957490993722</double>
      <double>20.71550347253773</double>
      <double>44.2643146219512</double>
      <double>79.02006159840417</double>
    </monthVals>
    <percentile>10</percentile>
    <fromYear>2020</fromYear>
    <toYear>2039</toYear>
  </domain.web.MonthlyEnsembleDatum>
  <domain.web.MonthlyEnsembleDatum>
    <scenario>a2</scenario>
    <monthVals>
      <double>255.35870526748175</double>
      <double>238.33457315494644</double>
      <double>256.3129555355977</double>
      <double>211.1526817388968</double>
      <double>156.18315817403936</double>
      <double>95.76615161178418</double>
      <double>64.80494137569298</double>
      <double>61.21688124037099</double>
      <double>84.63393322767311</double>
      <double>151.53565569683118</double>
      <double>208.90886595395</double>
      <double>252.03567805331406</double>
    </monthVals>
    <percentile>90</percentile>
    <fromYear>2020</fromYear>
    <toYear>2039</toYear>
  </domain.web.MonthlyEnsembleDatum>
etc
</list>

As with basic requests, you may narrow the response by specifying a specific scenario (a2, b1), percentile (10, 50, 90), or both:

/v1/country/type/ensemble[/sres][/percent]/var/start/end/ISO3

Ensemble requests also have the same limitations as basic requests; that is, manom, annualanom, a2 and b1 only apply to future time periods.

Derived Statistics for Ensemble Requests

The Climate Data API can calculate and return several “derived” statistics, as defined in the table below.  Derived statistics take the place of the “var” parameter in the ensemble request, like this:

/v1/country/type/ensemble/stat/start/end/ISO3[.ext]
/v1/basin/type/ensemble/stat/start/end/basinID[.ext]

stat is one of:

tmin_means

Average daily minimum  temperature

degrees Celsius

tmax_means

Average daily maximum temperature

degrees Celsius

tmax_days90th

Number of days with maximum temperature above the control period’s 90th percentile (hot days)

days

tmin_days90th

Number of days with minimum  temperature above the control period’s 90th percentile (warm nights)

days

tmax_days10th

Number of days with maximum temperature below the control period’s 10th percentile (cool days)

days

tmin_days10th

Number of days with minimum  temperature below the control period’s 10th percentile (cold nights)

days

tmin_days0

Number of days with minimum  temperature below 0 degrees Celsius

days

ppt_days

Number of days with precipitation greater than 0.2 mm

days

ppt_days2

Number of days with precipitation greater than 2 mm

days

ppt_days10

Number of days with precipitation greater than 10 mm

days

ppt_days90th

Number of days with precipitation greater than the control period's 90th percentile

days

ppt_dryspell

Average number of days between precipitation events

days

ppt_means

Average daily precipitation

mm

Note that derived statistics only support two future time periods, both of which are different from those for other requests, and must be paired as follows:

Time Periods for Derived Statistics

start end

2046

2065

2081

2100

Additionally, the control period for comparisons (manom and annualanom) is 1961-2000 for all derived statistics.

As with ordinary ensemble requests, you may narrow the response by specifying a specific scenario (a2, b1), percentile (10, 50, 90), or both:

/v1/country/type/ensemble[/sres][/percent]/stat/start/end/ISO3

Historical Data

The Climate Data API provides access to historical temperature and precipitation data. These data are separate from the outputs of the GCMs, and they are based on gridded climatologies from the Climate Research Unit. Again, note that these data are proxies for temperature and precipitation, where modeling has been used to extrapolate estimates where instrumental (station) data were unavailable or unreliable, especially in the early 1900’s.

Historical data requests can be monthly, yearly, or decadal. Monthly requests look like this:

/v1/country/cru/var/month/ISO3[.ext]
/v1/basin/cru/var/month/basinID[.ext]

The data response indicates average monthly values (temperature or precipitation) for the specified country or basin. Country averages are for 1901-2009, while basin averages are for 1960-2009.

Yearly requests look like this:

/v1/country/cru/var/year/ISO3[.ext]
/v1/basin/cru/var/year/basinID[.ext]

The data response indicates average values for each available year: 1901-2009 for countries, and 1960-2009 for basins.

Decadal requests look like this:

/v1/country/cru/var/decade/ISO3[.ext]
/v1/basin/cru/var/decade/basinID[.ext]

The data response for decadal requests indicates average annual values for each available decade (1900 is the earliest decade for countries; 1960 for basins. Note that the year 1900 is not in the data set, so 1900 averages only 9 years instead of 10, starting with 1901).

KML Output

The Climate Data API can produce KML definitions for both countries and basins, which can be used in any map-based application that recognizes the KML format. This provides useful geospatial context for understanding the data, especially for basins. KML requests look like this:

/v1/country/kml/[/simplification]/[ISO3]
/v1/basin/kml/[/simplification]/[basinID]

The optional simplification value is a decimal value between 0 and 1 that specifies boundary resolution; 0 (the default) is the highest available resolution while 1 is the lowest. This option lets you request simpler and thus smaller boundaries at the expense of resolution. A value of 0.01 reduces output and complexity by roughly 50%; values above 0.05 begin to lose too much detail.

An alternative request returns a partial KML definition: the shape itself without the kml, Document or Placemark tags. This option may be useful for programmatically combining multiple requests into a single layer, or adding style information:

/v1/country/kmlpart/[/simplification]/[ISO3]
/v1/basin/kmlpart/[/simplification]/[basinID]

Help/Feedback

User Voice