TourScanner

TourScanner AI ガイド

TourScanner API の使い方：ツアーやアクティビティを検索し、リアルタイムの空き状況を確認して、予約します。AI エージェントに同じことをさせたい場合に備えて、MCP サーバーについても説明します。

世界中のツアー、アクティビティ、観光名所を扱う 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 フィルターにも当てはまります。

予約の流れ

次の順序で 5 回呼び出します。

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 のリンクが表示されるところまでの予約フローの 3 つを実行します（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 にあります。

API キーは TOURSCANNER_API_KEY から読み込みます。別のホストを指定するには TOURSCANNER_BASE_URL を設定してください。まず OPTION_CODE を指定せずに book を実行してください。選択できるよう、オプションを表示して終了します。本番ホストで book を最後まで実行すると、実際に空き枠が仮押さえされ、Stripe のチェックアウトが作成されます。

使用したい言語がありませんか？この API は HTTPS 経由のプレーンな JSON なので、どの HTTP クライアントでも使えます。上記の OpenAPI 仕様から、ほとんどの言語向けのクライアントを生成できます。

AI エージェント向け

https://tourscanner.ai/api/mcp にリモート 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 としてこの情報を返します。
• レート制限に達すると、Retry-After ヘッダーとともに 429 が返されます。 その指示に従ってください。

環境

本番ホストでは、実際のホールドと Stripe の実際のチェックアウトが行われます。プロバイダーのテスト環境でサンドボックスを利用したい場合は、キーを取得する際にお申し付けください。

ライセンス

このリポジトリのコードには MIT ライセンスが適用されます。API から取得するカタログのコンテンツには、利用規約が適用されます。