Accessing HDX by API

| January 11, 2021

If you need to use another language or simply want to examine dataset metadata in detail in your web browser, then you can use CKAN's RESTful API, a powerful, RPC-style interface that exposes all of CKAN's core features to clients.


| January 11, 2021

If you wish to read data from HDX for analysis in R, then you can use the rhdx package. The goal of this package is to provide a simple interface to interact with HDX. Like the Python API, it is a wrapper around the CKAN REST API. rhdx is not yet fully mature and some breaking changes are expected.


| January 11, 2021

The recommended way of developing against HDX is to use the HDX Python API. This is a mature library that supports Python 2.7 and 3 with tests that have a high level of code coverage. The major goal of the library is to make pushing and pulling data from HDX as simple as possible for the end user. There are several ways this is achieved. It provides a simple interface that communicates with HDX using the CKAN Python API, a thin wrapper around the CKAN REST API. The HDX objects, such as datasets and resources, are represented by Python classes. This should make the learning curve gentle and enable users to quickly get started with using HDX programmatically. For example, to read a dataset and get its resources, you would simply do:

from hdx.hdx_configuration import Configuration 
from hdx.data.dataset import Dataset
Configuration.create(hdx_site='prod', user_agent='A_Quick_Example', hdx_read_only=True)'
dataset = Dataset.read_from_hdx('novel-coronavirus-2019-ncov-cases')
resources = dataset.get_resources()

There is library API-level documentation available online.
If you intend to push data to HDX, then it may be helpful to start with this scraper template which shows what needs to be done to create datasets on HDX. It should be straightforward to adapt the template for your needs.


| January 11, 2021

HDX has a RESTful API largely unchanged from the underlying CKAN API which can be used from any programming language that supports HTTP GET and POST requests. However, the terminology that CKAN uses is a little different to the HDX user interface. Hence, we have developed wrappers for specific languages that harmonise the nomenclature and simplify the interaction with HDX.
These APIs allow various operations such as searching, reading and writing dataset metadata, but not the direct querying of data within resources which can point to files or urls and of which there can be more than one per dataset.


| January 11, 2021

This section contains information for developers who want to write code that interacts with the Humanitarian Data Exchange (HDX) and the datasets it contains. Anything that you can do by way of the HDX user interface, you can do programatically by making calls to the API and you can do a lot more. Typical uses of the API might be to script the creation and update of datasets in HDX or to read data for analysis and visualisation.