Examples and use-cases

Python examples with tools and integrations

These examples show common tasks in Python. The full documentation at hdx-hapi.readthedocs.io has the same patterns in JavaScript, Node.js, and R. In every example, replace {your app identifier} with the identifier you generated in How to query HAPI.

A note on pagination. Queries are capped at 10,000 rows. Larger results are silently truncated to the first 10,000 with no warning, and a higher limit just returns a 422. Page through anything you don't know to be small: request pages until one comes back shorter than your page size.

1. Who is doing what where

List the organizations active in a country by querying operational presence. This example returns operational presence for Afghanistan. Add a sector filter, such as sector_name, to narrow the results to a single sector.

import json
from urllib import request

APP_IDENTIFIER = "{your app identifier}"
THEME = "coordination-context/operational-presence"
LOCATION = "AFG"
LIMIT = 1000

def fetch_all(base_url, limit):
    results = []
    idx = 0
    while True:
        offset = idx * limit
        url = f"{base_url}&offset={offset}&limit={limit}"
        with request.urlopen(url) as response:
            page = json.loads(response.read())["data"]
        results.extend(page)
        if len(page) < limit:
            break
        idx += 1
    return results

base_url = (
    f"https://hapi.humdata.org/api/v2/{THEME}"
    f"?location_code={LOCATION}"
    f"&output_format=json"
    f"&app_identifier={APP_IDENTIFIER}"
)

data = fetch_all(base_url, LIMIT)
print(f"Retrieved {len(data)} records")

2. Combine two sources for a food security snapshot

Since HAPI standardizes indicators across sources, you can pull food prices and food security phases for the same country and analyze them together, without learning two separate APIs. Query each sub-category with the same location_code, then join the results in your own code.

import json
from urllib import request

APP_IDENTIFIER = "{your app identifier}"
LOCATION = "AFG"
LIMIT = 1000

def fetch_all(base_url, limit):
    results = []
    idx = 0
    while True:
        offset = idx * limit
        url = f"{base_url}&offset={offset}&limit={limit}"
        with request.urlopen(url) as response:
            page = json.loads(response.read())["data"]
        results.extend(page)
        if len(page) < limit:
            break
        idx += 1
    return results

def get(theme):
    base_url = (
        f"https://hapi.humdata.org/api/v2/{theme}"
        f"?location_code={LOCATION}"
        f"&output_format=json"
        f"&app_identifier={APP_IDENTIFIER}"
    )
    return fetch_all(base_url, LIMIT)

food_prices = get("food-security-nutrition-poverty/food-prices-market-monitor")
food_security = get("food-security-nutrition-poverty/food-security")

3. Population by admin level, with pagination

This loop shows the paging pattern in full: it pulls the baseline population for a country and keeps requesting pages until a page comes back shorter than the limit, meaning it has everything. Use admin_level and the admin filters shown in the API reference to focus on a specific administrative level.

import json
from urllib import request
 
APP_IDENTIFIER = "{your app identifier}"
THEME = "geography-infrastructure/baseline-population"
LOCATION = "AFG"
LIMIT = 1000
 
def fetch_all(base_url, limit):
	results = []
	idx = 0
	while True:
    	offset = idx * limit
    	url = f"{base_url}&offset={offset}&limit={limit}"
    	with request.urlopen(url) as response:
            page = json.loads(response.read())["data"]
        results.extend(page)
    	if len(page) < limit:
            break
    	idx += 1
	return results
 
base_url = (
    f"https://hapi.humdata.org/api/v2/{THEME}"
    f"?location_code={LOCATION}"
    f"&output_format=json"
    f"&app_identifier={APP_IDENTIFIER}"
)
 
records = fetch_all(base_url, LIMIT)
print(f"Retrieved {len(records)} records")

4. Conflict events over time

Conflict event data goes back to 1997, so it is useful for a simple time series. Query the conflict events sub-category for a location and group the results by date in your own code. Once you have the data array, group by the date field to build a monthly or yearly trend.

import json
from collections import Counter
from urllib import request

APP_IDENTIFIER = "{your app identifier}"
THEME = "coordination-context/conflict-events"
LOCATION = "AFG"
LIMIT = 1000

def fetch_all(base_url, limit):
    results = []
    idx = 0
    while True:
        offset = idx * limit
        url = f"{base_url}&offset={offset}&limit={limit}"
        with request.urlopen(url) as response:
            page = json.loads(response.read())["data"]
        results.extend(page)
        if len(page) < limit:
            break
        idx += 1
    return results

base_url = (
    f"https://hapi.humdata.org/api/v2/{THEME}"
    f"?location_code={LOCATION}"
    f"&output_format=json"
    f"&app_identifier={APP_IDENTIFIER}"
)

events = fetch_all(base_url, LIMIT)

# Group by year to build a yearly trend.
by_year = Counter(e["reference_period_start"][:4] for e in events)
for year in sorted(by_year):
    print(year, by_year[year])

See it in action

For live examples built on HAPI, explore the data availability dashboard, and the example dashboard linked on Tools and integrations.

Do you have an example you’d like to share? Reach out to us!

Tools and integrations

You do not need to write code to use HAPI. These integrations and resources help you pull data into common tools.

• API sandbox: build and test a query and see the response.
• Dashboard: an example dashboard with key figures, charts, and a map for all countries in HAPI.