# Travel Advisory API Documentation

Base URL: `https://api.traveladvisory.io/v1`

## Authentication

All requests require an API key passed via the `Authorization` header:

```
Authorization: Bearer ta_live_your_key_here
```

Get your API key from [traveladvisory.io/dev/api/pricing](https://traveladvisory.io/dev/api/pricing).

## Rate Limits

| Tier | Monthly Requests | Per Minute | Price |
|------|-----------------|------------|-------|
| Free | 250 total | 10 req/min | Free |
| Builder | 5,000/mo | 60 req/min | $29/mo |
| Pro | 25,000/mo | 200 req/min | $79/mo |
| Scale | 100,000/mo | 500 req/min | $199/mo |

Rate limit headers are included in every response:
- `X-RateLimit-Limit` — monthly quota
- `X-RateLimit-Remaining` — requests remaining this month
- `X-RateLimit-Reset` — Unix timestamp when the quota resets

---

## Core Advisory

### GET /v1/advisory

Full advisory data for a country. Includes State Department level, reasons, restricted areas, entry/exit requirements, and area-specific warnings.

**Parameters:**
- `code` (required) — ISO 3166-1 alpha-2 country code (e.g., "CO", "JP")

```bash
curl -H "Authorization: Bearer ta_live_..." \
  "https://api.traveladvisory.io/v1/advisory?code=CO"
```

Returns advisory level (1-4), advisory text, restricted areas, entry/exit info, and source timestamps.

### GET /v1/countries

Returns all 195 countries with their ISO code, name, flag emoji, and current advisory level.

```bash
curl -H "Authorization: Bearer ta_live_..." \
  "https://api.traveladvisory.io/v1/countries"
```

Returns array of country objects. Each includes code, name, flag, and advisory level.

### GET /v1/countries-by-level

All countries at a specific advisory level. Useful for building maps or filtering dashboards.

**Parameters:**
- `level` (required) — Advisory level: 1 (Exercise Normal Precautions), 2 (Exercise Increased Caution), 3 (Reconsider Travel), 4 (Do Not Travel)

```bash
curl -H "Authorization: Bearer ta_live_..." \
  "https://api.traveladvisory.io/v1/countries-by-level?level=4"
```

Returns array of countries matching the requested advisory level.

### GET /v1/changes

Track advisory level changes over a date range. Defaults to the last 7 days if no dates are provided.

**Parameters:**
- `since` (optional) — Start date in YYYY-MM-DD format (default: 7 days ago)
- `until` (optional) — End date in YYYY-MM-DD format (default: today)

```bash
curl -H "Authorization: Bearer ta_live_..." \
  "https://api.traveladvisory.io/v1/changes?since=2026-03-01&until=2026-03-10"
```

Returns array of change objects with country, previous level, new level, and change date.

---

## Country Intelligence

### GET /v1/political-stability

World Bank Worldwide Governance Indicators. Six dimensions: rule of law, control of corruption, political stability, government effectiveness, voice and accountability, regulatory quality.

**Parameters:**
- `code` (required) — ISO 3166-1 alpha-2 country code

```bash
curl -H "Authorization: Bearer ta_live_..." \
  "https://api.traveladvisory.io/v1/political-stability?code=BR"
```

Returns six governance indicators, each scored from approximately -2.5 (weak) to +2.5 (strong).

### GET /v1/geography

Geographic information for a country.

**Parameters:**
- `code` (required) — ISO 3166-1 alpha-2 country code

```bash
curl -H "Authorization: Bearer ta_live_..." \
  "https://api.traveladvisory.io/v1/geography?code=AU"
```

Returns geographic data including region, subregion, coordinates, and borders.

### GET /v1/culture

Cultural data for a country.

**Parameters:**
- `code` (required) — ISO 3166-1 alpha-2 country code

```bash
curl -H "Authorization: Bearer ta_live_..." \
  "https://api.traveladvisory.io/v1/culture?code=IT"
```

Returns cultural information including languages, religions, customs, and etiquette.

### GET /v1/economy

Economic data for a country.

**Parameters:**
- `code` (required) — ISO 3166-1 alpha-2 country code

```bash
curl -H "Authorization: Bearer ta_live_..." \
  "https://api.traveladvisory.io/v1/economy?code=DE"
```

Returns GDP, inflation, currency, trade data, and economic indicators.

### GET /v1/demographics

Population and demographic information for a country.

**Parameters:**
- `code` (required) — ISO 3166-1 alpha-2 country code

```bash
curl -H "Authorization: Bearer ta_live_..." \
  "https://api.traveladvisory.io/v1/demographics?code=NG"
```

Returns population, age distribution, urbanization, literacy, and life expectancy.

---

## Health & Safety

### GET /v1/vaccinations

Required and recommended vaccinations, malaria information, disease risks, and active health notices for a country.

**Parameters:**
- `code` (required) — ISO 3166-1 alpha-2 country code

```bash
curl -H "Authorization: Bearer ta_live_..." \
  "https://api.traveladvisory.io/v1/vaccinations?code=KE"
```

Returns required_vaccines, recommended_vaccines, malaria_info, disease_risks, and health_notices arrays.

### GET /v1/traveler-impact

Risk assessment broken down by traveler type: solo, business, family, and remote worker. Includes consular support availability and severity scores.

**Parameters:**
- `code` (required) — ISO 3166-1 alpha-2 country code

```bash
curl -H "Authorization: Bearer ta_live_..." \
  "https://api.traveladvisory.io/v1/traveler-impact?code=TH"
```

Returns per-type risk profiles with severity scores, consular support info, and specific recommendations.

### GET /v1/packing-list

Suggested packing list items based on country conditions, climate, and advisory level.

**Parameters:**
- `code` (required) — ISO 3166-1 alpha-2 country code

```bash
curl -H "Authorization: Bearer ta_live_..." \
  "https://api.traveladvisory.io/v1/packing-list?code=IS"
```

Returns categorized packing suggestions based on destination conditions.

---

## Bulk & Comparison

### GET /v1/compare

Compare up to 4 countries side by side. Returns advisory data, stability indicators, and health info for each country in a single response.

**Parameters:**
- `codes` (required) — Comma-separated ISO codes, 2-4 countries (e.g., "CO,JP,DE,TH")

```bash
curl -H "Authorization: Bearer ta_live_..." \
  "https://api.traveladvisory.io/v1/compare?codes=CO,JP,DE"
```

Returns an object keyed by country code, each containing full advisory and risk data.

---

## Data Sources

| Source | What It Covers | Update Frequency |
|--------|---------------|-----------------|
| U.S. State Department | Advisory levels, restricted areas, entry requirements | Daily |
| CDC | Vaccinations, disease risks, travel health notices | Daily |
| World Bank WGI | 6 governance indicators (rule of law, corruption, etc.) | Daily |
| Freedom House | Available on website only (not included in API) | N/A |
| Wikipedia | Geography, culture, economy, demographics | Daily |

All data is refreshed via automated pipeline and cached with 6-hour revalidation.

---

## Error Handling

All errors return JSON with a `message` field:

```json
{
  "error": true,
  "message": "Invalid country code: XX"
}
```

Common HTTP status codes:
- `200` — Success
- `400` — Bad request (missing or invalid parameters)
- `401` — Unauthorized (missing or invalid API key)
- `429` — Rate limit exceeded
- `500` — Internal server error

---

Full documentation: [traveladvisory.io/dev/api/docs](https://traveladvisory.io/dev/api/docs)