API documentation (SDMX-JSON)
About the API
The OECD provides access to datasets in the catalogue of OECD databases through a RESTful application programming interface (API) based on the SDMX-JSON standard. This allows a developer to easily call the API using simple RESTful URL programmatically.
What is the SDMX-JSON protocol?
OECD and other international organisations have been working on defining a new format of statistical data for use in internet-based electronic communications with its users and third parties. One of the main aims is to provide web developers easy access to statistical databases using common formats they may already be familiar with.
SDMX-JSON query structure
The API uses the standard SDMX REST API for queries. To create an SDMX-JSON query, a dataset identifier, a list of dimension item identifiers and some additional parameters must be supplied in an URL in the following format:
http://stats.oecd.org/SDMX-JSON/data/<dataset identifier>/<filter expression>/<agency name>[ ?<additional parameters>]
| Parameter | Use |
| dataset identifier | The identifier of the dataset to be queried. |
| filter expression |
Using their identifiers, the list of desired dimension values to be included in the result. To get all available dimension values, use the “all” keyword. Dimensions should be separated by a dot (“.”) and for each dimension its values should be separated by the plus sign (“+”). If for a particular dimension, no dimension value identifiers are specified, then all available values of this dimension will be returned. To get the list of dimensions and dimension values, use http://stats.oecd.org/restsdmx/sdmx.ashx/GetDataStructure/<dataset identifier>
|
| agency name | The agency maintaining the artefact to be returned (“all” returns artefacts maintained by any maintenance agency). |
| Optional Parameter | Use |
| startPeriod | The start period for which results should be supplied (inclusive). If not specified, data returned from the beginning. The value can be in the following formats:
|
| endPeriod | The end period for which results should be supplied (inclusive). If not specified, data is returned until the latest available date. |
| dimensionAtObservation | The identifier of the dimension to be attached at the observation level, or “AllDimensions”. If this parameter is not set, then the default value order is:
|
| detail | This attribute specifies the desired amount of information to be returned. Possible values:
|
UpdatedAfter parameter
| Optional Parameter | Use |
| UpdatedAfter |
If this parameter is used, the returned message includes the observations inserted/updated since that point in time. The format should be like:
The time is the local time of the web service. |
Query examples: DimensionAtObservation parameter for grouping or flat format
Example of allDimensions: Observations are returned in a flat list without any grouping.
The observations in the resulting message (without attributes) will contain:
"observations": {
"0:0:0:0:0": [1073508.5],
"0:0:0:0:1": [1078175.0],
(…)
}
The "0:0:0:0:0” numbers indicate the zero-based index of the dimension values. The orders of the dimensions and dimension values in the structure section of the SDMX-JSON response define the indexes. In the example query’s case, the dimensions are Location, Subject, Measure, Frequency and Time. So "0:0:0:0:0” means that the observation belongs to the first value of the Location dimension, the first value of the Subject dimension, and so on.
The example files in the Detail section do not use the dimensionAtObservation parameter, so by default the Time dimension is used.
The SDMX-JSON draft specification explains the data message syntax and fields in more detail.
What is SDMX-JSON format?
SDMX-JSON is a specific JSON-based format defined under the SDMX standard, which is used to describe and transmit statistical data. In SDMX the measurement of a phenomenon (e.g. a population count) is known as an “observation”. Observations are described and uniquely identified by a combination of “dimension” values (e.g. a country and a year). “Attributes” allow further adding useful information but do not help identifying statistical data (e.g. observation status). Observations of a same kind – identifiable by the same dimensions – are grouped into a “dataset”. The format also allows for an optional intermediate grouping of the observations for all values of one of the dimensions, called “series”. Specifically, the grouping of the observations for all available time periods is a so-called “time series” (e.g. the population counts for all years for a specific country). Similarly, groups can be made with any dimension. Alternatively, no grouping results in a flat list of all observations in the dataset. Descriptive information on the dataset, dimensions and attributes is called “structural metadata” and is returned within the “structure” part of the message.
The structural metadata for all and only the actually returned observations are included in the SDMX-JSON response message. If possible, in order to minimise repetition, each dimension/attribute is specified at the highest possible grouping level. Dimensions and attributes specified on dataset and series level have the same values for all observations throughout the dataset or series respectively.
To uniquely identify observations in the SDMX-JSON message, the indexes of the corresponding dimension values as defined in the “structure” part of the message at series and observation level are concatenated into the series’ or observation’s property name. Here, the indexes are ordered in the pre-defined order of dimensions as defined in the “structure” part of the message and separated between each other by a colon character.
The concrete values of attributes at series and observation level are also returned through their index as defined in the “structure” part of the message.
The following documents describe the SDMX-JSON standard in more detail:
- SDMX standard, most notably Section 7 – Web Services Guidelines,
- SDMX-JSON draft specification (You can also find a HTML version of the SDMX-JSON specification, sample messages and informative JSON Schema here: samples-tools.zip).
It is important to note that both the draft specification and the API implementation are continuously being improved; there are likely to be changes in the future to ensure the API is aligned to the standard.
Additionally, there are some known limitations and implementation details about the API, some of which have already been mentioned in the end user documentation.
SDMX-JSON query builder
Available datasets are listed in the catalogue of OECD databases with API. Queries can be built using the Export / Developer API feature of the dataset browser.
Query examples: Filter expression
If there is a dataset with identifier QNA and with four dimensions, Location, Subject, Measure and Frequency, the SDMX-JSON query would look like the following:
In this query, “QNA” is the dataset identifier, “AUS+AUT”, “GDP+B1_GE”, “CUR+VOBARSA” and “Q” are the identifiers for the requested dimension values for Location, Subject, Measure and Frequency respectively, and “all” is the key word to obtain data from any maintaining agency. The data is requested from the second quarter of 2009 to the fourth quarter of 2011 inclusive.
If the full list of countries is requested, then the “AUS+AUT” country identifiers can be replaced either by the full list of country identifiers separated by the plus sign:
or an empty string:
To retrieve all (unfiltered) observations of the dataset, use the following: http://stats.oecd.org/sdmx-json/data/QNA/all/all?startTime=2009-Q1&endTime=2011-Q4
Query examples: detail parameter
Example of SeriesKeysOnly: observations and attributes are omitted; everything else is the same as in the full version.
Known limitations and implementation details
The following are a list of known limitations at this time. Please be advised that as the standard evolves the list of limitations will be updated to reflect new features.
- Only anonymous queries are supported, there is no authentication
- Each response is limited to 1 000 000 observations
- Maximum request URL length is 1000 characters
- Only the data resource is supported which returns data and relevant structural metadata. To obtain structural metadata on its own please use the SDMX-ML API
- Cross-origin requests are supported by CORS headers and JSONP
- Unlike some other implementations the default response content type is application/vnd.sdmx.draft-sdmx-json+json;version=2.1;
- Dimensions and attributes with only one requested value are not yet moved to dataset level even though the draft specification (see example message) would allow this
- Errors are not returned in the JSON format but HTTP status codes and messages are set according to the Web Services Guidelines
- 401 Unauthorized is returned if a non-authorised dataset is requested
- The source (or Agency ID) parameter in the REST query is mandatory but the “ALL” keyword is supported
- Versioning is not supported: always the latest implemented version is used
- The explicitMeasure parameter is not supported
- Reordering the data is not supported
- The lastNObservations parameter is not supported
- Observations follow the time series (or import-specific) order even if dimensionAtObservation=AllDimensions is used
Terms and conditions
OECD databases and API service is offered subject to your acceptance of OECD terms and conditions.