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, linki do Map Google i informacje o autorze.

Na tej stronie opisujemy opcje żądania, w tym opcje Pro, zawartość odpowiedzi oraz sposób naliczania opłat za żądania. Pełny schemat narzędzia znajdziesz w dokumentacji search_places.

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. Zobacz Kontrolowanie korzystania z Pro.

Opcja Opis
text_query Wymagane. Wyszukiwane hasło, np. coffee shops near Golden Gate Park. Zapytanie musi zawierać wystarczająco dużo informacji o lokalizacji, aby było jednoznaczne, lub żądanie musi zawierać parametr location_bias.
location_bias Okrąg (center i opcjonalnie radius_meters, do 50 000 metrów), który ma być preferowany przy wyświetlaniu wyników. Jeśli text_query wskazuje konkretną lokalizację, używana jest ta lokalizacja.
language_code Język podsumowania, na przykład en lub ja. Domyślny język to angielski.
region_code Kod regionu CLDR użytkownika, np. US. Wpływa na nazwy miejsc w poszczególnych regionach i może mieć wpływ na wyniki wyszukiwania zgodnie z obowiązującymi przepisami.
page_size Maksymalna liczba miejsc do zwrócenia. Wartość domyślna to 5. Wartości od 6 do 10 są dostępne w opcji Pro. Wartości powyżej 10 zwracają błąd INVALID_ARGUMENT. Usługa może zwrócić mniej miejsc niż żądano.
include_extended_details Gdy parametr ma wartość true, podsumowanie zawiera rozszerzone informacje o miejscu. Jest to opcja Pro. Domyślna wartość to false.

Opcje wersji Pro

Dwie opcje wybierają kod SKU Pro. Żądanie, które używa jednej lub obu tych funkcji, jest rozliczane w ramach kodu SKU Pro:

Opcja Pro Kiedy z niego korzystać
Adres true został ustawiony jako include_extended_details Prośba użytkownika wymaga rozszerzonych informacji o miejscu, takich jak statystyki z opinii, najważniejsze pozycje w menu, atmosfera czy wskazówki dla odwiedzających.
page_size od 6 do 10 Użytkownik chce porównać więcej niż 5 miejsc.

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

Rozszerzone informacje o miejscu

Ustaw parametr include_extended_details na wartość 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 oparte na opiniach, nastroje klientów i opinie.
  • konkretne oferty: pozycje menu, dania, specjały, 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, czasy 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 znajduje się 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: kuchnie lub typy sklepów, adresy, informacje kontaktowe, godziny otwarcia i standardowe udogodnienia. Przetwarzanie żądań z rozszerzonymi szczegółami trwa dłużej.

Szczegółowe informacje 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 uporządkowane places są takie same w przypadku obu kodów SKU.

Przykład

To żądanie dotyczy maksymalnie 8 miejsc z rozszerzonymi szczegółami. Jest rozliczana 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
}

Bez rozszerzonych 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 · $$$) Przytulna sala 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:

  • 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: szerokość i długość geograficzna 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świetlić w przypadku miejsca. Zobacz Wymagania dotyczące podania źródła.

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

Opcje Pro podczas ograniczonego GA

W okresie ograniczonej GA opcje Pro są dostępne tylko w przypadku projektów z listy dozwolonych Pro. Jeśli Twój projekt nie znajduje się jeszcze na liście dozwolonych, opcje Pro są ignorowane, a nie odrzucane:

  • include_extended_details jest traktowany jako false.
  • page_size wartości powyżej 5, w tym wartości powyżej 10, są zmniejszane do 5.

Żądanie jest rozliczane w ramach kodu SKU Essentials. Aby poprosić o dostęp, zapoznaj się z sekcją Opcje Pro w ramach ograniczonego GA.

Rozliczenia i limity

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

Limit search_places wynosi 300 zapytań na minutę na projekt i jest współdzielony przez obie SKU. Ceny znajdziesz w głównej tabeli cen i tabeli cen w Indiach.