License: CC BY 4.0 OpenAPI 3.1
Machine-readable specification for the Warnely Public API: a free, CORS-open, read-only REST API exposing the Warnely composite travel-safety dataset for 180 countries.
The canonical spec is served at https://warnely.com/openapi.json — that is the URL to use for production tooling. This repository mirrors the spec for GitHub-based discovery, version pinning, and OpenAPI directory submissions.
| Surface | URL | Use |
|---|---|---|
| Interactive docs (canonical) | https://warnely.com/api-docs | Try every endpoint live in the browser |
| Raw OpenAPI 3.1 JSON | https://warnely.com/openapi.json | Production tooling, codegen, Postman import |
| GitHub Pages mirror | https://sn-lui.github.io/warnely-openapi/ | Swagger UI served from this repo |
| jsdelivr CDN (versioned) | https://cdn.jsdelivr.net/gh/sn-lui/warnely-openapi@v1.0.0/openapi.json | Version-pinned spec for CI builds |
| jsdelivr CDN (latest) | https://cdn.jsdelivr.net/gh/sn-lui/warnely-openapi@main/openapi.json | Always-fresh spec |
| Postman collection | postman-collection.json | One-click Postman import |
| Endpoint | Returns |
|---|---|
GET /api/v1/countries |
Compact list of all 180 countries (iso2, iso3, name, region, risk_score, risk_tier, flag). Optional ?region= filter. |
GET /api/v1/countries/{iso} |
Full country snapshot: composite score, six-category risk breakdown, UK FCDO + US State Department advisories, drug-law tier, LGBTQ+ legal status, women's-safety rating, Global Peace Index rank, quick facts. |
GET /api/v1/methodology |
Composite formula (50% editorial + 30% authority + 15% structural + 5% live), component weights, source list, tier boundaries, review cadence. |
GET /api/v1/incidents/recent |
Last 50–200 incidents from the Warnely safety wire (Reuters, BBC, AP, AFP, USGS, GDACS, ReliefWeb). Optional ?country= filter. |
- UK FCDO travel advice (gov.uk) — refreshed daily
- US State Department travel advisories (travel.state.gov) — refreshed daily
- Global Peace Index 2025 (Institute for Economics and Peace)
- World Bank Worldwide Governance Indicators
- WHO country health profiles
- Warnely incident wire (Reuters, BBC, AP, AFP, USGS, GDACS, ReliefWeb, Met Office, EA Floods, regional feeds)
# One-line verify curl -s "https://warnely.com/api/v1/countries/TH" | head # Generate a TypeScript client npx openapi-typescript "https://warnely.com/openapi.json" -o ./src/warnely-api.d.ts
Interactive docs in the browser: warnely.com/api-docs (Swagger UI, no signup needed).
Postman: import either way — postman-collection.json from this repo, or paste https://warnely.com/openapi.json into Postman's Import → Link dialog. Pre-generated collection is checked in here so you don't need to re-convert each time the live spec changes:
# Download the Postman collection curl -s "https://raw.githubusercontent.com/sn-lui/warnely-openapi/main/postman-collection.json" > warnely.postman_collection.json
- Auth: None required.
- Rate limit: 100 req/min/IP.
- CORS: Open (
*). - HTTPS: Required.
- Licence: CC BY 4.0. Attribute as "Warnely (warnely.com)".
/api/v1is a stability commitment. Breaking changes ship only behind/api/v2.- Field additions to existing endpoints are non-breaking and do not bump the version.
Zero-dependency, hand-written client libraries living in this repo:
- Python
clients/python/— Python 3.8+, stdlib-only.pip install "git+https://github.com/sn-lui/warnely-openapi.git#subdirectory=clients/python" - TypeScript / JavaScript
clients/typescript/— Node 18+, browsers, Deno, Bun.npm install "github:sn-lui/warnely-openapi#v1.0.0&path:/clients/typescript"
Both clients wrap the same four endpoints, raise typed errors, and ship with full README + reference docs.
- CSV + JSON dataset bundle on Hugging Face: Warnely/country-risk
- Medical-evacuation cost dataset at warnely.com/methodology/medevac (CC BY 4.0)
- Country safety guides at warnely.com/guides
- Methodology at warnely.com/guides/methodology
- This spec is regenerated whenever a breaking-or-additive change ships.
- Watch this repo, or subscribe to the Warnely advisory-changes RSS feed for data-side updates.
- For API behaviour questions or bug reports: open an issue here or email
hello@warnely.com. - For dataset corrections (e.g. an out-of-date advisory): use the per-country guide pages on
warnely.com/guides/<country>which carry a feedback link.
The OpenAPI specification in this repository is CC BY 4.0, the same licence as the data it documents.