Testing: Core Concepts

Essential HDX concepts referenced throughout products and integrations

Note: This material is for alpha testing of a new HDX API endpoint built on CKAN's DataStore. It is not yet official documentation.

API Tokens

An API token is a unique key that authenticates users when making requests to HDX programmatically. It works like a password for the API, allowing you to create, update, or delete data depending on your permissions. Permissions are dependent on your level of access to various organizations (admin, editor, or member).

API tokens are connected to your HDX account and must be kept secure. Never share them publicly as they also allow write functionality.

Creating an HDX API Token

• Sign into HDX data.humdata.org.

• Navigate to your profile settings.

  

  
• Select “Manage API tokens”, and then generate your token.

  
• Copy your token (you will not be able to view it again) and save it either in your password manager or other secure location.

Data Resources

On HDX, a data resource is an individual data file or API endpoint that belongs to a dataset. Each dataset can contain one or more resources, for example a CSV file, Excel spreadsheet, shapefile, or an API feed. Resources are the actual data objects that users download or query.

To understand how resources fit into the overall structure of HDX, it helps to see their relationship to datasets and organizations:

Relationship of HDX Entities

Organization

└── Dataset

└── Resource(s)

• Organization: The publisher or owner of data (e.g., OCHA).

• Dataset: A collection of related information published by an organization (e.g., “Food Prices in Kenya”).

• Resource: The actual data file or service within a dataset (e.g., CSV file of market prices, shapefile of locations).

Each available HDX resource is identified by a unique resource ID, which you’ll need to include in API requests. Resource IDs are the the form of a 36 character UUID, for example:

f3f203bf-d29b-4b88-a724-25ab32a67543

You can find a resource ID through the dataset page UI, or by using the HDX CKAN API.

Finding a Resource ID: HDX CKAN API

For predictable dataset names, you can also access resource_ids through the HDX CKAN API endpoint which allows you to search the metadata of the data in our catalogue. See instructions below:

1. Find the dataset name: Go to the dataset page and find the name in the URL. You can also search using the HDX CKAN API (see cookbook above) which can also generate the dataset name.

   1. Example: https://blue.demo.data-humdata-org.ahconu.org/dataset/zwe-rainfall-subnational

2. Retrieve package and resource metadata: Use the package_show endpoint to fetch details about the dataset, including all its associated resources and the id. See example below.

   1. Example: https://blue.demo.data-humdata-org.ahconu.org/api/3/action/package_show?id=zwe-rainfall-subnational

3. Locate the resource in the response: From the response, identify the resource that corresponds to the structured data you're interested in. There you will find the resource_id.

   1. Example: