Open data · Developer reference
WorldsAid API
Build research and civic tools with structured, source-linked crisis records. The public read API is versioned and read-only; it never exposes precise operational coordinates.
Download the OpenAPI 3.0 specification · Sesame transmission connector · Read the Humanitarian Gaps Report
Access and rate limits
University data labs, student researchers and civic-tech hackathons are welcome to request a free research key at contact@worldsaid.com. Include your project, institution or event, intended use, and an approximate request rate. Keys are read-only and must be kept server-side; do not place them in public browser code.
Send a key in the X-API-Key header or as a bearer token in Authorization. The current limit is 60 requests per minute per client key. Page size defaults to 25 and is capped at 100. Use the returned next_cursor for the next page. A 429 response includes Retry-After.
curl 'https://worldsaid.com/api/v1/public/crises?limit=25' \
-H 'X-API-Key: YOUR_READ_ONLY_KEY'Endpoints
GET /api/v1/public/crises
Lists published crisis records with source references, reported impact fields, update dates and generalized location data. Optional filters: type, region, status, limit and cursor.
GET /api/v1/public/funding-logs
Lists validated public funding-ledger entries, including agency, currency, amount, purpose, source URL and observation date. Optional parameters: limit and cursor.
Current coverage: WorldsAid has no validated funding-ledger entries published yet. The endpoint returns an empty data page until records pass source and validation review; this is not a zero-funding finding.
POST /api/v1/transmissions
Receives authenticated, source-linked leads for investigation, a possible new story, or a suggested update to an existing story. The endpoint validates and deduplicates each payload, preserves the original evidence links, and queues it for independent investigation and editorial review. A successful 202 response is a receipt only: submissions cannot publish or alter WorldsAid content directly.
Transmission access is issued privately to approved partners. It uses a bearer credential or a scoped RS256 JSON Web Token and, by default, gateway-verified mutual TLS. See the Sesame connector guide and downloadable reference client for the implemented handshake.
Unauthenticated requests return 401. Invalid parameters return 400; rate limits return 429. Crisis response locations are generalized; no exact operational site coordinates are exposed. The API does not bypass the source, date or verification notes on each record.
Data licence and attribution
WorldsAid original data: WorldsAid’s original compilation, harmonized fields, and authored analysis made available through this API are offered under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).
Third-party material: This licence does not relicense material owned by linked source publishers or other third parties. Each record’s source links, stated terms, and attribution remain in force. Reusers are responsible for checking the rights that apply to each source and for not implying endorsement by WorldsAid or a cited organization.
When redistributing, retain the record identifier, source URL, observation and retrieval dates, verification status, and any stated uncertainty. Identify modifications and keep source-reported figures distinct from calculations or your own analysis.
Suggested citation: WorldsAid, “[record title],” record [ID], observed [date], accessed [date], [record URL]; original source: [source URL].
Research and responsible reuse
- Use stable record IDs and preserve older observations when a figure changes.
- Do not combine incompatible definitions, time periods, or geographic scopes into a single total.
- Separate source-reported facts from calculations, estimates and interpretation.
- Do not try to identify or map protected people or operational locations from generalized coordinates.
- Send corrections and dataset questions to contact@worldsaid.com.
Schema and change policy
API paths use the /api/v1/ version prefix. Additive fields may be introduced within a version. A breaking change requires a new version and published migration notes. The downloadable OpenAPI file documents the current request and response contract.