Climate Data API

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 withhttp://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

Average monthly change (anomaly).  The control period is manom

1961­1999 for temperature and precipitation variables, and 1961­ 2000 for derived statistics.

Average annual change (anomaly). The control period is 1961­1999 for annualanom

temperature and precipitation variables, and 1961­2000 forderived statistics.

var is one of:

Precipitation (rainfall and assumed

pr

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:

       a2     bccr_bcm2_0     pr            185.9119307       179.4912687       201.9563387       177.0913426       141.9072026       75.73041729       25.36077901       19.56156441       46.01293487       120.6003451       164.9925405       213.0492542          2020     2039           a2     cccma_cgcm3_1     pr            175.3399486       149.1324675       156.6887422       112.9897196

      90.3763538       68.36105859       40.01162929       37.79072858       52.06211842       88.35877702       127.6709071       159.1258626          2020     2039    etc

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.

cccma_cgcm3_1,pr,a2,2020,2039,175.3399486,149.1324675,156.6887422,112.9897196,90.3763538,68.36105859,40.01162929,37 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

csiro_mk3_5

ingv_echam4

cccma_cgcm3_1

BCM 2.0

CSIRO Mark 3.5

ECHAM 4.6

CGCM 3.1 (T47)

cnrm_cm3

CNRM CM3

gfdl_cm2_0

GFDL CM2.0

gfdl_cm2_1

GFDL CM2.1

ipsl_cm4

IPSL­CM4

MIROC 3.2

microc3_2_medres

(medres)

miub_echo_g

ECHO­G

ECHAM5/MPI­

mpi_echam5

OM

mri_cgcm2_3_2a

inmcm3_0

MRI­ CGCM2.3.2

INMCM3.0

UKMO

ukmo_hadcm3

HadCM3

UKMO

ukmo_hadgem1

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:

       a2            184.8479445634642       173.72065899435358       192.05951129440894       147.28657264202167       95.7940443047413       53.750569196933505       31.623741395705366       27.20792244572352       40.574594601853946       88.40907575306669       139.39022016525834       171.49016152441982          50     2020     2039           b1            96.57011374754501       94.84967311294484       96.58570285814521       69.26159838447259       41.933933816718856       18.915518205953415       8.900329730938152       6.331185105651406       9.890957490993722       20.71550347253773       44.2643146219512       79.02006159840417     

    10     2020     2039           a2            255.35870526748175       238.33457315494644       256.3129555355977       211.1526817388968       156.18315817403936       95.76615161178418       64.80494137569298       61.21688124037099       84.63393322767311       151.53565569683118       208.90886595395       252.03567805331406          90     2020     2039    etc

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:

Average daily tmin_means

minimum  temperature

Average daily tmax_means

maximum temperature

degrees Celsius

degrees Celsius

Number of days with maximum tmax_days90th

temperature above the control period’s

days

90thpercentile (hot days)

Number of days with minimum  tmin_days90th

temperature above the control period’s

days

90thpercentile (warm nights)

Number of days with maximum tmax_days10th

temperature below the control period’s

days

10thpercentile (cool days)

Number of days with minimum  tmin_days10th

temperature below the control period’s

days

10thpercentile (cold nights)

Number of days tmin_days0

with minimum  temperature below

days

0 degrees Celsius

Number of days ppt_days

with precipitation greater than 0.2

days

mm

Number of days ppt_days2

with precipitation

days

greater than 2 mm

Number of days ppt_days10

with precipitation greater than 10

days

mm

Number of days with precipitation ppt_days90th

greater than the control period's 90th percentile

days

Average number of days between

ppt_dryspell

precipitation

days

events

Average daily

ppt_means

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 andannualanom) 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 areproxies 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]