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:

var is one of:

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):

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:

SRES is one of:

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:

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:

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]