# TourScanner AI — Tours & Activities Booking API

> The largest multi-provider tours & activities API on the market.
> 1,000,000+ activities from 14 providers through a single REST API.
> Backed by TourScanner, with 10 years of experience in the tours & activities industry.

## Why TourScanner AI

- **One integration, all providers** — Search and book across 14 providers
- **1,000,000+ activities** across 5,000+ cities and 7,800+ attractions worldwide
- **API key access** — Keys are issued by TourScanner on request (api@tourscanner.ai); every REST and MCP call needs one
- **Full booking lifecycle** — Hold, pay, confirm, status, cancel and amend through the API
- **Agent-ready** — Remote MCP server, OpenAPI 3.1 spec, idempotent booking writes, machine-readable error codes
- **8 languages** — Full multilingual search and content (EN, IT, ES, FR, DE, PT, NL, PL)
- **Activity Caliber** — Proprietary quality-ranking algorithm refined over 10 years of data

## Who Is This For

- **Travel app developers** — Add tour booking to your app with a single API integration
- **AI agent builders** — Give your agent live search, availability and booking tools via MCP or REST
- **Affiliate & content sites** — Monetize your travel audience with real-time bookable activities
- **Tour operators & resellers** — Access the widest inventory through one API

## Booking Workflow

1. **Search** — Find cities and activities (`GET /api/search/destinations`, `GET /api/search/activities`)
2. **Availability** — Check dates and time slots (`POST /api/availability/schedule`, `POST /api/availability/slots`)
3. **Hold & Pay** — Reserve booking + Stripe checkout (`POST /api/booking/hold`)
4. **Confirm** — Finalize after payment (`POST /api/booking/confirm`)
5. **Manage** — Status, cancel and amend (`POST /api/booking/status`, `/cancel-quote`, `/cancel`, `/amend-quote`, `/amend`)

## Endpoints

- `GET /api/search/destinations?q=rome&lang=en` — Search cities
- `GET /api/search/activities?city_name=rome&sort=caliber&limit=20` — Search activities by city name
- `GET /api/search/activities?city=84632&sort=caliber&limit=20` — Search activities by city ID
- `GET /api/search/product/:id` — Full product detail
- `POST /api/availability/schedule` — Monthly availability calendar
- `POST /api/availability/slots` — Real-time time slots for a date
- `POST /api/booking/options` — Booking form fields (variants, age bands, questions)
- `POST /api/booking/hold` — Hold booking + get Stripe checkout URL
- `POST /api/booking/confirm` — Confirm after Stripe payment
- `POST /api/booking/status` — Check booking status
- `POST /api/booking/cancel-quote` — Cancellability and refund
- `POST /api/booking/cancel` — Cancel booking
- `POST /api/booking/amend-quote` — Quote a date/time/ticket/party change
- `POST /api/booking/amend` — Apply a quoted amendment
- `POST /api/booking/reschedule` — Move to a new date/time (supported suppliers)

Booking writes accept an `Idempotency-Key` header. Errors return `data.code` and `data.retryable`.

## Authentication

Every request needs an API key, sent as `X-API-Key: <key>`. Keys are issued by TourScanner on request: contact api@tourscanner.ai. Without a key the API answers `401 {"error": "API_KEY_REQUIRED"}`.

## Providers

14 providers, 1,000,000+ activities. Certified suppliers book in-house through this API; the others return a partner booking link (`bookableByUs: false`).

## Environments

tourscanner.ai is production: `/api/booking/hold` places real supplier holds and real Stripe checkouts. For sandbox access on provider test rails, contact api@tourscanner.ai.

## MCP Server

Remote MCP server (Streamable HTTP) at `https://tourscanner.ai/api/mcp`. An API key is required on every request: `Authorization: Bearer <API key>` (or `X-API-Key`); clients that cannot send headers, like claude.ai custom connectors, use `https://tourscanner.ai/api/mcp?api_key=<API key>`. 12 tools: search_destinations, search_activities, get_activity, check_availability, get_availability_calendar, get_booking_options, create_checkout_session, get_booking_status, get_cancellation_quote, cancel_booking, get_amendment_quote, amend_booking. create_checkout_session returns a tourscanner.io checkout link where the traveller books and pays; cancel and amend run in demo mode.

Stdio-only clients:

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

## Links

- [API docs](https://tourscanner.ai/docs): interactive reference with sandbox testing
- [Full API reference](https://tourscanner.ai/llms-full.txt): every endpoint in plain text
- [OpenAPI 3.1 spec](https://tourscanner.ai/openapi.json): machine-readable schema
- [MCP server setup](https://tourscanner.ai/mcp): connect Claude, ChatGPT, Cursor, VS Code, Codex, Gemini and more
- [Guides](https://tourscanner.ai/guides): articles on tours and activities
- [Explore](https://tourscanner.ai/explore): sample destinations and activities
- [About](https://tourscanner.ai/about): who we are
- [Privacy](https://tourscanner.ai/privacy) and [Terms](https://tourscanner.ai/terms)
- [API guide on GitHub](https://github.com/Mhmd-S/tourscanner-api-guide): runnable examples in Node, Python, Ruby, Go and curl