API Documentation

Full REST API for searching, checking availability, and booking tours and activities. All responses are JSON. Every request needs an API key, sent as X-API-Key. Keys are issued by TourScanner on request: write to [email protected]. Without a key the API answers 401 with {"error": "API_KEY_REQUIRED"}. The "Try it" panels on this page run from your browser without one.

Booking Workflow

The typical integration follows this flow:

Low-latency typeahead. Returns a grouped payload — cities, pois, tags, activities — suitable for rendering a search-as-you-type dropdown. Designed to be called on every keystroke.

Parameters

Search for cities and destinations by name (q), or look up a single city by id to hydrate a destination header. The lookup mode returns a destination object — { id, name, nameLocalized, slug, country, countryCode, region, population, lat, lng } — with the name localized to lang and the full localized country name; it is null when the id isn't a city.

Parameters

Search activities by text, city, or filters. Returns paginated results with pricing.

Parameters

Facets

When facets=true (default), the response includes a facets object with refinement options. Each facet's counts are computed over the activities matching every other dimensional filter — so clicking a provider chip re-narrows the tag/price/rating/feature counts, but the provider counts themselves stay stable so the user can pivot. Bounds in facets.prices are in the currency's minor unit (cents for EUR/USD), matching the min_price / max_price params. Capped at the top 3,000 activities by caliber for a city/POI-scoped query (1,000 for a broad browse) when the matching corpus is larger — facets.capped tells you when that happened. The facets.features (characteristics) and facets.tourTypes arrays correspond to the features and tour_types filter params — feed a chip's key straight back to filter. facets.languages ({ code, count }) drives the languages filter, and facets.landmarks ({ id, name, slug, poiType, count }) lists the other POIs the matching tours also cover — the "additional landmarks" filter, fed back through also_pois.

{
  "facets": {
    "tags":      [{ "id": 70787, "name": "Walking Tours", "slug": "walking-tours", "type": "activity_type", "count": 487 }, ...],
    "providers": [{ "id": 3, "count": 320 }, { "id": 4, "count": 88 }, ...],
    "prices":    { "currency": "EUR", "min": 500, "max": 98000, "buckets": [{ "from": 0, "to": 2000, "count": 4 }, { "from": 2000, "to": 4000, "count": 12 }, ..., { "from": 50000, "to": null, "count": 7 }] },
    "ratings":   [{ "min": 3, "count": 1024 }, { "min": 3.5, "count": 870 }, { "min": 4, "count": 520 }, { "min": 4.5, "count": 230 }],
    "features":  [{ "key": "free_cancellation", "count": 234 }, { "key": "instant_confirmation", "count": 412 }, { "key": "mobile_ticket", "count": 540 }, { "key": "accessible", "count": 130 }],
    "tourTypes": [{ "key": "guided", "count": 410 }, { "key": "private", "count": 96 }, { "key": "ticket", "count": 220 }, { "key": "audioguide", "count": 24 }, { "key": "night", "count": 31 }],
    "languages": [{ "code": "en", "count": 612 }, { "code": "it", "count": 288 }, { "code": "es", "count": 141 }, ...],
    "landmarks": [{ "id": 4412, "name": "Roman Forum", "slug": "roman-forum", "poiType": "monument", "count": 203 }, ...],
    "corpusSize": 1234,
    "capped": false
  }
}

Search tags (activity categories and filters) by name, or look up a single tag by id to hydrate a tag detail / landing header. Optionally include the top-ranked activities for each tag, so you can build faceted browse UIs without hardcoding IDs. Filter to a category's tags with category, scope/rank to a city with cityId, and set withActivities=true — together these return a whole category landing page (ranked tags, each with its top activities) in a single call.

Parameters

Points of interest in a city — attractions, districts, landmarks. POIs are pulled from ts.pois by their own city_id, so neighbour-city POIs incorrectly linked via legacy parser data cannot leak in. Sorted by how many of the city's valid/enabled/available activities link to each POI (POIs with no activities still appear, sorted last). Pass sort to opt into the curated ranking order or popularity (activity count × review volume); omit it and the order is unchanged.

Scoping note: counts (and embedded activities, if requested) are restricted to activities whose city_id equals the queried city. Day trips that visit a Florence POI but depart from Rome are excluded, matching what a user sees when browsing the city.

Parameters

Get full product detail including description, gallery, itinerary, pricing, features, and cancellation policy. reviewsSummary carries a generated digest of the activity's reviews for the requested lang — null when that language has no digest (there is no English fallback), which is the common case since coverage is partial. Use its generatedAt to judge whether the digest still reflects the current reviewsCount.

Parameters

Paginated reviews for a single activity.

Parameters

Get a monthly availability calendar. Returns which dates have available slots.

Body Parameters

Get real-time bookable time slots for a specific date. Use after the user selects a date from the schedule.

Body Parameters

Get booking form fields: product variants, age bands, booking questions, language guides, and cancellation policy.

Body Parameters

Hold a booking and create a Stripe Checkout session. Returns a checkoutUrl to redirect the customer to Stripe for payment. The hold uses manual capture — the card is authorized but not charged until the booking is confirmed with the provider.

Body Parameters

Response

{
  "checkoutUrl": "https://checkout.stripe.com/...",
  "internalRef": "TS-3-abc123-def456",
  "expiresAt": "2026-04-10T15:30:00Z",
  "retailPrice": 5400,
  "currency": "EUR"
}

Confirm a booking after Stripe payment. Call this with the session_id from the Stripe success redirect. This captures the payment and confirms with the provider.

Body Parameters

Response

{
  "status": "confirmed",
  "internalRef": "TS-3-abc123-def456",
  "providerRef": "BR-12345678",
  "voucherUrl": "https://...",
  "ticketUrl": "https://...",
  "activityName": "Colosseum Skip-the-Line Tour",
  "travelDate": "2026-05-15"
}

Check the current status of a booking.

Body Parameters

Cancel a booking. Cancels with the provider and refunds the Stripe payment.

Body Parameters

Discover the ranking scopes available on the platform, resolved into human-friendly { city, poi } records. Use this to drive a "popular destinations" UI without hardcoding city IDs.

Parameters

List the categories (ts.categories) — the high-level groups (Sightseeing, Museums, Day Trips…) that bundle tags via ts.tag_categories. Drill into a category's tags with /api/search/tags?category=… (add cityId to rank by city popularity). For the flat list of browseable tags use /api/data/tags; for free-text tag search use /api/search/tags.

Parameters

{
  "categories": [
    { "id": 15, "slug": "sightseeing", "name": "Sightseeing" },
    { "id": 5, "slug": "museums", "name": "Museums" }, ...
  ]
}

List the globally-visible tags (Walking Tours, Food Tours, Skip-the-line…) for a browseable tag tree. This is what /api/data/categories returned previously. For free-text tag search use /api/search/tags; for the tags of one category use /api/search/tags?category=….

Parameters

Stripe Payment Flow

The booking system uses Stripe's manual capture mode for safe payment handling:

1. Hold — POST /api/booking/hold creates a Stripe Checkout session with capture_method: manual. The customer's card is authorized but not charged.
2. Redirect — Redirect the customer to the returned checkoutUrl. Stripe handles card input securely.
3. Success callback — After payment, Stripe redirects to your success URL with ?session_id=....
4. Confirm — Call POST /api/booking/confirm with the session ID. This confirms with the provider, then captures the payment.
5. Failure — If the provider rejects the booking, the payment authorization is cancelled automatically (no charge).

MCP Server

The same capabilities are available as a remote Model Context Protocol (MCP) server, so AI agents (Claude, ChatGPT, Cursor, custom agents) can search, check live availability, prepare checkouts and manage bookings through tool calls.

Every request needs an API key, including initialize and tools/list. Keys are issued by TourScanner on request: [email protected]. Send it as Authorization: Bearer <key> or X-API-Key: <key>; clients that cannot send headers put it in the URL as ?api_key=<key>. Without a valid key the server answers 401 with WWW-Authenticate: Bearer. The examples below use YOUR_API_KEY: replace it with your own key.

Claude Code

Add the server with the key in a header:

claude mcp add --transport http tourscanner https://beta.tourscanner.ai/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Claude Desktop

In claude_desktop_config.json, bridge the remote server with mcp-remote and pass the key as a header:

{
  "mcpServers": {
    "tourscanner": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://beta.tourscanner.ai/api/mcp",
        "--header", "Authorization: Bearer ${TOURSCANNER_API_KEY}"
      ],
      "env": { "TOURSCANNER_API_KEY": "YOUR_API_KEY" }
    }
  }
}

claude.ai custom connectors

Custom connectors cannot send headers, so the key goes in the server URL. In Settings → Connectors → Add custom connector, use:

https://beta.tourscanner.ai/api/mcp?api_key=YOUR_API_KEY

Other clients

Any client with remote MCP support (Streamable HTTP) can point at https://beta.tourscanner.ai/api/mcp with the Authorization: Bearer header.

Available Tools

Tools carry MCP annotations (readOnlyHint, destructiveHint) so agent hosts can ask the user before a write. Booking tools only see bookings made with the calling key.

Example Agent Prompt

"Find skip-the-line Colosseum tickets for 2 adults next Saturday.
Check live availability and prepare the cheapest morning slot."

Response Codes

Error body

Errors keep a human message and add a stable data.code plus data.retryable:

{
  "statusCode": 422,
  "message": "This time slot is no longer available. Please select a different time.",
  "data": { "code": "SLOT_UNAVAILABLE", "retryable": false }
}

Codes: VALIDATION_ERROR, AUTH_REQUIRED, NOT_FOUND, RATE_LIMITED, SLOT_UNAVAILABLE, PRICE_CHANGED, PAX_INVALID, NOT_CANCELLABLE, NOT_SUPPORTED, HOLD_EXPIRED, PAYMENT_REQUIRED, PROVIDER_TIMEOUT, PROVIDER_ERROR, IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_IN_PROGRESS, DEMO_SESSION, BOOKING_FAILED.

Idempotent retries

/booking/hold, /confirm, /cancel, /amend and /reschedule accept an Idempotency-Key header (e.g. a UUID). Retrying with the same key and body within 24h replays the first response (Idempotent-Replayed: true) instead of booking twice; the same key with a different body returns IDEMPOTENCY_KEY_REUSED.