Documentation

Quick start

Static facts work without a key:

curl https://citedtravel.com/v1/countries/JP/power
curl "https://citedtravel.com/v1/power/compat?from=GB&to=US"
curl "https://citedtravel.com/v1/countries/JP/holidays?from=2026-12-20&to=2027-01-10&lang=ja"

API keys

Entry requirements and trip briefs need a key. Create a free key (shown once):

curl -X POST https://citedtravel.com/v1/keys -H 'content-type: application/json' \
  -d '{"email":"you@example.com","accept_terms":true}'

Send it as Authorization: Bearer ct_live_… or X-API-Key. Paid plans (Builder, Pro) are coming soon; during the soft launch the billing endpoints answer 503.

Languages

Add lang (BCP 47) or send Accept-Language. Supported: en (default), ja, zh-Hans (also zh, zh-CN, zh-SG) and zh-Hant (also zh-TW, zh-HK, zh-MO). A field name with a sibling name_i18n is resolved to your language, and name_lang tells you which language was served. When there is no localized value we fall back to English, never to the other Chinese script. Verbatim official quotes are never translated.

Endpoints

Full schema: OpenAPI 3.1.

Entry pilot

Short tourist stays for GB, US and JP passport holders, taken from each passport country's official travel advice. For travel to Japan, Japan's own visa-exemption list is used as well. Answers include status, max_stay_days, verbatim quotes (authoritative, in the original language), confidence, official_links, an advisory and not_a_verdict. They are decision support only. Show the advisory and the links to your users.

MCP server

Remote MCP over Streamable HTTP at https://citedtravel.com/mcp. Tools: resolve_country, get_country_facts, check_power_compatibility, get_emergency_numbers, get_tipping_norms, get_public_holidays, check_entry_requirements, get_trip_brief, list_recent_changes. All of them are read-only.

{
  "mcpServers": {
    "citedtravel": {
      "url": "https://citedtravel.com/mcp",
      "headers": { "Authorization": "Bearer ct_live_…" }
    }
  }
}

x402 pay-per-call (live, USDC on Base)

No key needed. When a call needs payment (entry lookups and trip briefs without a key, or static calls past the keyless limit), the API answers 402 with a PAYMENT-REQUIRED header (x402 v2, base64 JSON): scheme exact, network eip155:8453 (Base mainnet), asset USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913. Retry with a PAYMENT-SIGNATURE header; the response carries PAYMENT-RESPONSE with the settlement transaction. Over MCP, send the payment in _meta["x402/payment"] and read _meta["x402/payment-response"]. Prices: $0.005 per static call, $0.01 per entry lookup, $0.02 per trip brief. Payments are verified and settled through the Coinbase CDP facilitator. We prepare the response before settling and never settle for a request we cannot answer (for example an unsupported passport). Settled payments are final and non-refundable: on-chain transfers cannot be reversed.

Limits and errors

Keyless: 60 requests/min per IP. Free key: 1,000/month (50 entry lookups) and 60/min. Builder (coming soon): 100,000/month and 600/min. Pro (coming soon): 1,000,000/month and 3,000/min. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Errors are RFC 9457 application/problem+json.

Fact model

Each fact has value, sources[] (publisher, url, license, retrieved_at, quote or source_value), cross_checks[], last_verified, next_review_due, confidence {score, level, reasons}, attribution[] and, where available, localization.

Licensing and attribution

Values come only from sources that allow commercial reuse: CC0, public domain, OGL v3, Japan's Public Data License 1.0, MIT, the Unicode License and attributed CC BY. When you display facts, show the strings in each response's attribution field. Share-alike datasets are used only to cross-check values and are never redistributed. The full register is at /v1/sources.