Entlang der Route suchen

Mit dem Tool search_along_route kann ein LLM Orte entlang einer Reiseroute anhand einer Abfrage in natürlicher Sprache finden, z. B. Ladestationen für Elektrofahrzeuge auf dem Weg zum Lake Tahoe oder Cafés zwischen San Francisco und San Jose. Das Tool gibt eine KI-generierte Zusammenfassung der passenden Orte und der damit verbundenen Umwege zurück. Für jeden in der Zusammenfassung genannten Ort enthält die Antwort auch die Orts-ID, die Breiten- und Längengradkoordinaten, Google Maps-URLs, die erforderliche Quellenangabe und Messwerte für Umwege.

Jede search_along_route-Anfrage ist eine Pro-Option und wird unter der Maps Grounding Pro-SKU abgerechnet.

Sie können search_along_route über den MCP-Server oder als REST-Methode searchAlongRoute aufrufen. Auf dieser Seite werden die Anfrageoptionen, die Angabe einer Route, der Inhalt der Antwort und die Abrechnung von Anfragen beschrieben. Die vollständigen Schemas finden Sie in der search_along_route-MCP-Referenz und der searchAlongRoute-REST-Referenz.

Anfrageoptionen

Das LLM legt diese Optionen fest, wenn es das Tool aufruft, basierend auf der Anfrage des Nutzers und der Toolbeschreibung. Sie können mit Ihren eigenen Anweisungen beeinflussen, welche Optionen das Modell verwendet. Weitere Informationen finden Sie unter Nutzung von Pro steuern.

In der folgenden Tabelle werden die Anfrageoptionen für search_along_route beschrieben:

Option Beschreibung
text_query Erforderlich. Die Suchanfrage in natürlicher Sprache für Orte entlang der Route, z. B. ev chargers, coffee oder vegetarian restaurants.
retrieval_token, route_endpoints oder encoded_polyline Erforderlich. Die Route, entlang der gesucht werden soll. Geben Sie in jeder Anfrage eines dieser drei Felder an. Weitere Informationen finden Sie unter Route angeben.
travel_mode Optional. Die Mobilitätsform, die zur Berechnung der Route und der Umwege verwendet wird: DRIVE (Standard), WALK oder BICYCLE. WALK und BICYCLE werden nur mit route_endpoints unterstützt. TRANSIT wird nicht unterstützt. WALK-Routen befinden sich in der Betaphase. Manchmal fehlen klare Gehwege oder Fußgängerwege. Sie müssen diese Warnung für alle Fußgängerrouten anzeigen, die Sie in Ihrer App darstellen.
routing_preference Optional. Wie Verkehrsdaten zur Berechnung der Route und der Umwegzeiten verwendet werden: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (Standard) oder ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL verwendet die aktuelle Verkehrslage, sofern verfügbar. Für WALK oder BICYCLE wird diese Option nicht unterstützt.
include_extended_details Optional. Wenn true, enthält die Zusammenfassung erweiterte Ortsdetails, z. B. Informationen aus Rezensionen, Menüpunkte, Atmosphäre, Tipps für Besucher, Verfügbarkeit von Ladestationen für Elektrofahrzeuge oder Benzinpreise. Die Standardeinstellung ist false.
language_code Optional. Der BCP-47-Sprachcode für die Zusammenfassung und die lokalisierte Umwegstrecke, z. B. en-US oder ja. Die Standardeinstellung ist en-US.
region_code Optional. Der zweistellige CLDR-Regionscode des Nutzers, z. B. US oder CA. Wirkt sich auf regionsspezifische Ortsnamen und möglicherweise auf Ergebnisse gemäß geltendem Recht aus.

Route angeben

In jeder search_along_route-Anfrage muss die Route mit einem von drei sich gegenseitig ausschließenden Feldern angegeben werden. Wenn Sie mehr als ein Routenfeld festlegen oder alle drei weglassen, wird der Fehler INVALID_ARGUMENT zurückgegeben.

In der folgenden Tabelle werden die drei Möglichkeiten zum Angeben einer Route verglichen:

Routenoption Eingabeformat Unterstützte Mobilitätsformen Gibt detourDuration zurück Anwendungsbereich
retrieval_token Der retrievalToken-String aus einer vorherigen compute_routes-Antwort (10 Minuten lang gültig) DRIVE Ja Der KI-Agent hat bereits compute_routes für eine Route aufgerufen, einschließlich Routen mit Zwischenstopps, und der Nutzer fragt nach Orten entlang dieser Route.
route_endpoints Ein Objekt mit origin- und destination-Wegpunkten (address, place_id oder lat_lng) DRIVE, WALK, BICYCLE Ja Der Nutzer bittet darum, Orte zwischen zwei Standorten in einem einzigen Schritt zu finden, ohne zuerst compute_routes aufzurufen, oder die Route wird zu Fuß oder mit dem Fahrrad zurückgelegt.
encoded_polyline Ein codierter Polylinien-String, der eine Fahrtroute darstellt DRIVE Nein (gibt nur localizedDetourDistance zurück) Ihre Anwendung hat bereits eine Routen-Polylinie aus einer anderen Quelle, z. B. der Routes API.

Kette compute_routes und search_along_route

Wenn in einer compute_routes-Anfrage der Mobilitätsmodus DRIVE verwendet wird, enthält jede Route in der Antwort ein retrievalToken-Feld. Dieses Token ist 10 Minuten lang gültig und codiert die berechnete Route, einschließlich aller Zwischenstopps. Wenn der Nutzer anschließend nach Orten entlang dieser Route fragt, kann das LLM den Wert retrievalToken als retrieval_token in search_along_route übergeben.

Erweiterte Ortsdetails

Setzen Sie include_extended_details auf true, wenn die Anfrage des Nutzers qualitative Informationen, Echtzeitbedingungen oder spezielle Attribute entlang der Route erfordert, z. B.:

  • Was Rezensenten sagen: Rezensionsbasierte Statistiken, Kundenstimmung und Feedback.
  • Spezifische Angebote: Menüpunkte, Gerichte, Spezialitäten, Getränke oder Highlights des Unternehmens.
  • Atmosphäre: Inneneinrichtung, Ästhetik, Ambiente oder Stimmung.
  • Praktische Tipps für Besucher und Echtzeitdaten: ob eine Vorabreservierung erforderlich ist, Wartezeiten, wie stark der Ort besucht ist, Verfügbarkeit von Ladestationen für Elektrofahrzeuge, Kraftstoffpreise, Parkmöglichkeiten und Einrichtungen.

Lassen Sie include_extended_details auf false (Standardeinstellung) für Standardsuchen entlang einer Route, z. B. um Tankstellen, Raststätten oder Cafés nach Standort, Öffnungszeiten und Umwegzeit zu finden. Anfragen mit erweiterten Details dauern länger, verursachen aber keine zusätzlichen Kosten, da jede search_along_route-Anfrage bereits über die Pro-SKU abgerechnet wird.

Beispiele

In der folgenden MCP-Anfrage wird nach Ladestationen für Elektrofahrzeuge zwischen San Francisco und Lake Tahoe gesucht. Dabei werden route_endpoints und verkehrsabhängiges Routing verwendet:

{
  "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
}

Im folgenden Beispiel wird ein retrieval_token aus einer vorherigen compute_routes-Antwort verwendet:

{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      "text_query": "coffee shops",
      "retrieval_token": "RETRIEVAL_TOKEN"
    }
  },
  "jsonrpc": "2.0",
  "id": 2
}

Ersetzen Sie RETRIEVAL_TOKEN durch den String retrievalToken, der von compute_routes zurückgegeben wird.

Im folgenden Beispiel wird die erste Anfrage an die REST-Methode searchAlongRoute gesendet:

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"

Ersetzen Sie dabei API_KEY durch Ihren eigenen API-Schlüssel.

Antwort

Die Antwort umfasst die folgenden Felder:

  • summary: Eine Zusammenfassung der Suchergebnisse und der Vor- und Nachteile von Umwegen in natürlicher Sprache. Sie kann nullbasierte Zitate wie [0] enthalten, die Einträgen in results zugeordnet sind.
  • results[]: Die sortierte Liste der in der Zusammenfassung erwähnten Orte. Jeder Eintrag enthält:
    • place: Details zum Ort:
      • place: Der Ressourcenname des Ortes im Format places/{id}.
      • id: Die Orts-ID. Sie können sie mit anderen Google Maps Platform APIs verwenden, um den Ort beispielsweise auf einer Karte anzuzeigen.
      • location: Die Breiten- und Längengradkoordinaten des Ortes.
      • googleMapsLinks: Google Maps-URLs für den Ort (placeUrl), die Wegbeschreibung (directionsUrl), Rezensionen (reviewsUrl), Fotos (photosUrl) und das Verfassen einer Rezension (writeAReviewUrl).
      • attribution: Die Zuordnung, die Sie für den Ort angeben müssen. Weitere Informationen finden Sie unter Anforderungen an die Quellenangabe.
    • detourSummary: Die zusätzliche Reisedauer und -strecke, die für einen Halt an diesem Ort entlang der Route erforderlich sind:
      • localizedDetourDistance: Die zusätzliche Entfernung, formatiert in der Sprache der Anfrage, z. B. "1.2 mi" oder "1.9 km".
      • detourDuration: Die zusätzliche Fahrtzeit als Dauerstring, z. B. "180s". Dieses Feld wird nicht festgelegt, wenn die Route mit encoded_polyline angegeben wird.
  • contentToken: Ein agentisches Datenvisualisierungstoken (Vorabversion), mit dem Sie die Orte in der Antwort ohne zusätzliche Kosten mit dem Places UI Kit anzeigen können. Wird zurückgegeben, wenn die Antwort mindestens einen Ort enthält.

Ausführliche Informationen zu den Feldern finden Sie in der search_along_route-Referenz.

Abrechnung und Kontingente

Jede search_along_route-Anfrage ist ein abrechenbares Ereignis im Rahmen der Maps Grounding Pro-SKU. Wenn Sie include_extended_details auf true oder routing_preference auf ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL festlegen, fallen keine zusätzlichen Gebühren an. Wenn Ihr Agent zuerst compute_routes aufruft und dann retrieval_token an search_along_route übergibt, wird jeder Toolaufruf als separate Anfrage abgerechnet.

Wenn Sie die Orte aus einer search_along_route-Antwort mit dem Places UI Kit anzeigen, können Sie das agentische Datenvisualisierungstoken (Vorabversion) verwenden, damit diese Places UI Kit-Anfragen nicht in Rechnung gestellt werden.

Das Kontingent für search_along_route beträgt 300 Abfragen pro Minute und Projekt. Informationen zu den Preisen finden Sie in der Hauptpreistabelle und in der Preistabelle für Indien.