search_along_route ツールを使用すると、LLM は自然言語クエリから旅行ルート沿いの場所（タホ湖に向かう途中の EV 充電ステーションや、サンフランシスコとサンノゼの間のコーヒー ショップなど）を検索できます。このツールは、一致する場所と、その場所を迂回した場合のトレードオフを AI で生成した要約を返します。概要で引用されている場所ごとに、プレイス ID、緯度 / 経度座標、Google マップのリンク、必要な帰属表示、迂回指標もレスポンスに含まれます。
すべての search_along_route リクエストは Pro オプションであり、Maps Grounding Pro SKU で課金されます。
search_along_route は、MCP サーバーを介して呼び出すか、searchAlongRoute REST メソッドとして呼び出すことができます。このページでは、リクエスト オプション、ルートの指定方法、レスポンスの内容、リクエストの課金方法について説明します。完全なスキーマについては、search_along_route MCP リファレンスと searchAlongRoute REST リファレンスをご覧ください。
リクエスト オプション
LLM は、ユーザーのリクエストとツールの説明に基づいて、ツールを呼び出すときにこれらのオプションを設定します。独自の指示を使用して、モデルが使用するオプションに影響を与えることができます。Pro の使用を制御するをご覧ください。
次の表に、search_along_route のリクエスト オプションを示します。
| オプション | 説明 |
|---|---|
text_query |
必須。ルート沿いの場所を検索する自然言語検索クエリ（例: ev chargers、coffee、vegetarian restaurants）。 |
retrieval_token、route_endpoints、encoded_polylineのいずれか |
必須。検索対象のルート。各リクエストで、これら 3 つのフィールドのいずれかを指定します。ルートを指定するをご覧ください。 |
travel_mode |
省略可。ルートと迂回路の計算に使用される移動手段。DRIVE（デフォルト）、WALK、BICYCLE のいずれかです。WALK と BICYCLE は route_endpoints でのみサポートされています。TRANSIT はサポートされていません。WALK のルートはベータ版であり、歩道や歩行者用通路が明確に表示されない場合があります。アプリに表示するすべての徒歩ルートについて、この警告をユーザーに表示する必要があります。 |
routing_preference |
省略可。ROUTING_PREFERENCE_TRAFFIC_UNAWARE（デフォルト）または ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL。交通データを使用してルートと迂回時間を計算する方法。ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL は、利用可能な場合はリアルタイムの交通状況を使用します。WALK または BICYCLE ではサポートされていません。 |
include_extended_details |
省略可。true の場合、概要には、クチコミ、メニュー項目、雰囲気、訪問者のヒント、EV 充電器の利用可能性、ガソリン価格などの分析情報を含むPlace Detailsが含まれます。デフォルト値は false です。 |
language_code |
省略可。概要とローカライズされた迂回距離の BCP-47 言語コード（例: en-US、ja）。デフォルト値は en-US です。 |
region_code |
省略可。ユーザーの 2 文字の CLDR 地域コード（US、CA など）。地域固有の場所の名前に影響し、適用される法律に基づいて検索結果に影響する可能性があります。 |
ルートを指定する
各 search_along_route リクエストでは、3 つの相互に排他的なフィールドのいずれかを使用してルートを指定する必要があります。複数のルート フィールドを設定するか、3 つすべてを省略すると、INVALID_ARGUMENT エラーが返されます。
次の表は、ルートを指定する 3 つの方法を比較したものです。
| ルート オプション | 入力形式 | サポートされている移動手段 | 戻り値 detourDuration |
用途 |
|---|---|---|---|---|
retrieval_token |
以前の compute_routes レスポンスの retrievalToken 文字列（10 分間有効） |
DRIVE |
はい | エージェントは、経由地を含む運転ルートをすでに compute_routes にリクエストしており、ユーザーはそのルート沿いの場所をリクエストしています。 |
route_endpoints |
origin と destination のウェイポイント（address、place_id、lat_lng）を含むオブジェクト |
DRIVE、WALK、BICYCLE |
はい | ユーザーが、最初に compute_routes を呼び出すことなく、1 つのステップで 2 つの場所の間にある場所を検索するようにリクエストした場合、またはルートで徒歩または自転車を使用する場合。 |
encoded_polyline |
運転ルートを表すエンコードされたポリライン文字列 | DRIVE |
いいえ（localizedDetourDistance のみを返します） |
アプリに、Routes API などの別のソースから取得したルートのポリラインがすでに存在する。 |
compute_routes と search_along_route をチェーンする
compute_routes リクエストで DRIVE 移動モードを使用すると、レスポンスの各ルートに retrievalToken フィールドが含まれます。このトークンは 10 分間有効で、計算されたルート（中間地点を含む）をエンコードします。ユーザーがそのルート沿いの場所を尋ねると、LLM は retrievalToken 値を search_along_route の retrieval_token として渡すことができます。
拡張された Place Details
ユーザーのリクエストに、次のようなルート沿いの定性的な分析情報、リアルタイムの状況、特別な属性が必要な場合は、include_extended_details を true に設定します。
- レビュー投稿者の意見: レビューに基づく分析情報、顧客の感情、フィードバック。
- 具体的なサービス: メニュー項目、料理、名物料理、飲料、ビジネスのハイライト。
- 雰囲気: インテリア、美観、雰囲気、ムード。
- 訪問者に役立つ実用的なヒントとリアルタイム データ: 事前予約の必要性、待ち時間、混雑状況、EV 充電器の空き状況、ガソリン価格、駐車場、施設。
ルート沿いの標準的な検索（ガソリン スタンド、休憩所、コーヒー ショップを場所、営業時間、迂回時間で検索するなど）では、include_extended_details を false（デフォルト）に設定したままにします。詳細な情報を取得するリクエストは完了までに時間がかかりますが、search_along_route リクエストはすべて Pro SKU で課金されるため、追加料金は発生しません。
例
次の MCP リクエストは、route_endpoints と交通状況を考慮したルートを使用して、サンフランシスコとレイクタホの間の EV 充電スタンドを検索します。
{
"method": "tools/call",
"params": {
"name": "search_along_route",
"arguments": {
"text_query": "fast EV chargers with a coffee shop nearby",
"route_endpoints": {
"origin": {"address": "San Francisco, CA"},
"destination": {"address": "Lake Tahoe, CA"}
},
"travel_mode": "DRIVE",
"routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
"include_extended_details": true
}
},
"jsonrpc": "2.0",
"id": 1
}
次の例では、前の compute_routes レスポンスの retrieval_token を使用しています。
{ "method": "tools/call", "params": { "name": "search_along_route", "arguments": { "text_query": "coffee shops", "retrieval_token": "RETRIEVAL_TOKEN" } }, "jsonrpc": "2.0", "id": 2 }
RETRIEVAL_TOKEN は、compute_routes によって返された retrievalToken 文字列に置き換えます。
次の例では、最初のリクエストを searchAlongRoute REST メソッドに送信します。
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
"textQuery": "fast EV chargers with a coffee shop nearby",
"routeEndpoints": {
"origin": {"address": "San Francisco, CA"},
"destination": {"address": "Lake Tahoe, CA"}
},
"travelMode": "DRIVE",
"routingPreference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
"includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchAlongRoute"
API_KEY を API キーに置き換えます。
レスポンス
レスポンスには、次のフィールドが含まれます。
summary: 検索結果と迂回ルートのトレードオフの自然言語による要約。resultsのエントリにマッピングされる 0 ベースの引用（[0]など）が含まれる場合があります。results[]: 要約に記載されている場所のランク付けされたリスト。各エントリには次の情報が含まれます。place: 場所に関する詳細。place: 場所のリソース名（places/{id}形式）。id: プレイス ID。他の Google Maps Platform API と組み合わせて使用できます。たとえば、地図上に場所を表示できます。location: 場所の緯度 / 経度座標。googleMapsLinks: 場所（placeUrl）、ルート（directionsUrl）、クチコミ（reviewsUrl）、写真（photosUrl）、クチコミの作成（writeAReviewUrl）の Google マップのリンク。attribution: 場所とともに表示する必要がある帰属情報。帰属表示の要件をご覧ください。
detourSummary: ルート上のこの場所に立ち寄るために必要な追加の移動時間と距離。localizedDetourDistance: リクエスト言語でフォーマットされた追加の距離（"1.2 mi"、"1.9 km"など）。detourDuration: 追加の移動時間（期間文字列、"180s"など）。ルートがencoded_polylineで指定されている場合、このフィールドは設定されません。
contentToken: エージェント データ可視化トークン（プレビュー版）。Places UI キット を使用して、レスポンス内の場所を追加料金なしで表示できます。レスポンスに 1 つ以上の場所が含まれている場合に返されます。
フィールドの詳細については、search_along_route リファレンスをご覧ください。
課金と割り当て
各 search_along_route リクエストは、Maps Grounding Pro SKU の課金対象イベント 1 件に相当します。include_extended_details を true に設定するか、routing_preference を ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL に設定しても、追加料金は発生しません。エージェントが最初に compute_routes を呼び出し、次に retrieval_token を search_along_route に渡すと、各ツール呼び出しは個別のリクエストとして課金されます。
Places UI キットを使用して search_along_route レスポンスの場所を表示する場合は、エージェント データ可視化トークン（プレビュー）を使用することで、Places UI キットのリクエストが課金されないようにできます。
search_along_route の割り当ては、プロジェクトごとに 1 分あたり 300 件のクエリです。料金については、メインの料金表とインドの料金表をご覧ください。