API Documentation

Full REST API for searching, checking availability, and booking tours and activities. All responses are JSON. No authentication is required for sandbox testing.

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.

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 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": {
    "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": 2500, "count": 145 }, { "from": 2500, "to": 5000, "count": 87 }, ..., { "from": 10000, "to": null, "count": 23 }] },
    "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 }],
    "corpusSize": 1234,
    "capped": false
  }
}

Search tags (activity categories and filters) by name. Optionally include the top-ranked activities for each tag, so you can build faceted browse UIs without hardcoding IDs.

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).

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.

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 visible tag categories. For free-text tag search use /api/search/tags instead.

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

This API is available as a Model Context Protocol (MCP) server, allowing AI agents (Claude, GPT, etc.) to search, check availability, and book activities programmatically.

Configuration

Add the following to your MCP client config (e.g. claude_desktop_config.json or .claude/settings.json):

{
  "mcpServers": {
    "tours-api": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-remote", "http://localhost:3017/api/mcp"]
    }
  }
}

Available Tools

Example Agent Prompt

"Find skip-the-line tours in Rome for 2 adults on April 20th.
Check availability and show me the best options with prices."

Response Codes