Warnely Public API — OpenAPI 3.1 Specification

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.

Where to read the spec

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

What the API exposes

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.

Data sources

• 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)

Quick start

# 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

Terms

• Auth: None required.
• Rate limit: 100 req/min/IP.
• CORS: Open (*).
• HTTPS: Required.
• Licence: CC BY 4.0. Attribute as "Warnely (warnely.com)".

Stability

• /api/v1 is a stability commitment. Breaking changes ship only behind /api/v2.
• Field additions to existing endpoints are non-breaking and do not bump the version.

Client SDKs

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.

Companion data

• 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

Updates

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

Issues + feedback

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

Licence

The OpenAPI specification in this repository is CC BY 4.0, the same licence as the data it documents.