API documentation (SDMX-ML)
About the Rest-SDMX API
The OECD provides access to datasets in the catalogue of OECD databases through a RESTful application programming interface (API) based on the SDMX-ML standard. This allows a developer to easily call the API using simple RESTful URL programmatically.
What is SDMX-ML protocol?
The SDMX Technical Standards Version 1.0 establishes an information model which describes aggregated statistical data sets and the structural metadata needed to exchange them in a standard fashion. Based on the SDMX information model, XML formats (SDMX-ML) are used for exchange of structural metadata, data sets and queries. Versions 2.0 and 2.1 build on this foundation established in version 1.0 to provide a higher degree of support for the SDMX information model, with an emphasis on data sharing in the form of a set of standard registry services interfaces.
Rest-SDMX service methods
| Method | Use |
|
GetKeyFamily/ |
Return structural metadata information about available datasets and their structure. |
| GetData |
Used to convey data in a non-data structure specific form. Each Data set in this message will have a related structure specification in the header, which states the data structure that the data conforms to and how the data is organised (i.e. the observation dimension). |
| GetSchema | Schema query is used to query SDMX compliant databases or web services for data structure specific schemas for the purpose of validating structured data. |
Rest-SDMX query structure
GetDataStructure Method
To create a datastructure query, a dataset identifier and agency name must be supplied in an URL in the following format:
http://stats.oecd.org/restsdmx/sdmx.ashx/{GetKeyFamily|GetDataStructure}/
<dataset identifier>/<agency name>[ ?<additional parameters>]
| Parameter | Use |
| dataset identifier | The identifier of the dataset to be queried. Can be set to “ALL” or a specific identifier. “ALL” returns available dataset lists. |
| agency name |
The agency maintaining the artefact to be returned. “All” returns artefacts maintained by any maintenance agency. The agency name for the OECD is “OECD”. |
| Optional Parameter | Use |
| format | Can be blank or SDMX-ML. If the format is set to blank then the SDMX-ML format is used as default. |
| querymessage | Not part of the standard. Boolean value. If set to “True” then it returns the Query message instead of result. Can be used to review/analyse the query message which will be sent to SDMX-ML service. |
Query examples:
Return data structure:
http://stats.oecd.org/restsdmx/sdmx.ashx/GetDataStructure/
QNA/all?format=SDMX-ML
Return query message:
http://stats.oecd.org/restsdmx/sdmx.ashx/GetDataStructure/
QNA/all?format=SDMX-ML&querymessage=true
GetData Method
To create a data query, the following parameters must be supplied in an URL in the following format: a dataset identifier, a list of dimension item identifiers and some additional parameters:
http://stats.oecd.org/restsdmx/sdmx.ashx/GetData/<dataset identifier>/<filter expression>/<agency name>[?<additional parameters>]
| Parameter | Use |
| dataset identifier | The identifier of the dataset to be queried. For example, QNA. |
| 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. The agency name for the OECD is “OECD”. |
| Optional Parameter | Use |
| format | Specify the format of the result. Can be set to “generic_v2” or “compact_v2”. If not specified then it uses the “generic_v2” as default. Compact version uses attributes instead of XML child nodes. |
| startPeriod/ startTime |
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/ endTime |
The end period for which results should be supplied (inclusive). If not specified, data is returned until the latest available date. The format is the same as for startPeriod/startTime |
| querymessage | Not part of the standard. Boolean value. If set to “True” then it returns the Query message instead of result. Can be used to review/analyse the query message which will be sent to SDMX-ML service. |
Query examples:
Return compact data: http://stats.oecd.org/restsdmx/sdmx.ashx/GetData/QNA/AUS+AUT.GDP+
B1_GE.CUR+VOBARSA.Q/all?startTime=2009-Q2&endTime=2011-Q4&format=compact_v2
Return query message: http://stats.oecd.org/restsdmx/sdmx.ashx/GetData/QNA/AUS+AUT.GDP+
B1_GE.CUR+VOBARSA.Q/all?startTime=2009-Q2&endTime=2011-Q4&querymessage=true
GetSchema Method
To create a schema query, a dataset identifier must be supplied in an URL in the following format:
http://stats.oecd.org/restsdmx/sdmx.ashx/GetSchema/<dataset identifier>
| Parameter | Use |
| dataset identifier | The identifier of the dataset to be queried. For example "QNA". |
Query examples:
Return schema: http://stats.oecd.org/restsdmx/sdmx.ashx/GetSchema/QNA
Specifics of the OECD implementation
The following are a list of specific OECD REST SDMX interface implementation details at this time. Please be advised that the list will be updated to reflect developments and/or new features of the SDMX standard.
- 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.
- Cross-origin requests are supported by CORS headers (read more about CORS http://www.html5rocks.com/en/tutorials/cors/).
- Errors are not returned in the result 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.
- 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.
- The retrieval of reference metadata is not supported at this time
Terms and conditions
OECD databases and API service is offered subject to your acceptance of OECD terms and conditions.