HDX core concepts

Essential HDX concepts referenced throughout products and integrations.

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.

Profile Settings

API Tokens

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

Manage API Tokens

• 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 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 metadata API.

Finding a resource ID: Dataset page

You can locate a resource’s unique ID directly from its dataset page in the HDX UI. Each resource listed under Data and Resources displays its Resource ID beneath the title. Clicking the copy icon next to the ID will copy the full UUID to your clipboard, making it easy to use in scripts, API calls, or downstream analysis.

This is the quickest way to retrieve the exact identifier for a resource you want to query programmatically.

Resource ID

Finding a resource ID: HDX Metadata API

For predictable dataset names, you can also access resource_ids through the HDX metadata 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 metadata API (see cookbook above) which can also generate the dataset name.

   1. Example: https://data.humdata.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://data.humdata.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:

   

   resource_id