Tools

11 tools for working with ReliefWeb humanitarian data:

Oversized records

The five reliefweb_get_* tools never truncate. Under a fixed byte budget they return the record whole; over it they return a complete section outline — every section, its real serialized size, and how to reach it — and a sections: [...] re-call returns exactly the named sections plus identity metadata. The re-call is self-contained: the record is re-fetched from its ID and sliced, so nothing has to be replayed. Both modes carry the same information in structuredContent and content[].

The resources always return the whole record — a resource read has no way to name sections, so reach for the tool when a record is too large.

Curated-profile archives

A country or disaster profile returns only what ReliefWeb currently curates in each of its three link lists. Each list also has an archive, thousands of entries deep for a long-running crisis — Syria carries 2,328 archived key content links and 120 archived appeals and response plans. reliefweb_get_country and reliefweb_get_disaster page that archive on request:

{ "iso3": "SYR", "archive": { "list": "keyContent", "offset": 0, "limit": 25 } }

The response replaces the profile with one page: the list it came from, the true total, how many entries it holds, its offset, the entries, and the next offset while more remain — absent once the page reaches the end. Lists are keyContent, appealsResponsePlans, and usefulLinks, named for the fields the active half lands on.

sections and archive are alternative modes and a call carrying both is rejected: sections slices the record, archive replaces it with a page. A record over the response budget still answers an archive call with the page — a page is bounded by limit and carries no record prose, so it never outlines.

reliefweb_search_reports

Search humanitarian reports on ReliefWeb with rich filtering.

• Full-text search across title, body, and key metadata fields
• Filtering by country (ISO3), disaster ID, format, theme, language, and source organization
• Date range filtering on source publication date — a bare 2024-01-15 is accepted alongside full ISO 8601
• Raw filter object for compound conditions not covered by named params
• Pagination via offset and limit (up to 1,000 per call)
• Format is a closed set: News and Press Release, Situation Report, Map, Infographic, Analysis, Other, Assessment, Manual and Guideline, Appeal, UN Document, Evaluation and Lessons Learned — matched ignoring case, spacing, and punctuation; anything else is rejected with the list
• include_archived has no effect here — reports have no archived class, so all of them are in scope by default
• Returns paginated summaries — use reliefweb_get_report to fetch full body text
• Rate limit: 1,000 calls/day

reliefweb_get_report

Fetch a single ReliefWeb report by its numeric ID with full body text.

• Full body HTML, all metadata, and file attachment URLs
• Use after reliefweb_search_reports to retrieve document content (10–100KB each)
• Over the response budget, returns a section outline instead; sections: ["body"] pulls the body back on its own
• Returns structured not_found when the ID doesn't exist

reliefweb_search_disasters

Search active and historical disasters on ReliefWeb.

• Filtering by disaster type (Earthquake, Flood, Cyclone, etc.), country, and status
• GLIDE number lookup for cross-system disaster correlation
• Date range filtering on disaster creation date — a bare 2024-01-15 is accepted alongside full ISO 8601
• Status values: alert, ongoing, past, alert-archive; multiple values comma-separated, matched ignoring case, spacing, and punctuation
• Optional include_archived=true to reach alert-archive entries, which the default preset hides
• Returns IDs for use with reliefweb_get_disaster and as disaster_id filter in reliefweb_search_reports

reliefweb_get_disaster

Fetch a disaster record by ReliefWeb numeric ID with full details.

• Full description, profile overview, affected countries, and GLIDE number
• Currently-active curated key content links from the ReliefWeb editorial team (the present set, not the full archive)
• Currently-active appeals and response plans linked to the disaster
• Currently-active useful external links curated by ReliefWeb editors
• Major disasters run to tens of KB of prose; over the response budget the record comes back as a section outline, and sections: ["description"] or sections: ["profileOverview"] pulls one narrative at a time
• archive: { list: "keyContent" } pages the archived entries each curated list leaves out

reliefweb_get_country

Fetch a country profile from ReliefWeb by ISO3 code.

• Situation overview text curated by OCHA editors
• Currently-active key content links maintained by ReliefWeb editors (the present curated set, not the full archive)
• Currently-active humanitarian appeals and response plans
• Currently-active useful external links for the country
• Country profiles are the authoritative situation summary for humanitarian responders
• archive: { list: "keyContent" } pages the archived entries each curated list leaves out — 2,328 of them for Syria
• Carries the same outline-and-sections behavior as the other detail tools, though an active-only profile is small enough that it rarely reaches the budget

reliefweb_list_countries

List all countries and territories tracked by ReliefWeb.

• Optional crisis_only=true to limit to active humanitarian situations (status ongoing)
• Returns ISO3 codes, status, and canonical URLs — use ISO3 with reliefweb_get_country
• Pagination up to 1,000 entries per call

reliefweb_search_jobs

Search humanitarian job listings on ReliefWeb.