Warnely Developer API

Free, CORS-open, read-only REST endpoints for the 180-country travel-safety dataset and the Warnely incident wire. Designed to be useful from a notebook, a serverless function, or your terminal in under a minute.

# Get a single country
curl -s "https://warnely.com/api/v1/countries/TH" | head

Overview #

The Warnely API exposes the same dataset that powers the country guides at warnely.com/guides. All endpoints are read-only. Responses are plain JSON over HTTPS. CORS is open so the API is consumable from browser-based notebooks, static frontends, and serverless edge runtimes without a proxy.

The contract is versioned via the path prefix. /api/v1 is stable: breaking changes ship only behind /api/v2. Field additions to existing endpoints are non-breaking and will not bump the version.

Authentication and rate limits #

No authentication. The API is intended for low-volume programmatic use, citation in notebooks, and embedding in editorial pages. Rate limit is 100 requests per minute per IP, enforced by the upstream Express server. The RateLimit-* response headers report your remaining budget.

For higher volumes or commercial use cases, email hello@warnely.com with a short description of your project.

List countries #

Returns the compact record for every country in the Warnely dataset.

Query parameters

Example

# All 180 countries
curl "https://warnely.com/api/v1/countries"

# Just Latin America
curl "https://warnely.com/api/v1/countries?region=Latin%20America"

Response shape

{
  "count": 180,
  "methodology": "https://warnely.com/guides/methodology",
  "licence": "CC BY 4.0",
  "attribution": "Warnely",
  "countries": [
    {
      "iso2": "TH",
      "iso3": "THA",
      "name": "Thailand",
      "region": "Asia",
      "risk_score": 36,
      "risk_tier": "Exercise Increased Caution",
      "flag": "🇹🇭"
    }
  ]
}

Get a single country #

Full snapshot for one country, including the composite-score breakdown, the latest UK FCDO and US State Department advisories, structured drug-law tier, LGBTQ+ legal and social status, women's-safety rating, Global Peace Index rank, and Quick Facts (plug type, water safety, drive side).

Path parameters

Examples

# Thailand
curl "https://warnely.com/api/v1/countries/TH"

# JavaScript (browser or node)
const res = await fetch("https://warnely.com/api/v1/countries/JP");
const data = await res.json();
console.log(data.country.risk_score);

# Python
import requests
r = requests.get("https://warnely.com/api/v1/countries/IN")
print(r.json()["country"]["risk_tier"])

Methodology metadata #

Returns the composite formula, component weights, tier boundaries, source list, and review cadence. Useful for embedding alongside a country score in a research notebook or article so readers know exactly what they are reading.

curl "https://warnely.com/api/v1/methodology"

Response sample

{
  "composite": {
    "formula": "0.50 * editorial + 0.30 * authority + 0.15 * structural + 0.05 * live",
    "renormalised_when_missing": true,
    "scale": "0-100 (lower is safer)"
  },
  "components": {
    "editorial": { "weight": 0.5, "description": "..." },
    "authority": { "weight": 0.3, "description": "..." },
    "structural": { "weight": 0.15, "description": "..." },
    "live": { "weight": 0.05, "description": "..." }
  },
  "tiers": [...],
  "sources": [...]
}

Recent incidents #

Recent items from the Warnely incident wire. Sources include Reuters, BBC, AP, AFP, USGS earthquake feed, GDACS disaster alerts, ReliefWeb, Met Office severe weather, and several other safety-relevant feeds.

Query parameters

Examples

# Last 50 global incidents
curl "https://warnely.com/api/v1/incidents/recent"

# Last 20 incidents in Greece
curl "https://warnely.com/api/v1/incidents/recent?country=Greece&limit=20"

Errors #

All errors return a JSON body with two keys: error (a machine-readable code) and message (a human-readable explanation). HTTP status codes follow standard conventions.

Changelog #

Licence and attribution #

Dataset content served by this API is published under the Creative Commons Attribution 4.0 International licence (CC BY 4.0). You may use it commercially, modify it, and redistribute it, including in proprietary works. Attribution must read Warnely and link to warnely.com.

A suggested citation block for academic or notebook use:

Warnely (2026). Warnely Country Risk Dataset.
CC BY 4.0. https://warnely.com/guides/methodology

Found a bug, missing field, or want an endpoint that does not exist yet? Email hello@warnely.com. The dataset and code are also mirrored on Hugging Face and Kaggle if you prefer working with the static CSV.