Szukaj miejsc

Narzędzie search_places umożliwia LLM znajdowanie miejsc w Mapach Google na podstawie zapytania w języku naturalnym. Narzędzie zwraca wygenerowane przez AI podsumowanie pasujących miejsc. W przypadku każdego miejsca, które jest wymienione w podsumowaniu, zwraca też identyfikator miejsca, współrzędne geograficzne, linki do Map Google i informacje o autorze.

Możesz wywołać search_places za pomocą serwera MCP lub metody REST searchText. Na tej stronie opisujemy opcje żądania, w tym opcje Pro, zawartość odpowiedzi oraz sposób naliczania opłat za żądania. Pełne schematy znajdziesz w dokumentacji search_places MCP i dokumentacji searchText 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_places:

Opcje wersji Pro

Wybierz Maps Grounding Pro SKU. Żądanie, które używa jednej lub obu tych funkcji, jest rozliczane w ramach kodu SKU Pro:

Żądania, które nie korzystają z żadnej z tych opcji, w tym żądania z parametrem page_size od 1 do 5, są rozliczane w ramach kodu SKU Essentials.

Rozszerzone informacje o miejscu

Ustaw parametr include_extended_details na true, gdy prośba użytkownika wymaga informacji jakościowych, warunków w czasie rzeczywistym lub specjalistycznych atrybutów, takich jak:

• Co mówią recenzenci: statystyki na podstawie opinii, 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: czy należy dokonać rezerwacji, zasady dotyczące wizyt bez rezerwacji, czas oczekiwania, natężenie ruchu, parking i udogodnienia;
• Bliskość: odległość lub czas podróży od lokalizacji zapytania lub centrum location_bias, gdy użytkownik pyta, co jest w pobliżu lub najbliżej.

Statystyki w podsumowaniu zależą od zapytania i danych dostępnych dla każdego miejsca. Nie każdy rodzaj statystyk pojawia się w każdej odpowiedzi.

Pozostaw wartość false (domyślną) w przypadku wyszukiwania standardowego: kuchni lub typów sklepów, adresów, informacji kontaktowych, godzin otwarcia i standardowych udogodnień. Przetwarzanie żądań z rozszerzonymi szczegółami trwa dłużej.

Szczegóły rozszerzone nie zmieniają struktury odpowiedzi. Bez nich podsumowanie opisuje każde miejsce w 1–2 zdaniach. Dzięki nim każde miejsce ma dłuższy opis, który wykorzystuje więcej danych z Map Google, w tym informacje z opinii. Wpisy strukturalne places są takie same w przypadku obu kodów SKU.

Przykład

To żądanie MCP prosi o maksymalnie 8 miejsc z rozszerzonymi szczegółami. Jest rozliczany w ramach kodu SKU Pro:

{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      "text_query": "date night Italian restaurants in Chicago",
      "page_size": 8,
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

Ten przykład wysyła to samo żądanie do metody REST searchText:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "date night Italian restaurants in Chicago",
  "pageSize": 8,
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchText"

Zastąp API_KEY swoim kluczem interfejsu API.

Bez szczegółowych informacji podsumowanie opisuje każde miejsce w jednym lub dwóch zdaniach:

Example Trattoria [0] (4,6★ (1250) · 123 W Example St · $$$) A neighborhood trattoria known for handmade pasta and a long wine list.

With extended details, the summary adds what reviewers highlight and practical tips:

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) Kameralna restauracja oświetlona świecami, którą recenzenci opisują jako romantyczną, ale głośną w weekendy. Wśród wyjątkowych dań warto wymienić tagliatelle al ragù, burratę i tiramisu. Zalecamy rezerwację stolika. W piątkowe i sobotnie wieczory goście bez rezerwacji muszą czekać 30–45 minut. Liczba miejsc parkingowych przy ulicy jest ograniczona.

Odpowiedź

Odpowiedź zawiera te pola:

• summary: podsumowanie wyników wyszukiwania w języku naturalnym. Może zawierać cytaty indeksowane od zera, takie jak [0], które są mapowane na wpisy w places.
• places[]: miejsca wymienione w podsumowaniu. Każde miejsce zawiera:
  • 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.
• 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.

Odpowiedź ma taką samą strukturę w przypadku obu SKU oraz MCP i REST. Szczegółowe informacje o polach znajdziesz w dokumentacji search_places.

Rozliczenia i limity

Każde żądanie search_places to jedno zdarzenie podlegające rozliczeniu:

• Żądanie, które nie korzysta z żadnych opcji Pro, jest rozliczane w ramach kodu SKU Maps Grounding Essentials.
• Żądanie, które korzysta z opcji Pro, jest rozliczane w ramach kodu SKU Maps Grounding Pro. Użycie obu opcji w jednym żądaniu nie zmienia opłaty. Informacje o cenach wersji Pro znajdziesz w artykule Porównanie Essentials, Pro i powiązania ze źródłami informacji przy użyciu Map Google.

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

Limit search_places wynosi 300 zapytań na minutę w przypadku każdego projektu i jest współdzielony przez oba kody SKU. Ceny znajdziesz w głównej tabeli cen i tabeli cen w Indiach.