Find UNdata on Facebook Follow UNdata on Twitter Please send us your feedback

Using UNdata API

About UNdata API

UNdata API provides dynamic, programmatic access to data within the UNdata platform. Developers can use the API to dynamically query UNdata to obtain the latest data and display the result on a Web page, download to local storage for further processing, etc.

UNdata API is powered by Eurostat’s SDMX Reference Infrastructure (SDMX-RI). The API is implemented as a SOAP Web Service that can be used to query the datamarts using the SDMX standard. The API is governed by UNdata Terms of Use.

How To Use UNdata API

  1. To use UNdata API, you first need to create an SDMX Query. This is an XML document that defines query parameters in accordance with the dataset you intend to retrieve. Queries can be easily created with SDMX Browser. Use this tool to browse available dataflows and define a query, then use the Download Query link to obtain the query as an XML file.

  2. To retrieve the data, use HTTP POST to submit SDMX query created at step 1 to the UNdata SOAP Web Service at http://data.un.org/ws/NSIStdV20Service.asmx. In most cases, you can use GetCompactData or GetGenericData methods to query the datamarts. The Web service supports CORS and can be used in JavaScript.

  3. Results will be returned in an XML document structured in accordance with selected dataset’s Data Structure Definition.

FAQ

Where can I get more information about SDMX?

Will there be a REST web service for UNdata?

  • Yes, a RESTful web service will soon be rolled out.

Will there be JSON support?

  • Yes. SDMX implementation for JSON is currently being developed.

How do I create an SDMX query?

  • The easiest way to create an SDMX query is to use the SDMX Browser to view available dataflows and define a query, then use the Download Query link to get the query as SDMX-ML.

Why is API not available for all UNdata datamarts?

  • To be exposed through SDMX API, each datamart requires an SDMX Data Structure Definition (DSD). We are in the process of mapping UNdata datamarts to available DSDs, as well as developing new DSD where required. API support will be gradually extended to further UNdata datamarts as DSDs and mappings are completed.

What is Data Structure Definition?

  • In SDMX, dataset structure and codes are defined prior to data exchange, just like a relational database structure needs to be defined before the database can be used. These structures are stored in a document called Data Structure Definition (DSD). To establish data dissemination, each UNdata datamart requires one or more DSDs which, as much as possible, should be internationally standardized. API is already provided for some datamarts for which DSDs are available. As more DSDs are developed, SDMX API will be enabled for other UNdata datamarts.

How do I get a Data Structure Definition associated with a dataflow?

  • Submit a RegistryInterface SDMX message to the QueryStructure method of the Web service to retrieve a DSD. Alternatively, you can use SDMX Browser: prepare a query, click Download SDMX-ML, and select SDMX-ML Structure file to return the DSD and partial codelists matching your query.

How is the data returned?

  • Datasets are returned as structured XML documents. Specific structure of each dataset is determined by its DSD as well as selected SDMX format (Compact, Cross-Sectional, or Generic).

Copyright © 2014 - Conditions of Use
United Nations Statistics Division
Version v0.14.6 Beta