# Travel Risk Intelligence API

> A REST API for real-time travel safety data: government travel advisories, natural
> disaster alerts, armed-conflict events and composite country risk scores for 229
> countries and territories. Aligned with ISO 31030 (travel risk management).

Base URL: https://api.travelriskapi.com
Human docs: https://travelriskapi.com/#docs
OpenAPI spec: https://api.travelriskapi.com/openapi.json
Interactive docs: https://api.travelriskapi.com/docs

## Getting a key

Free tier: 100 requests/day, no credit card.

```
curl -X POST https://api.travelriskapi.com/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'
```

The key is returned in the response and emailed. Send it on every request as the
`X-API-Key` header.

## Core endpoints

- `GET /api/v1/countries` — all countries with advisory level and risk score
- `GET /api/v1/countries/codes` — every valid country code in one response
- `GET /api/v1/countries/{iso}` — one country; accepts alpha-3 (USA) or alpha-2 (US)
- `GET /api/v1/risk-score/{iso}` — composite 1–5 risk score with calculation breakdown
- `GET /api/v1/alerts` — active disaster/hazard alerts; filters: `severity`,
  `alert_type`, `country_iso`, `days` (1–365), `skip`, `limit` (max 1000)
- `GET /api/v1/conflicts` — armed conflict and unrest events, rolling 30-day window
- `GET /api/v1/advisories` — government advisories grouped by country, with the
  maximum level across three independent government sources
- `GET /api/v1/usage` — the caller's own consumption
- `GET /api/v1/billing/plans` — current plans and credit packs
- `GET /api/v1/health` — service health

## Example

```
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.travelriskapi.com/api/v1/alerts?severity=Critical&days=7&limit=50"
```

Every list response includes `total`, `skip`, `limit`, `data`, plus
`data_updated_at` (the newest record held) and `generated_at`.

## Data and refresh cadence

- Government travel advisories from three national agencies — refreshed daily
- Natural disaster and severe-weather alerts from five sources — every 6 hours
- Armed-conflict / unrest events — every 15 minutes
- Coverage: 229 countries and territories, ~19,000 active alerts

Upstream source names are presented as neutral labels (`agency-1`, `weather`,
`seismic`) rather than brand names.

## Plans

| Plan | Price | Requests/day |
|---|---|---|
| Free | $0 | 100 |
| Pro | $99/month | 10,000 |
| Enterprise | $499/month | unlimited |

Prepaid credits from $10 (10,000 requests) are also available and are consumed only
after the daily quota is used up. Subscriptions can be cancelled at any time from the
customer dashboard.

## Limits and conventions

- Authentication: `X-API-Key` header, required on all `/api/v1/*` endpoints
- Two limits apply: a per-minute burst limit and a daily quota; both return HTTP 429
  with a `Retry-After` header. The daily counter resets at 00:00 UTC.
- Quota state is reported on every response via `X-Quota-Limit`, `X-Quota-Used`,
  `X-Quota-Remaining` and `X-Credits-Balance`
- Pagination via `skip` / `limit`, maximum 1000 records per page; `total` is always
  returned, so a full export of ~19,000 alerts takes 20 requests
- Country codes: ISO 3166-1 alpha-3 preferred, alpha-2 accepted
- Responses are gzip/zstd compressed when the client advertises support

## Changelog

https://travelriskapi.com/changelog — every API change, including added fields.
API keys do not expire.

## Contact

support@travelriskapi.com