MCP Reference: mapstools.googleapis.com

Wywołaj to narzędzie, gdy użytkownik prosi o znalezienie miejsc, firm, adresów, lokalizacji, ciekawych miejsc lub o inne wyszukiwanie związane z Mapami Google.

Wymagania dotyczące danych wejściowych (KRYTYCZNE):

1. text_query (ciąg znaków – WYMAGANY): główne zapytanie. Musi on jasno określać, czego szuka użytkownik.

   • Przykłady: 'restaurants in New York', 'coffee shops near Golden Gate Park', 'SF MoMA', '1600 Amphitheatre Pkwy, Mountain View, CA, USA', 'pets friendly parks in Manhattan, New York', 'date night restaurants in Chicago', 'accessible public libraries in Los Angeles'.
   • Aby uzyskać informacje o miejscu: dodaj wymagany atrybut (np. 'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address').

2. location_bias (obiekt – OPCJONALNY): użyj tego parametru, aby nadać priorytet wynikom w pobliżu określonego obszaru geograficznego.

   • Format: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
   • Zastosowanie:
     • Aby ustawić promień 5 km: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
     • Aby silnie przesunąć środek: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (pomijając radius_meters).

3. language_code (ciąg znaków – OPCJONALNY): język, w którym ma być wyświetlane podsumowanie wyników wyszukiwania.

   • Format: dwuliterowy kod języka (ISO 639-1), po którym opcjonalnie następuje podkreślenie i dwuliterowy kod kraju (ISO 3166-1 alfa-2), np. en, ja, en_US, zh_CN, es_MX. Jeśli nie podasz kodu języka, wyniki będą w języku angielskim.

4. region_code (ciąg znaków – OPCJONALNY): kod regionu CLDR Unicode użytkownika. Ten parametr służy do wyświetlania informacji o miejscu, takich jak nazwa miejsca w danym regionie, jeśli jest dostępna. Parametr może wpływać na wyniki zgodnie z obowiązującymi przepisami.

   • Format: dwuliterowy kod kraju (ISO 3166-1 alfa-2), np. US, CA.

5. page_size (liczba całkowita – OPCJONALNA): maksymalna liczba miejsc do zwrócenia, od 1 do 10. Domyślna wartość to 5. Ustaw wartość powyżej 5 tylko wtedy, gdy użytkownik chce porównać więcej niż 5 miejsc. Wartości od 6 do 10 wiążą się z wyższymi kosztami i większymi opóźnieniami.

6. include_extended_details (wartość logiczna – OPCJONALNA): ustaw to pole na true, gdy żądanie użytkownika wymaga szczegółowych statystyk jakościowych, dynamiki w czasie rzeczywistym lub specjalistycznych atrybutów encji. Domyślna wartość to false. Ustawienie wartości true wiąże się z wyższymi kosztami i dłuższym czasem oczekiwania.

Instrukcje dotyczące wywołania narzędzia:

• Informacje o lokalizacji (KRYTYCZNE): wyszukiwanie musi zawierać wystarczające informacje o lokalizacji. Jeśli lokalizacja jest niejednoznaczna (np. „pizzerie”), musisz określić ją w parametrze text_query (np. „pizzerie w Nowym Jorku”) lub użyć parametru location_bias. Jeśli jest to konieczne, podaj nazwę miasta, stanu/prowincji i regionu/kraju w celu uściślenia.

• Zawsze podawaj jak najbardziej szczegółowe i bogate w kontekst text_query.

• Używaj location_bias tylko wtedy, gdy współrzędne są wyraźnie podane lub gdy określenie lokalizacji na podstawie znanego kontekstu użytkownika jest odpowiednie i konieczne do uzyskania lepszych wyników.

• Odpowiedź oparta na źródłach musi być przypisana do źródła za pomocą informacji z pola attribution, jeśli są dostępne.

Oblicza trasy podróży między miejscem początkowym a docelowym, opcjonalnie z przystankami pośrednimi. Zwraca odległość i czas trwania każdej trasy.

Wymagania dotyczące danych wejściowych (KRYTYCZNE):

1. origin i destination (obiekty – WYMAGANE): każdy z nich musi być podany za pomocą dokładnie jednej z tych opcji:

   • address (ciąg tekstowy, np. 'Eiffel Tower, Paris'). Nazwane miejsca, punkty orientacyjne i firmy są rozpoznawane bezpośrednio, więc NIE wywołuj najpierw search_places tylko po to, aby uzyskać kod geograficzny punktu na trasie. Uwzględnij miasto, region lub kraj, o którym wspomniał użytkownik.
   • lat_lng (obiekt, {"latitude": number, "longitude": number}).
   • place_id (ciąg znaków, np. 'ChIJOwE_Id1w5EAR4Q27FkL6T_0'), na przykład z search_places.

2. intermediate_waypoints (tablica obiektów – OPCJONALNA): maksymalnie 25 przystanków, przez które należy przejechać, w kolejności między miejscem początkowym a docelowym. Taki sam format jak origin. Nieobsługiwane w przypadku TRANSIT. Uwzględniaj tylko przystanki, o które prosił użytkownik. Podanie więcej niż 10 punktów pośrednich spowoduje wzrost kosztów i opóźnienia.

3. travel_mode (typ wyliczeniowy – OPCJONALNY): DRIVE (domyślny), WALK, BICYCLE lub TRANSIT.

4. Czas (OPCJONALNIE – ustaw maksymalnie JEDNĄ wartość): sygnatury czasowe RFC 3339 z przesunięciem UTC, np. '2026-09-19T08:00:00-07:00'. Domyślnie jest to odjazd w tej chwili. W przypadku TRANSIT czas może wynosić do 7 dni w przeszłości lub do 100 dni w przyszłości. W przypadku innych trybów czas może wynosić do 365 dni w przyszłości i nie może być w przeszłości.

   • departure_time: użyj, gdy użytkownik podaje, kiedy wyjeżdża (np. „jutro o 8:00”).
   • arrival_time: używaj, gdy użytkownik podaje, kiedy musi dotrzeć na miejsce (np. „bądź tam o 9:00”).

5. routing_preference (typ wyliczeniowy – OPCJONALNY):

   • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (domyślna): ignoruje aktualne informacje o natężeniu ruchu, zdarzeniach drogowych i zamkniętych drogach. Najkrótszy czas oczekiwania.
   • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: korzysta z informacji o warunkach na drodze w czasie rzeczywistym, jeśli są dostępne. Nieobsługiwane w przypadku WALK i BICYCLE. Ustaw tę opcję TYLKO wtedy, gdy użytkownik pyta o ruch, korki lub szacowany czas dotarcia na miejsce dostosowany do natężenia ruchu. Powoduje to wyższe koszty i dłuższy czas oczekiwania.

6. location_bias (obiekt – OPCJONALNY): {"latitude": number, "longitude": number} używany do uściślania nazw miejsc w adresach punktów pośrednich. Jeśli nazwa jest niejednoznaczna (np. „Springfield”), a użytkownik nie podał regionu, zachowaj nazwę podaną w polu address i ustaw pole location_bias na obszar docelowy, zamiast zgadywać region.

7. compute_alternative_routes (wartość logiczna – OPCJONALNA): ustaw na true tylko wtedy, gdy użytkownik prosi o opcje lub alternatywne trasy. Domyślna wartość to false, co powoduje zwrócenie tylko zalecanej trasy.

8. include_polyline (wartość logiczna – OPCJONALNA): ustaw na true tylko wtedy, gdy potrzebna jest geometria trasy (encoded_polyline). Domyślna wartość to false.

Instrukcje dotyczące wywołania narzędzia:

• Jeśli brakuje miejsca wylotu lub przylotu, MUSISZ poprosić użytkownika o wyjaśnienie, zanim wywołasz narzędzie.
• W przypadku pytań typu „Jak daleko jest z A do B?” użyj B jako origin i A jako destination.

Przykładowe wywołanie narzędzia: {"origin":{"address":"Wieża Eiffla"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"intermediate_waypoints":[{"address":"Luwr"}],"travel_mode":"DRIVE","departure_time":"2026-09-19T08:00:00+02:00"}

Instrukcje dotyczące odpowiedzi:

• Gdy wysyłane jest żądanie tras alternatywnych, trasy są uporządkowane od najbardziej do najmniej zalecanych.
• Jeśli routes jest puste, poinformuj użytkownika, że nie znaleziono trasy. Nie zgaduj trasy.
• Aby znaleźć miejsca na trasie DRIVE, przekaż retrieval_token trasy do search_along_route. Token jest ważny przez 10 minut.
• Podawaj tylko fakty zwrócone przez narzędzie. NIE wymyślaj szczegółowych wskazówek dojazdu, linii transportu publicznego, stacji, peronów ani przesiadek.
• Uziemione dane wyjściowe muszą być przypisane do źródła za pomocą pola attribution każdej trasy, jeśli jest dostępne.

Wywołaj to narzędzie, gdy użytkownik chce znaleźć miejsca, firmy lub punkty orientacyjne na trasie podróży (np. „stacje benzynowe na trasie do Tahoe”, „kawiarnie między SF a San Jose”). Wywołanie tego narzędzia wiąże się z wyższymi kosztami niż w przypadku search_places, dlatego używaj search_places, gdy wyszukujesz miejsca w pobliżu jednej lokalizacji, a nie na trasie.

Wymagania dotyczące danych wejściowych (KRYTYCZNE):

1. text_query (ciąg znaków – WYMAGANY): opis w języku naturalnym tego, czego szukać na trasie.

   • Przykłady: 'ev chargers', 'coffee', 'vegetarian restaurants', 'rest stops'.

2. Specyfikacja trasy (WYMAGANA – podaj dokładnie JEDNĄ z tych opcji):

   • retrieval_token (ciąg tekstowy): retrieval_token zwrócony przez poprzednie wywołanie compute_routes dla trasy DRIVE. Używaj tej opcji, gdy trasa została już obliczona. Token jest ważny przez 10 minut.
   • route_endpoints (obiekt): origin i destination trasy. Każdy z nich musi być podany za pomocą jednego z tych elementów: address, lat_lng lub place_id.
     • Przykład: {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}
   • encoded_polyline (ciąg znaków): zakodowana linia łamana reprezentująca trasę DRIVE.

3. travel_mode (typ wyliczeniowy – OPCJONALNY): DRIVE (domyślny), WALK lub BICYCLE. Atrybuty WALK i BICYCLE są obsługiwane tylko w przypadku route_endpoints. TRANSIT nie jest obsługiwany.

4. routing_preference (typ wyliczeniowy – OPCJONALNY):

   • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (domyślna): oblicza trasę i objazdy bez uwzględniania informacji o aktualnym natężeniu ruchu. Najkrótszy czas oczekiwania.
   • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: korzysta z informacji o warunkach na drodze w czasie rzeczywistym, jeśli są dostępne. Nieobsługiwane w przypadku WALK i BICYCLE. Ustaw tę opcję TYLKO wtedy, gdy użytkownik pyta o natężenie ruchu, korki lub czas objazdu dostosowany do natężenia ruchu. Powoduje dłuższy czas oczekiwania.

5. include_extended_details (wartość logiczna – OPCJONALNA): ustaw wartość true tylko wtedy, gdy żądanie wymaga statystyk dotyczących opinii jakościowych, konkretnych pozycji menu lub ofert, atmosfery, wskazówek dla odwiedzających lub natężenia ruchu, dostępności ładowarek EV, cen paliwa lub innych szczegółowych informacji jakościowych. Domyślna wartość to false. Włączenie tej opcji może wydłużyć czas oczekiwania.

6. language_code (ciąg znaków – OPCJONALNY): język podsumowania wyników i informacji o miejscu, np. en, ja, en-US. Domyślna wartość to en-US.

7. region_code (ciąg znaków – OPCJONALNY): kod regionu Unicode CLDR użytkownika, np. US, CA.

Instrukcje dotyczące wywołania narzędzia:

• Każdy wynik zawiera detour_summary (jeśli jest dostępny) opisujący dodatkową odległość (localized_detour_distance) i, o ile trasa nie została podana jako encoded_polyline, dodatkowy czas (detour_duration) związany z zatrzymaniem się w tym miejscu. Użyj go, aby porównać opcje.
• Odpowiedź summary może zawierać cytaty indeksowane od zera (np. „[0]”) odwołujące się do wpisów w results.
• Uziemione dane wyjściowe muszą być przypisane do źródła za pomocą pola attribution każdego elementu results[].place, jeśli jest dostępne.

Rozpoznaje listę zbiorczą konkretnych zapytań o lokalizację (nazwy punktów orientacyjnych lub dokładne adresy) i przekształca je w kanoniczne identyfikatory miejsc w Mapach Google.

Wymagania dotyczące danych wejściowych (KRYTYCZNE):

1. queries (tablica obiektów – WYMAGANA): lista zapytań o lokalizację do rozwiązania. Możesz podać maksymalnie 20 zapytań.

   • Każdy obiekt zapytania musi zawierać:
     • text (ciąg tekstowy – WYMAGANY): zapytanie tekstowe reprezentujące konkretną nazwę miejsca lub adres do rozpoznania.
       • Przykłady: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

2. location_bias (obiekt – OPCJONALNY): użyj tego parametru, aby nadać priorytet wynikom w pobliżu określonego obszaru geograficznego.

   • Format: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

3. region_code (ciąg znaków – OPCJONALNY): kod regionu CLDR w standardzie Unicode (dwuliterowy kod kraju, np. US, CA) użytkownika, który ma być używany do filtrowania wyników.

Instrukcje dotyczące wywołania narzędzia:

• Konkretność (KRYTYCZNA): zapytania muszą zawierać konkretną nazwę miejsca lub adres. Ogólne wyszukiwania, takie jak 'restaurants', lub nazwy sieci, takie jak 'Starbucks', nie są obsługiwane.
• NIE wywołuj tego narzędzia, jeśli narzędzia, które planujesz wywołać, akceptują już bezpośrednio nieprzetworzone ciągi znaków adresu lub nazwy miejsca.

Zapisywanie w Mapach Google:

• Odpowiedź zawiera pole save_to_maps_url: pojedynczy link do Map Google zawierający wszystkie miejsca, które udało się znaleźć.
• Gdy użytkownik chce zapisać, udostępnić lub otworzyć znalezione miejsca jako listę w Mapach Google, wyświetl mu ten link. NIE twórz tego linku samodzielnie.

Obsługa błędów (KRYTYCZNE):

• To narzędzie do przetwarzania wsadowego. Żądanie może zwrócić „mieszane wyniki” (np. niektóre zapytania zostaną rozwiązane, a inne nie).
• Lista wyjściowa results jest mapowana 1:1 z indeksami wejściowymi queries. Nieudane zapytanie spowoduje wyświetlenie pustego komunikatu Result (nie ustawiono entity) w odpowiednim indeksie na liście results.
• MUSISZ sprawdzić pole mapy failed_requests w odpowiedzi, aby określić, który indeks zapytania nie został utworzony. Klucz failed_requests reprezentuje indeks nieudanego zapytania w żądaniu (liczony od 0). Nie zakładaj, że całe wywołanie zbiorcze nie powiodło się z powodu częściowego niepowodzenia.

Rozpoznaje listę adresów URL Map Google i przekształca je w kanoniczne identyfikatory miejsc w Mapach Google.

Kiedy wywołać to narzędzie (KRYTYCZNE):

• Użyj tego narzędzia, gdy użytkownik poda co najmniej 1 link lub adres URL do udostępniania w Mapach Google (np. „https://maps.app.goo.gl/...”, 'https://www.google.com/maps/place/...' lub 'https://maps.google.com/...') i musisz wyodrębnić podstawowe kanoniczne identyfikatory miejsc.
• W jednym żądaniu zbiorczym możesz określić maksymalnie 20 adresów URL do rozpoznania.

Wymagania dotyczące danych wejściowych (KRYTYCZNE):

• urls (tablica ciągów znaków – WYMAGANE): lista adresów URL Map Google do rozpoznania. Każdy adres URL musi być prawidłowym adresem URL Map Google wskazującym jedno miejsce.

Zapisywanie w Mapach Google:

• Odpowiedź zawiera pole save_to_maps_url: pojedynczy link do Map Google zawierający wszystkie miejsca, które udało się znaleźć.
• Gdy użytkownik chce zapisać, udostępnić lub otworzyć znalezione miejsca jako listę w Mapach Google (np. zbierając miejsca udostępnione w rozmowie), wyświetl mu ten link. NIE twórz tego linku samodzielnie.

Obsługa błędów (KRYTYCZNE):

• To narzędzie do przetwarzania wsadowego. Żądanie może zwrócić „mieszane wyniki” (np. niektóre adresy URL zostaną rozwiązane, a inne nie).
• Lista wyjściowa entities jest mapowana 1:1 z indeksami wejściowymi urls. Niepowodzenie rozpoznania adresu URL spowoduje, że na liście entities pod odpowiednim indeksem pojawi się pusta wiadomość Entity (bez ustawionych pól).
• MUSISZ sprawdzić pole mapy failed_requests w odpowiedzi, aby dowiedzieć się, który indeks adresu URL nie został utworzony. Klucz failed_requests reprezentuje indeks nieudanego adresu URL w żądaniu (liczony od 0). Nie zakładaj, że całe wywołanie zbiorcze nie powiodło się z powodu częściowego niepowodzenia.