Read-only · no key needed · OpenAPI 3.1
TieredTravel API
A small read-only API over the same data the site renders: which cities have guides, which attractions have their own page, which walking routes are published. No authentication required, no signup.
If you want the content of a page rather than a list of what exists, do not stitch it back
together from these endpoints. Request the page itself with Accept: text/markdown and you
will get a clean Markdown rendering — the prose, the costs, the numbered walking route — at roughly a
fifth to a twenty-fifth of the tokens the HTML costs.
curl -H 'Accept: text/markdown' https://tieredtravel.com/destinations/barcelona
Usage terms for anything you fetch are declared as Content-Signal directives in robots.txt: search and AI grounding are welcome, model training is not.
AI assistants (MCP)
The same data is a remote Model Context Protocol server at https://tieredtravel.com/mcp
(Streamable HTTP, no key). Add it to Claude under Settings → Connectors → Add custom connector,
or to any client that takes a server URL:
{"mcpServers": {"tieredtravel": {"url": "https://tieredtravel.com/mcp"}}}
| Tool | Returns |
|---|---|
| destination_costs | What a day costs in a city at budget, mid-range and luxury, split into stay, food, transport and activities. |
| walking_route | A self-guided walking route, stop by stop, with what to know at each and real coordinates. |
| compare_destinations | Two cities side by side: daily cost at each tier, currency, language and best months. |
| find_destinations | Which cities the server knows, by country, continent or part of a name. |
Every figure comes from the published guides; a city the catalogue does not have is an error, never a guess. The server card is at /.well-known/mcp/server-card.json, and the same tools are an A2A agent at /.well-known/agent-card.json.
Discovery
The catalog follows RFC 9727
and is served as application/linkset+json.
/auth.md covers authentication in one fetch.
Endpoints
| Endpoint | Returns |
|---|---|
| GET /api/v1/destinations | Published cities. Takes ?limit= (default 50, max 500). Tier guides are not included. |
| GET /api/v1/destinations/{slug} | One city, with its tier guides and their daily cost breakdowns. Expect budget, midrange and luxury — plus, on some cities, a legacy business guide that no page on the site renders. |
| GET /api/v1/attractions | {dest_slug, thing_slug} for every attraction with its own guide page. |
| GET /api/v1/walks | {dest_slug, walk_slug, duration_hours} for every published walking route. |
| GET /api/v1/f1 | {slug} for every Grand Prix with a race guide. |
| GET /api/v1/hotels | Always []. Reserved, never populated — the empty array is the implementation, not an outage. |
| GET /api/v1/airlines | Always [], same as hotels. |
| POST /api/v1/revalidate | Operator only. Purges the page cache; requires the X-Revalidate-Secret header. |
Authentication is optional
A token unlocks no additional data — everything here is public either way. What it gives you is an identity, and with it a rate limit of your own instead of one shared with everything behind your IP. Registration is open and takes one request.
curl -sX POST https://tieredtravel.com/oauth/register -d '{"client_name":"my-agent"}'
curl -sX POST https://tieredtravel.com/oauth/token -u "$ID:$SECRET" -d grant_type=client_credentials
curl -H "Authorization: Bearer $TOKEN" https://tieredtravel.com/api/v1/walks
An expired or invalid token means “anonymous”, not “forbidden”: the request still succeeds at the shared limit. Full detail, including what this design cannot do, is in /auth.md.
Limits
Anonymous requests are counted per IP, authenticated ones per client. There is no pagination beyond
limit on destinations; every other endpoint returns its full list, which is in the hundreds of
rows, not the millions.