Szukaj na trasie

Narzędzie search_along_route pozwala LLM znajdować miejsca na trasie podróży na podstawie zapytania w języku naturalnym, np. stacje ładowania EV w drodze do Lake Tahoe lub kawiarnie między San Francisco a San Jose. Narzędzie zwraca wygenerowane przez AI podsumowanie pasujących miejsc i informacje o tym, jak wpłyną one na czas podróży. W przypadku każdego miejsca wymienionego w podsumowaniu odpowiedź zawiera też identyfikator miejsca, współrzędne geograficzne, linki do Map Google, wymagane informacje o autorstwie i dane dotyczące objazdu.

Każde żądanie search_along_route jest opcją Pro i jest rozliczane w ramach kodu SKU Maps Grounding Pro.

Możesz wywołać search_along_route przez serwer MCP lub jako metodę REST searchAlongRoute. Na tej stronie opisano opcje żądania, sposób określania trasy, zawartość odpowiedzi i sposób naliczania opłat za żądania. Pełne schematy znajdziesz w dokumentacji search_along_route MCP i dokumentacji searchAlongRoute REST.

Opcje żądania

Model LLM ustawia te opcje, gdy wywołuje narzędzie, na podstawie prośby użytkownika i opisu narzędzia. Możesz wpływać na to, których opcji używa model, za pomocą własnych instrukcji. Więcej informacji znajdziesz w artykule o kontrolowaniu korzystania z wersji Pro.

W tabeli poniżej opisano opcje żądania dla search_along_route:

Opcja Opis
text_query Wymagane. Zapytanie dotyczące wyszukiwania w języku naturalnym miejsc na trasie, np. ev chargers, coffee lub vegetarian restaurants.
retrieval_token, route_endpoints lub encoded_polyline Wymagane. Trasa, wzdłuż której ma być przeprowadzone wyszukiwanie. W każdym żądaniu podaj jedno z tych 3 pól. Zobacz Określanie trasy.
travel_mode Opcjonalnie: Środek transportu używany do obliczania trasy i objazdów: DRIVE (domyślny), WALK lub BICYCLE. Wartości WALK i BICYCLE są obsługiwane tylko w przypadku route_endpoints. TRANSIT nie jest obsługiwany. Trasy WALK są w wersji beta i czasami mogą nie obejmować chodników ani ścieżek dla pieszych. Musisz wyświetlać to ostrzeżenie użytkownikowi w przypadku wszystkich tras pieszych, które wyświetlasz w aplikacji.
routing_preference Opcjonalnie: Jak dane o ruchu są używane do obliczania czasu trasy i objazdu: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (domyślnie) lub ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL korzysta z informacji o warunkach na drodze w czasie rzeczywistym, jeśli są dostępne. Nie jest obsługiwany w przypadku WALK ani BICYCLE.
include_extended_details Opcjonalnie: Gdy true, podsumowanie zawiera rozszerzone informacje o miejscu, takie jak statystyki z opinii, pozycje w menu, atmosfera, wskazówki dla odwiedzających, dostępność ładowarek EV lub ceny paliwa. Domyślna wartość to false.
language_code Opcjonalnie: Kod języka w standardzie BCP-47 dla podsumowania i zlokalizowanej odległości objazdu, np. en-US lub ja. Domyślna wartość to en-US.
region_code Opcjonalnie: Dwuliterowy kod regionu CLDR użytkownika, np. US lub CA. Ma wpływ na nazwy miejsc w poszczególnych regionach i może wpływać na wyniki na podstawie obowiązujących przepisów.

Określ trasę

Każde żądanie search_along_route musi określać trasę za pomocą jednego z 3 wykluczających się wzajemnie pól. Ustawienie więcej niż 1 pola trasy lub pominięcie wszystkich 3 pól powoduje błąd INVALID_ARGUMENT.

W tabeli poniżej znajdziesz porównanie 3 sposobów określania trasy:

Opcja trasy Format wejściowy Obsługiwane środki transportu Zwraca detourDuration Kiedy z niego korzystać
retrieval_token Ciąg znaków retrievalToken z poprzedniej odpowiedzi compute_routes (ważny przez 10 minut). DRIVE Tak Agent wywołał już compute_routes, aby uzyskać trasę dojazdu, w tym trasy z przystankami pośrednimi, a użytkownik pyta o miejsca na tej trasie.
route_endpoints Obiekt z punktami pośrednimi origin i destination (address, place_id lub lat_lng) DRIVE, WALK, BICYCLE Tak Użytkownik prosi o znalezienie miejsc między 2 lokalizacjami w jednym kroku bez wcześniejszego wywołania compute_routes lub trasa obejmuje chodzenie albo jazdę na rowerze.
encoded_polyline Ciąg znaków zakodowanej linii łamanej reprezentujący trasę dojazdu. DRIVE Nie (zwraca tylko localizedDetourDistance) Twoja aplikacja ma już linię łamaną trasy z innego źródła, np. z interfejsu Routes API.

Łańcuszek compute_routes i search_along_route

Gdy żądanie compute_routes używa środka transportu DRIVE, każda trasa w odpowiedzi zawiera pole retrievalToken. Ten token jest ważny przez 10 minut i koduje obliczoną trasę, w tym wszystkie przystanki pośrednie. Gdy użytkownik zapyta o miejsca na tej trasie, LLM może przekazać wartość retrievalToken jako retrieval_token w search_along_route.

Rozszerzone informacje o miejscu

Ustaw parametr include_extended_details na true, gdy żądanie użytkownika wymaga statystyk jakościowych, warunków w czasie rzeczywistym lub specjalistycznych atrybutów na trasie, takich jak:

  • Opinie recenzentów: statystyki oparte na opiniach, nastroje klientów i opinie.
  • konkretne oferty: pozycje menu, dania, specjalności, napoje lub najważniejsze informacje o firmie;
  • Atmosfera: wystrój wnętrza, estetyka, nastrój.
  • praktyczne wskazówki dla odwiedzających i dane w czasie rzeczywistym: czy warto zarezerwować miejsce z wyprzedzeniem, czas oczekiwania, natężenie ruchu, dostępność ładowarek EV, ceny paliwa, parking i udogodnienia;

Pozostaw parametr include_extended_details ustawiony na false (wartość domyślna) w przypadku standardowych wyszukiwań na trasie, takich jak znajdowanie stacji benzynowych, miejsc odpoczynku lub kawiarni według lokalizacji, godzin otwarcia i czasu objazdu. Żądania z rozszerzonymi szczegółami trwają dłużej, ale nie wiążą się z dodatkowymi opłatami, ponieważ każde żądanie search_along_route jest już rozliczane w ramach SKU Pro.

Przykłady

To żądanie MCP wyszukuje stacje ładowania EV między San Francisco a Lake Tahoe, korzystając z route_endpoints i wyznaczania trasy z uwzględnieniem natężenia ruchu:

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

W tym przykładzie użyto retrieval_token z poprzedniej odpowiedzi compute_routes:

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

Zastąp RETRIEVAL_TOKEN ciągiem znaków retrievalToken zwróconym przez compute_routes.

Ten przykładowy kod wysyła pierwsze żądanie do metody REST searchAlongRoute:

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"

Zastąp API_KEY swoim kluczem interfejsu API.

Odpowiedź

Odpowiedź zawiera te pola:

  • summary: podsumowanie wyników wyszukiwania i kompromisów związanych z objazdem w języku naturalnym. Może zawierać cytaty indeksowane od zera, takie jak [0], które są mapowane na wpisy w polu results.
  • results[]: rankingowa lista miejsc wymienionych w podsumowaniu. Każdy wpis zawiera:
    • place: szczegółowe informacje o miejscu:
      • place: nazwa zasobu miejsca w formacie places/{id}.
      • id: identyfikator miejsca. Możesz go używać z innymi interfejsami API Google Maps Platform, np. do wyświetlania miejsca na mapie.
      • location: współrzędne szerokości i długości geograficznej miejsca.
      • googleMapsLinks: linki do Map Google dotyczące miejsca (placeUrl), wskazówek dojazdu (directionsUrl), opinii (reviewsUrl), zdjęć (photosUrl) i pisania opinii (writeAReviewUrl).
      • attribution: atrybucja, którą musisz wyświetlać w przypadku miejsca. Zobacz Wymagania dotyczące podania źródła.
    • detourSummary: dodatkowy czas podróży i odległość wymagane do zatrzymania się w tym miejscu na trasie:
      • localizedDetourDistance: dodatkowa odległość sformatowana w języku żądania, np. "1.2 mi" lub "1.9 km".
      • detourDuration: dodatkowy czas podróży jako ciąg znaków określający czas trwania, np. "180s". To pole nie jest ustawiane, gdy trasa jest określona za pomocą encoded_polyline.
  • contentToken: token wizualizacji danych agentowych (wersja testowa), który umożliwia wyświetlanie miejsc w odpowiedzi za pomocą Places UI Kit bez dodatkowych kosztów. Zwracany, gdy odpowiedź zawiera co najmniej 1 miejsce.

Szczegółowe informacje o polach znajdziesz w dokumentacji search_along_route.

Rozliczenia i limity

Każde żądanie search_along_route to 1 zdarzenie podlegające rozliczeniu w ramach kodu SKU Maps Grounding Pro. Ustawienie include_extended_details na true lub routing_preference na ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL nie powoduje naliczenia dodatkowych opłat. Jeśli agent najpierw wywoła compute_routes, a następnie przekaże retrieval_token do search_along_route, każde wywołanie narzędzia zostanie rozliczone jako osobne żądanie.

Jeśli wyświetlasz miejsca z odpowiedzi search_along_route za pomocą Places UI Kit, możesz użyć tokena wizualizacji danych agentowych (wersja testowa), aby te żądania Places UI Kit nie były rozliczane.

Limit search_along_route wynosi 300 zapytań na minutę dla każdego projektu. Ceny znajdziesz w głównej tabeli cen i tabeli cen w Indiach.