TourScanner

TourScanner AI 指南

如何使用 TourScanner API：搜索旅游和活动、查看实时可用情况并预订。本文也介绍 MCP 服务，供你让 AI Agent 执行相同操作时参考。

这是一个面向全球旅游、活动和景点的 REST API（通过 HTTPS 传输 JSON，采用 OpenAPI 3.1）。目录收录了来自 14 家供应商的约 100 万项活动，并通过一组统一的端点提供服务。本仓库是文档的实践指南：说明要调用哪些接口、按什么顺序调用，以及哪些错误会让人白白耗上一下午。

参考文档位于 tourscanner.ai/docs，机器可读规范位于 tourscanner.ai/openapi.json。

获取密钥

密钥需人工签发。请发送邮件至 [email protected]，说明你正在开发什么，以及你关注哪些城市。每次请求都要在 X-API-Key 标头中发送密钥。未提供密钥时会收到 401。

export TOURSCANNER_API_KEY=your_key

发起第一个请求

curl -s "https://tourscanner.ai/api/search/activities?city=rome&q=colosseum&limit=3" \
  -H "X-API-Key: $TOURSCANNER_API_KEY"

响应中会包含 activities，以及 total、page 和一些筛选项。每项活动都有一个 id、名称、评分，以及一个格式为 { "currency": "EUR", "price": 5400 } 的 price。

价格以最小货币单位的整数表示，因此 5400 相当于 54.00。min_price 和 max_price 筛选项也遵循这一规则。

预订流程

按以下顺序调用五个接口：

1. 使用 GET /api/search/activities 查找活动。
2. 使用 POST /api/availability/slots 查询指定日期的实际时段和价格。
3. 使用 POST /api/booking/options 获取票种和预订问题。
4. POST /api/booking/hold 会预留时段并返回 Stripe checkoutUrl。此时只会授权银行卡，不会扣款。
5. 客户付款后，使用 POST /api/booking/confirm。此操作会向供应商确认预订并扣款。

详情和请求正文见 docs/booking.md。步骤 1 至 4 的可运行示例见 examples/node/book.mjs。

示例

Node、Python、Ruby、Go 和 curl 示例都执行相同的三项操作：搜索、查看可用情况，以及完成预订流程直至获取 Stripe 链接。除语言标准库外，无需安装其他软件包（Node 18 或更高版本）。

	搜索	可用情况	预订
Node	node examples/node/search.mjs rome colosseum	node examples/node/availability.mjs 12345 2026-12-01	OPTION_CODE=... node examples/node/book.mjs 12345 2026-12-01
Python	python3 examples/python/search.py rome colosseum	python3 examples/python/availability.py 12345 2026-12-01	OPTION_CODE=... python3 examples/python/book.py 12345 2026-12-01
Ruby	ruby examples/ruby/search.rb rome colosseum	ruby examples/ruby/availability.rb 12345 2026-12-01	OPTION_CODE=... ruby examples/ruby/book.rb 12345 2026-12-01
Go	go run . search rome colosseum	go run . availability 12345 2026-12-01	OPTION_CODE=... go run . book 12345 2026-12-01

Go 示例请在 examples/go 目录中运行。curl 脚本位于 examples/curl。

示例会从 TOURSCANNER_API_KEY 读取密钥。设置 TOURSCANNER_BASE_URL 可将其指向其他主机。首次运行 book 时不要设置 OPTION_CODE：程序会打印可选项后停止，方便你选择代码。在生产主机上完整运行 book 会实际预留时段并创建 Stripe 结账页面。

没有你使用的语言？该 API 通过 HTTPS 传输纯 JSON，因此任何 HTTP 客户端都能使用。上面的 OpenAPI 规范可为大多数语言生成客户端。

面向 AI Agent

远程 MCP 服务位于 https://tourscanner.ai/api/mcp。它提供 12 个工具，涵盖搜索、可用情况、结账链接和预订状态。Claude、Cursor、VS Code 等产品的配置方法见 docs/mcp.md。

容易让人踩坑的地方

• 使用分，而不是欧元。 所有价格字段都以最小货币单位计。
• productOptionCode 来自 booking/options。 没有它就无法创建预留，而且不同活动的代码也不同。
• passengers 中必须包含 adults，且其值至少为 1。
• **电话号码必须包含国家代码，**例如 +442079460000。其他格式都会被拒绝。
• Stripe 会话会在 30 分钟后过期。 之后预留会被释放。
• 请在预订前立即检查可用性。 搜索结果来自我们的目录，时段则来自供应商的实时数据，两者可能不一致。
• 并非所有供应商都由我们直接处理预订。 其他供应商需要将旅客转交给合作伙伴。搜索时添加 providers=2,3,7，即可将结果限制为由我们直接预订的供应商。MCP get_activity 工具会通过每项活动的 bookableByUs 字段报告这一信息。
• 触发速率限制时会返回 429，并附带 Retry-After 标头。请遵守该值。

环境

生产环境主机会创建真实预留和真实 Stripe 结账会话。如果你想使用基于供应商测试环境的沙盒，请在获取密钥时提出申请。

许可证

本仓库中的代码采用 MIT 许可证。通过 API 获取的目录内容受条款约束。