Wprowadzenie
Wyszukaj tekst (Nowe) zwraca informacje o zbiorze Miejsc na podstawie ciągu znaków (np. „pizza w Nowym Jorku”, „sklepy obuwnicze w pobliżu Warszawy” lub „ul. Główna 123”). Usługa odpowiada listą miejsc pasujących do ciągu tekstowego i ustawionych preferencji lokalizacji.
Oprócz wymaganych parametrów Wyszukaj tekst (New) obsługuje doprecyzowywanie zapytań za pomocą opcjonalnych parametrów, aby uzyskiwać lepsze wyniki.
Narzędzie APIs Explorer umożliwia wysyłanie żądań w czasie rzeczywistym, dzięki czemu możesz zapoznać się z interfejsem API i jego opcjami:
Żądania wyszukiwania tekstowego (nowe)
Żądanie wyszukiwania tekstowego (nowego) to żądanie HTTP POST w tej postaci:
https://places.googleapis.com/v1/places:searchText
Przekaż wszystkie parametry w treści żądania JSON lub w nagłówkach w ramach żądania POST. Na przykład:
curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'Odpowiedzi z wyszukiwania tekstowego (nowa wersja)
Wyszukiwanie tekstowe (nowe) zwraca obiekt JSON jako odpowiedź. W odpowiedzi:
- Tablica
placeszawiera wszystkie pasujące miejsca. - Każde miejsce w tablicy jest reprezentowane przez obiekt
Place. ObiektPlacezawiera szczegółowe informacje o jednym miejscu. - Pole FieldMask przekazane w żądaniu określa listę pól zwracanych w obiekcie
Place. - Nie ma gwarancji, że lista zwróconych miejsc będzie spójna w przypadku identycznych żądań.
Kompletny obiekt JSON ma postać:
{
"places": [
{
object (Place)
}
]
}Wymagane parametry
-
FieldMask
Określ listę pól, które mają zostać zwrócone w odpowiedzi, tworząc maskę pola odpowiedzi. Przekaż maskę pola odpowiedzi do metody za pomocą parametru adresu URL
$fieldslubfieldsalbo za pomocą nagłówka HTTPX-Goog-FieldMask. W odpowiedzi nie ma domyślnej listy zwracanych pól. Jeśli pominiesz maskę pola, metoda zwróci błąd.Maskowanie pól to dobra praktyka projektowania, która pozwala uniknąć wysyłania żądań dotyczących niepotrzebnych danych. Dzięki temu można skrócić czas przetwarzania i uniknąć niepotrzebnych opłat.
Podaj listę typów danych o miejscu rozdzieloną przecinkami, które mają zostać zwrócone. Na przykład aby pobrać wyświetlaną nazwę i adres miejsca.
X-Goog-FieldMask: places.displayName,places.formattedAddress
Użyj
*, aby pobrać wszystkie pola.X-Goog-FieldMask: *
Określ co najmniej jedno z tych pól:
Te pola aktywują identyfikator SKU Wyszukaj tekst Essentials ID Only:
places.attributions
places.id
places.consumerAlert
places.name*
nextPageToken
places.movedPlace
places.movedPlaceId* Pole
places.namezawiera nazwę zasobu miejsca w formacieplaces/PLACE_ID. Użyjplaces.displayNamew wersji Pro, aby uzyskać dostęp do tekstowej nazwy miejsca.Pełną listę pól i powiązanych z nimi kodów SKU znajdziesz w sekcji Pola danych o miejscach (nowe).
Te pola aktywują SKU Wyszukaj tekst Pro:
places.accessibilityOptions
places.addressComponents
places.addressDescriptor*
places.adrFormatAddress
places.businessStatus
places.containingPlaces
places.displayName
places.formattedAddress
places.googleMapsLinks
places.googleMapsTypeLabel
places.googleMapsUri
places.iconBackgroundColor
places.iconMaskBaseUri
places.location
places.openingDate
places.photos
places.plusCode
places.postalAddress
places.primaryType
places.primaryTypeDisplayName
places.pureServiceAreaBusiness
places.shortFormattedAddress
places.searchUri
places.subDestinations
places.timeZone
places.types
places.utcOffsetMinutes
places.viewport
* Opisy adresów są ogólnie dostępne dla klientów w Indiach, a w innych krajach są w fazie eksperymentalnej.Pełną listę pól i powiązanych z nimi kodów SKU znajdziesz w sekcji Pola danych o miejscach (nowe).
Następujące pola wywołują SKU Wyszukaj tekst Enterprise:
places.currentOpeningHours
places.currentSecondaryOpeningHours
places.internationalPhoneNumber
places.nationalPhoneNumber
places.priceLevel
places.priceRange
places.rating
places.regularOpeningHours
places.regularSecondaryOpeningHours
places.transitStation
places.userRatingCount
places.websiteUriPełną listę pól i powiązanych z nimi kodów SKU znajdziesz w artykule Pola danych o miejscach (nowe).
Te pola wywołują kod SKU Wyszukaj tekst Enterprise + Atmosphere:
places.allowsDogs
places.curbsidePickup
places.delivery
places.dineIn
places.editorialSummary
places.evChargeAmenitySummary
places.evChargeOptions
places.fuelOptions
places.generativeSummary
places.goodForChildren
places.goodForGroups
places.goodForWatchingSports
places.liveMusic
places.menuForChildren
places.neighborhoodSummary
places.parkingOptions
places.paymentOptions
places.outdoorSeating
places.reservable
places.restroom
places.reviews
places.reviewSummary
routingSummaries*
places.servesBeer
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDessert
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
* Tylko wyszukiwanie tekstowe i wyszukiwanie w pobliżuPełną listę pól i powiązanych z nimi kodów SKU znajdziesz w artykule Pola danych o miejscu (nowe).
-
textQuery
Ciąg tekstowy, w którym ma zostać przeprowadzone wyszukiwanie. Na przykład „restauracja”, „ulica Główna 123” lub „Najlepsze miejsce do odwiedzenia w San Francisco”. Interfejs API zwraca pasujące kandydatury na podstawie tego ciągu znaków i porządkuje wyniki według ich trafności.
Wyszukiwanie tekstowe (nowe) nie jest przeznaczone do niejednoznacznych zapytań, w tym:
Typ zapytania Przykład Zbyt wiele pojęć lub ograniczeń, np. nazwy wielu miejsc, dróg lub miast w jednym zapytaniu. „Market Street San Francisco San Jose Airport” Elementy adresu pocztowego nie są reprezentowane w Mapach Google „C/O John Smith 123 Main Street”
„P.O. Box 13 San Francisco”nazwy firm, sieci lub kategorii połączone z lokalizacjami, w których te podmioty nie są dostępne; „Tesco w pobliżu Dallas w Teksasie” Niejednoznaczne zapytania z wieloma interpretacjami „Oddanie ładowarki” Historyczne nazwy, które nie są już używane "Middlesex United Kingdom" Elementy lub intencje niegeoprzestrzenne „Ile łodzi jest w porcie Ventura?” Nieoficjalne lub wymyślone nazwy „The Jenga”
„The Helter Skelter”Współrzędne geograficzne "37.422131,-122.084801"
Parametry opcjonalne
-
includeFutureOpeningBusinesses
Jeśli
true, zwraca firmy, które mają zostać otwarte w przyszłości. Domyślna wartość tofalse.
Aby pobrać stan firmy, w masce pola żądania uwzględnijplaces.businessStatus. Aby pobrać przewidywaną datę otwarcia firmy, w masce pola żądania uwzględnijplaces.openingDate. -
includedType
Zawęża wyniki do miejsc pasujących do określonego typu zdefiniowanego w tabeli A. Można określić tylko 1 typ. Na przykład:
"includedType":"bar""includedType":"pharmacy"
Wyszukaj tekst (Nowe) stosuje filtrowanie według typu w przypadku niektórych zapytań, w zależności od ich zastosowania. Na przykład filtrowanie według typu może nie być stosowane do zapytań o konkretne adresy („ul. Główna 123”), ale prawie zawsze jest stosowane do zapytań kategorialnych („sklepy w pobliżu” lub „centra handlowe”).
Aby zastosować filtrowanie typu do wszystkich zapytań, ustaw wartość
strictTypeFilteringnatrue. -
includePureServiceAreaBusinesses
Jeśli ustawisz wartość
true, odpowiedź będzie zawierać firmy, które odwiedzają klientów lub dostarczają im produkty bezpośrednio, ale nie mają fizycznej lokalizacji. Jeśli ustawisz wartośćfalse, interfejs API będzie zwracać tylko firmy, które mają fizyczną lokalizację. languageCode
Język, w którym mają być zwracane wyniki.
- Zobacz listę obsługiwanych języków. Google często aktualizuje listę obsługiwanych języków, więc może ona nie być wyczerpująca.
-
Jeśli nie podasz wartości
languageCode, interfejs API domyślnie użyje wartościen. Jeśli podasz nieprawidłowy kod języka, API zwróci błądINVALID_ARGUMENT. - Interfejs API stara się podać adres ulicy, który jest czytelny zarówno dla użytkownika, jak i miejscowych. Aby to osiągnąć, zwraca adresy w języku lokalnym, a w razie potrzeby transliteruje je na pismo czytelne dla użytkownika, uwzględniając preferowany język. Wszystkie pozostałe adresy są zwracane w preferowanym języku. Wszystkie komponenty adresu są zwracane w tym samym języku, który jest wybierany na podstawie pierwszego komponentu.
- Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API użyje najbliższego dopasowania.
- Preferowany język ma niewielki wpływ na zbiór wyników, które interfejs API wybiera do zwrócenia, oraz na kolejność, w jakiej są one zwracane. Geokoder interpretuje skróty w różny sposób w zależności od języka, np. skróty typów ulic lub synonimy, które mogą być prawidłowe w jednym języku, ale nie w innym.
locationBias
Określa obszar wyszukiwania. Ta lokalizacja służy jako punkt odniesienia, co oznacza, że mogą być zwracane wyniki z określonej lokalizacji, w tym wyniki spoza określonego obszaru.
Możesz podać
locationRestrictionlublocationBias, ale nie oba te parametry.locationRestrictionokreśla region, w którym muszą się znajdować wyniki, alocationBiasokreśla region, w którym wyniki prawdopodobnie będą się znajdować lub w pobliżu którego będą się znajdować, ale mogą być poza tym obszarem.Określ region jako prostokątny widok lub okrąg.
Okrąg jest zdefiniowany przez punkt środkowy i promień w metrach. Promień musi mieścić się w zakresie od 0,0 do 50 000,0 włącznie. Domyślny promień to 0,0. Na przykład:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Prostokąt to widoczny obszar określony przez szerokość i długość geograficzną, reprezentowany przez 2 przeciwległe punkty o niskich i wysokich wartościach. Punkt dolny wyznacza południowo-zachodni róg prostokąta, a punkt górny – północno-wschodni róg prostokąta.
Obszar widoku jest uważany za zamknięty region, co oznacza, że obejmuje swoje granice. Zakres szerokości geograficznej musi mieścić się w przedziale od -90 do 90 stopni włącznie, a zakres długości geograficznej musi mieścić się w przedziale od -180 do 180 stopni włącznie:
- Jeśli
low=high, widoczny obszar składa się z tego jednego punktu. - Jeśli
low.longitude>high.longitude, zakres długości geograficznej jest odwrócony (obszar widoczny przekracza linię długości geograficznej 180 stopni). - Jeśli
low.longitude= –180 stopni, ahigh.longitude= 180 stopni, widoczny obszar obejmuje wszystkie długości geograficzne. - Jeśli
low.longitude= 180 stopni ihigh.longitude= –180 stopni, zakres długości geograficznej jest pusty. - Jeśli
low.latitude>high.latitude, zakres szerokości geograficznej jest pusty.
Należy wypełnić zarówno dolną, jak i górną wartość, a reprezentowane pole nie może być puste. Pusty obszar wyświetlania powoduje błąd.
Na przykład ten obszar widoku obejmuje w całości Nowy Jork:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- Jeśli
locationRestriction
Określa obszar wyszukiwania tylko w przypadku zapytań dotyczących kategorii, które mogą zwracać wiele miejsc (np. „Restauracje w Nowym Jorku” lub „Centra handlowe”). Wyniki spoza określonego obszaru nie są zwracane.
Określ region jako prostokątny widoczny obszar. Przykład definiowania widocznego obszaru znajdziesz w opisie
locationBias.Możesz podać
locationRestrictionlublocationBias, ale nie oba te parametry. ParametrlocationRestrictionokreśla region, w którym muszą znajdować się wyniki, a parametrlocationBiasokreśla region, w którym wyniki prawdopodobnie będą się znajdować lub będą blisko niego, ale mogą też znajdować się poza nim.-
maxResultCount (wycofane)
Określa liczbę wyników (od 1 do 20) wyświetlanych na stronie. Jeśli np. ustawisz wartość
maxResultCountna 5, na pierwszej stronie pojawi się maksymalnie 5 wyników. Jeśli zapytanie może zwrócić więcej wyników, odpowiedź zawiera tokennextPageToken, który możesz przekazać w kolejnym żądaniu, aby uzyskać dostęp do następnej strony. evOptions
Określa parametry identyfikowania dostępnych złączy ładowania pojazdów elektrycznych (EV) i szybkości ładowania.
connectorTypes
Filtruje według typu złącza ładowania EV dostępnego w danym miejscu. Miejsce, które nie obsługuje żadnego z typów złączy, zostanie odfiltrowane. Obsługiwane typy złączy do ładowania EV obejmują ładowarki łączone (AC i DC), ładowarki Tesla, ładowarki zgodne ze standardem GB/T (do szybkiego ładowania EV w Chinach) i ładowarki do gniazdek ściennych. Więcej informacji znajdziesz w dokumentacji referencyjnej.
- Aby filtrować wyniki pod kątem konkretnego obsługiwanego łącznika, ustaw wartość
connectorTypes. Jeśli na przykład chcesz znaleźć złącza J1772 typu 1, ustawconnectorTypesnaEV_CONNECTOR_TYPE_J1772. - Aby filtrować wyniki dotyczące nieobsługiwanych łączników, ustaw wartość
connectorTypesnaEV_CONNECTOR_TYPE_OTHER. - Aby filtrować wyniki pod kątem dowolnego typu złącza, które jest gniazdkiem ściennym, ustaw wartość
connectorTypesnaEV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET. - Aby filtrować wyniki według dowolnego typu oprogramowania sprzęgającego, ustaw
connectorTypesnaEV_CONNECTOR_TYPE_UNSPECIFIEDlub nie ustawiaj wartości dlaconnectorTypes.
- Aby filtrować wyniki pod kątem konkretnego obsługiwanego łącznika, ustaw wartość
minimumChargingRateKw
Filtruje miejsca według minimalnej mocy ładowania EV w kilowatach (kW). Wszystkie miejsca, w których stawka ładowania jest niższa od minimalnej stawki ładowania, są odfiltrowywane. Jeśli na przykład chcesz znaleźć ładowarki EV o mocy co najmniej 10 kW, możesz ustawić ten parametr na „10”.
minRating
Ogranicza wyniki tylko do tych, których średnia ocena użytkowników jest większa lub równa temu limitowi. Wartości muszą mieścić się w zakresie od 0,0 do 5,0 (włącznie) w odstępach co 0,5. Na przykład: 0, 0,5, 1,0, … , 5,0 włącznie. Wartości są zaokrąglane w górę do najbliższej wartości z końcówką 0,5. Na przykład wartość 0,6 eliminuje wszystkie wyniki z oceną mniejszą niż 1,0.
openNow
Jeśli
true, zwracaj tylko te miejsca, które są otwarte w momencie wysłania zapytania. Jeślifalse, zwróć wszystkie firmy niezależnie od stanu otwarcia. Jeśli ustawisz ten parametr nafalse, zwracane będą miejsca, które nie mają określonych godzin otwarcia w bazie danych Miejsc Google.pageSize
Określa liczbę wyników (od 1 do 20) wyświetlanych na stronie. Jeśli np. ustawisz wartość
pageSizena 5, na pierwszej stronie pojawi się maksymalnie 5 wyników. Jeśli zapytanie może zwrócić więcej wyników, odpowiedź zawiera parametrnextPageToken, który możesz przekazać w kolejnym żądaniu, aby uzyskać dostęp do następnej strony.pageToken
Określa
nextPageTokenz treści odpowiedzi na poprzedniej stronie.-
priceLevels
Ogranicz wyszukiwanie do miejsc o określonym poziomie cen. Domyślnie wybrane są wszystkie poziomy cenowe.
Poziomy cen można oczekiwać w przypadku miejsc tych typów:
Jeśli określono
priceLevels, miejsca nieobsługiwanych typów nie będą uwzględniane w odpowiedzi.Określ tablicę zawierającą co najmniej 1 wartość zdefiniowaną przez
PriceLevel.Na przykład:
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
rankPreference
Określa, w jaki sposób wyniki są klasyfikowane w odpowiedzi na podstawie typu zapytania:
- W przypadku zapytania kategorycznego, np. „Restauracje w Nowym Jorku”, domyślnie stosowana jest opcja
RELEVANCE(sortuj wyniki według trafności wyszukiwania). Możesz ustawić parametrrankPreferencenaRELEVANCElubDISTANCE(wyniki będą sortowane według odległości). - W przypadku zapytań niekategorycznych, takich jak „Mountain View, CA”, zalecamy pozostawienie wartości
rankPreferencebez ustawienia.
- W przypadku zapytania kategorycznego, np. „Restauracje w Nowym Jorku”, domyślnie stosowana jest opcja
regionCode
Kod regionu używany do formatowania odpowiedzi, podany jako dwuznakowy kod CLDR. Ten parametr może też wpływać na wyniki wyszukiwania. Nie ma wartości domyślnej.
Jeśli nazwa kraju w polu
formattedAddressw odpowiedzi pasuje doregionCode, kod kraju jest pomijany w poluformattedAddress. Ten parametr nie ma wpływu naadrFormatAddress, który zawsze zawiera nazwę kraju, jeśli jest dostępna, ani nashortFormattedAddress, który nigdy jej nie zawiera.Większość kodów CLDR jest identyczna z kodami ISO 3166-1, z kilkoma istotnymi wyjątkami. Na przykład krajowa domena najwyższego poziomu Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”). W zależności od obowiązujących przepisów parametr może wpływać na wyniki.
strictTypeFiltering
Używany z parametrem
includedType. Jeśli ustawisz wartośćtrue, zwracane będą tylko miejsca pasujące do określonych typów określonych przezincludedType. Jeśli ma wartość false (domyślnie), odpowiedź może zawierać miejsca, które nie pasują do określonych typów.
Przykłady wyszukiwania tekstowego (nowego)
Znajdowanie miejsca za pomocą ciągu zapytania
Poniższy przykład pokazuje żądanie wyszukiwania tekstowego (nowego) dotyczące „pikantnego jedzenia wegetariańskiego w Sydney w Australii”:
curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'
Zwróć uwagę, że nagłówek X-Goog-FieldMask określa, że odpowiedź zawiera te pola danych: places.displayName,places.formattedAddress.
Odpowiedź ma wtedy postać:
{ "places": [ { "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia", "displayName": { "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney", "languageCode": "en" } }, { "formattedAddress": "29 King St, Sydney NSW 2000, Australia", "displayName": { "text": "Peace Harmony", "languageCode": "en" } }, ... ] }
Dodaj do maski pola więcej typów danych, aby zwracać dodatkowe informacje.
Na przykład dodaj places.types,places.websiteUri, aby w odpowiedzi uwzględnić typ restauracji i adres internetowy:
curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri' \
'https://places.googleapis.com/v1/places:searchText'Odpowiedź ma teraz postać:
{ "places": [ { "types": [ "vegetarian_restaurant", "vegan_restaurant", "chinese_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "websiteUri": "http://www.motherchusvegetarian.com.au/", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "types": [ "vegan_restaurant", "thai_restaurant", "vegetarian_restaurant", "indian_restaurant", "italian_restaurant", "american_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia", "websiteUri": "http://www.veggosizzle.com.au/", "displayName": { "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney", "languageCode": "en" } }, ... ] }
Filtrowanie miejsc według poziomu cen
Użyj opcji priceLevel, aby przefiltrować wyniki i wyświetlić restauracje, które są określone jako niedrogie lub umiarkowanie drogie:
curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'W tym przykładzie użyto też nagłówka X-Goog-FieldMask, aby dodać pole danych places.priceLevel do odpowiedzi, tak aby miało ono postać:
{ "places": [ { "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "priceLevel": "PRICE_LEVEL_MODERATE", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "formattedAddress": "115 King St, Newtown NSW 2042, Australia", "priceLevel": "PRICE_LEVEL_MODERATE", "displayName": { "text": "Green Mushroom", "languageCode": "en" } }, ... ] }
Dodaj dodatkowe opcje, aby zawęzić wyszukiwanie, np. includedType, minRating, rankPreference, openNow i inne parametry opisane w sekcji Parametry opcjonalne.
Ograniczanie wyszukiwania do określonego obszaru
Aby ograniczyć wyszukiwanie do danego obszaru, użyj operatora locationRestriction lub locationBias, ale nie obu jednocześnie. locationRestriction
określa region, w którym muszą się znajdować wyniki, a locationBias
określa region, w pobliżu którego muszą się znajdować wyniki, ale mogą być poza tym obszarem.
Ograniczanie obszaru za pomocą parametru locationRestriction
Użyj parametru locationRestriction, aby ograniczyć wyniki zapytania do określonego regionu. W treści żądania podaj wartości low i high szerokości i długości geograficznej, które określają granicę regionu.
Poniższy przykład pokazuje żądanie wyszukiwania tekstowego (nowego) dotyczące „jedzenia wegetariańskiego” w Nowym Jorku. To żądanie zwraca tylko pierwsze 10 wyników dla otwartych miejsc.
curl -X POST -d '{
"textQuery" : "vegetarian food",
"pageSize" : "10",
"locationRestriction": {
"rectangle": {
"low": {
"latitude": 40.477398,
"longitude": -74.259087
},
"high": {
"latitude": 40.91618,
"longitude": -73.70018
}
}
}
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.id,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'
Określanie obszaru za pomocą parametru locationBias
Poniższy przykład pokazuje żądanie wyszukiwania tekstowego (nowego) dotyczące „jedzenia wegetariańskiego” z określeniem lokalizacji w promieniu 500 metrów od punktu w centrum San Francisco. To żądanie zwraca tylko pierwszych 10 wyników dotyczących otwartych miejsc.
curl -X POST -d '{
"textQuery" : "vegetarian food",
"openNow": true,
"pageSize": 10,
"locationBias": {
"circle": {
"center": {"latitude": 37.7937, "longitude": -122.3965},
"radius": 500.0
}
},
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'
Wyszukiwanie ładowarek EV o minimalnej szybkości ładowania
Używaj minimumChargingRateKw i connectorTypes, aby wyszukiwać miejsca z dostępnymi ładowarkami zgodnymi z Twoim pojazdem elektrycznym.
Poniższy przykład pokazuje żądanie dotyczące ładowarek EV Tesla i J1772 typu 1 o minimalnej szybkości ładowania 10 kW w Mountain View w Kalifornii. Zwracane są tylko 4 wyniki.
curl -X POST -d '{
"textQuery": "EV Charging Station Mountain View",
"pageSize": 4,
"evOptions": {
"minimumChargingRateKw": 10,
"connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"]
}
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \
'https://places.googleapis.com/v1/places:searchText'
Żądanie zwraca tę odpowiedź:
{ "places": [ { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 16, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_CHADEMO", "maxChargeRateKw": 100, "count": 8, "availableCount": 5, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 100, "count": 2, "availableCount": 2, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 350, "count": 6, "availableCount": 3, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 6, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 100, "count": 4, "availableCount": 3, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 350, "count": 2, "availableCount": 0, "outOfServiceCount": 2, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 5, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_J1772", "maxChargeRateKw": 3.5999999046325684, "count": 1, "availableCount": 0, "outOfServiceCount": 1, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CHADEMO", "maxChargeRateKw": 50, "count": 2, "availableCount": 0, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 50, "count": 2, "availableCount": 0, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, { "displayName": { "text": "Electric Vehicle Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 10, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_OTHER", "maxChargeRateKw": 210, "count": 10 } ] } } ] }
Wyszukiwanie firm działających na określonym obszarze
Użyj parametru includePureServiceAreaBusinesses, aby wyszukać firmy, które nie mają fizycznego adresu świadczenia usługi (np. mobilna usługa sprzątania lub food truck).
Poniżej znajdziesz przykład żądania dotyczącego hydraulików w San Francisco:
curl -X POST -d '{
"textQuery" : "plumber San Francisco",
"includePureServiceAreaBusinesses": true
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'
W odpowiedzi firmy bez fizycznego adresu usługi nie uwzględniają pola formattedAddress:
{ "places": [ { "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA", "displayName": { "text": "Advanced Plumbing & Drain", "languageCode": "en" } }, { "formattedAddress": "1455 Bancroft Ave, San Francisco, CA 94124, USA", "displayName": { "text": "Magic Plumbing Heating & Cooling", "languageCode": "en" } }, /.../ { "displayName": { "text": "Starboy Plumbing Inc.", "languageCode": "en" } }, { "formattedAddress": "78 Dorman Ave, San Francisco, CA 94124, USA", "displayName": { "text": "Cabrillo Plumbing, Heating & Air", "languageCode": "en" } }, { "formattedAddress": "540 Barneveld Ave # D, San Francisco, CA 94124, USA", "displayName": { "text": "Mr. Rooter Plumbing of San Francisco", "languageCode": "en" } }, /.../ { "displayName": { "text": "Pipeline Plumbing", "languageCode": "en" } }, { "formattedAddress": "350 Bay St #100-178, San Francisco, CA 94133, USA", "displayName": { "text": "One Source Plumbing and Rooter", "languageCode": "en" } }, /.../ ] }
Określanie liczby wyników do zwrócenia na stronie
Użyj parametru pageSize, aby określić liczbę wyników na stronie. Parametr nextPageToken w treści odpowiedzi zawiera token, którego można użyć w kolejnych wywołaniach, aby uzyskać dostęp do następnej strony wyników.
Poniższy przykład pokazuje żądanie „pizza w Nowym Jorku” ograniczone do 5 wyników na stronę:
curl -X POST -d '{
"textQuery": "pizza in New York",
"pageSize": 5
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'
{ "places": [ { "id": "ChIJifIePKtZwokRVZ-UdRGkZzs" }, { "id": "ChIJPxPd_P1YwokRfzLhSiACEoU" }, { "id": "ChIJrXXKn5NZwokR78g0ipCnY60" }, { "id": "ChIJ6ySICVZYwokR9rIK8HjXhzE" }, { "id": "ChIJ6xvs94VZwokRnT1D2lX2OTw" } ], "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q" }
Aby przejść do następnej strony wyników, użyj parametru pageToken, aby przekazać parametr nextPageToken w treści żądania:
curl -X POST -d '{
"textQuery": "pizza in New York",
"pageSize": 5,
"pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'
{ "places": [ { "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw" }, { "id": "ChIJjaD94kFZwokR-20CXqlpy_4" }, { "id": "ChIJ6ffdpJNZwokRmcafdROM5q0" }, { "id": "ChIJ8Q2WSpJZwokRQz-bYYgEskM" }, { "id": "ChIJ8164qwFZwokRhplkmhvq1uE" } ], "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c" }
Pobieranie deskryptorów adresu
Deskryptory adresów zawierają informacje o lokalizacji miejsca, w tym o pobliskich punktach orientacyjnych i obszarach.
Poniższy przykład pokazuje żądanie wyszukiwania tekstowego (nowe) dotyczące miejsc w pobliżu centrum handlowego w San Jose. W tym przykładzie w polu maski uwzględniasz addressDescriptors:
curl -X POST -d '{
"textQuery": "clothes",
"maxResultCount": 5,
"locationBias": {
"circle": {
"center": {
"latitude": 37.321328,
"longitude": -121.946275
}
}
},
"rankPreference":"RANK_PREFERENCE_UNSPECIFIED"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchText
Odpowiedź zawiera miejsce określone w żądaniu, listę pobliskich punktów orientacyjnych i ich odległość od tego miejsca oraz listę obszarów i ich relację do tego miejsca:
{ "places": [ { "displayName": { "text": "Urban Outfitters", "languageCode": "en" }, "addressDescriptor": { "landmarks": [ { "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s", "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s", "displayName": { "text": "Westfield Valley Fair", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "food", "movie_theater", "point_of_interest", "restaurant", "shoe_store", "shopping_mall", "store" ], "spatialRelationship": "WITHIN", "straightLineDistanceMeters": 133.72855 }, { "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4", "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4", "displayName": { "text": "Nordstrom", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "point_of_interest", "shoe_store", "store" ], "straightLineDistanceMeters": 250.99161 }, { "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4", "placeId": "ChIJ8WvuSB7Lj4ARFyHppkxDRQ4", "displayName": { "text": "Macy's", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "point_of_interest", "store" ], "straightLineDistanceMeters": 116.24196 }, { "name": "places/ChIJ9d3plB_Lj4ARzyaU5bn80WY", "placeId": "ChIJ9d3plB_Lj4ARzyaU5bn80WY", "displayName": { "text": "Bank of America Financial Center", "languageCode": "en" }, "types": [ "bank", "establishment", "finance", "point_of_interest" ], "straightLineDistanceMeters": 121.61515 }, { "name": "places/ChIJaXCjxvXLj4ARCPmQpvJ52Lw", "placeId": "ChIJaXCjxvXLj4ARCPmQpvJ52Lw", "displayName": { "text": "Bloomingdale's", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "furniture_store", "home_goods_store", "point_of_interest", "shoe_store", "store" ], "straightLineDistanceMeters": 81.32396 } ], "areas": [ { "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI", "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI", "displayName": { "text": "Westfield Valley Fair", "languageCode": "en" }, "containment": "WITHIN" }, { "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q", "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q", "displayName": { "text": "Valley Fair", "languageCode": "en" }, "containment": "WITHIN" }, { "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM", "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM", "displayName": { "text": "Central San Jose", "languageCode": "en" }, "containment": "WITHIN" } ] } }, /.../ ] }
Znajdowanie firm, które zostaną otwarte w przyszłości
Poniższy przykład pokazuje żądanie wyszukiwania tekstowego (nowego) dotyczące firm, które zostaną otwarte w przyszłości w New Meadows w Idaho:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.businessStatus,places.openingDate" \
-d '{
"textQuery": "Roberts Greenhouse and Tree Farm",
"includeFutureOpeningBusinesses": true,
"maxResultCount": 20,
"locationBias": {
"circle": {
"center": {"latitude": 44.9755100, "longitude": -116.2842180},
"radius": 20
}
}
}' \
"https://places.googleapis.com/v1/places:searchText"
Odpowiedź zawiera firmy, które zostaną otwarte w przyszłości, wraz z ich statusem i przewidywaną datą otwarcia:
{ "places": [ { "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do", "businessStatus": "FUTURE_OPENING", "displayName": { "text": "Roberts Greenhouse and Tree Farm", "languageCode": "en" }, "openingDate": { "year": 2026, "month": 4, "day": 15 } } ] }
Uzyskiwanie informacji o stacjach transportu publicznego
Aby znaleźć stacje transportu publicznego, możesz użyć wyszukiwania tekstowego (nowego). Treść odpowiedzi zawiera informacje o stacji, w tym jej nazwę, powiązanych przewoźników i linie transportu publicznego obsługujące stację. Dodatkowo odpowiedź zawiera ikonę pojazdu i kolory, których możesz użyć do wyświetlenia informacji o stacji transportu publicznego.
Poniżej znajdziesz przykładowe żądanie dotyczące „Grand Central Station”:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.transitStation" \
-d '{
"textQuery": "Grand Central Station"
}' \
"https://places.googleapis.com/v1/places:searchText"
Treść odpowiedzi zawiera informacje o każdej stacji w promieniu, liniach obsługiwanych przez stację, alertach wydanych przez przewoźników na tym przystanku oraz informacje o odjazdach:
{ "places": [ { "id": "ChIJhRwB-yFawokRi0AhGH87UTc", "displayName": { "text": "Grand Central", "languageCode": "en" }, "transitStation": { "displayName": { "text": "Grand Central", "languageCode": "en" }, "agencies": [ { "displayName": { "text": "Metro-North Railroad", "languageCode": "en" }, "url": "http://www.mta.info/mnr", "lines": [ { "id": "ChIJOXpD29y2wokRryDO0CocwK0", "vehicleType": "HEAVY_RAIL", "displayName": { "text": "Harlem", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#0061AA", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg" }, "alerts": [ { "effect": "OTHER", "texts": [ { "headline": { "text": "Information", "languageCode": "en" }, "summary": { "text": "Temporary platforms are in place at Botanical Garden, Williams Bridge, and Woodlawn for northbound travel. Build in extra travel time to reach the platform.", "languageCode": "en" }, "fullDescription": { "text": "What's Happening? We are renovating some Harlem Line stations in the Bronx. Learn more about the project here.", "languageCode": "en" } } ], "detailsUrls": [ { "url": "https://new.mta.info/" } ], "cause": "OTHER_CAUSE", "startTime": "2026-04-16T04:00:00Z", "endTime": "2026-12-01T04:45:00Z", "attribution": { "link": { "text": "new.mta.info", "url": "https://new.mta.info/" } }, "createTime": "2026-05-15T22:39:30Z", "severityLevel": "INFO" } ] }, ... ] }, ... ] "stops": [ { "id": "ChIJOfdrigFZwokRJPllLwfPrJY", "location": { "latitude": 40.752823, "longitude": -73.977195999999992 }, "wheelchairAccessibleEntrance": true } ], "departureBoards": [ { "displayType": "TIME_CENTRIC", "rows": [ { "departures": [ { "timedDeparture": { "scheduledTime": "2026-05-15T22:42:00Z", "timingType": "SCHEDULED", "predictedTime": "2026-05-15T22:42:00Z", "updateTime": "2026-05-15T22:38:50Z" }, "originallyScheduledStopId": "ChIJOfdrigFZwokRJPllLwfPrJY", "lineId": "ChIJAfBuQhwg6IkRYnFpClHxFrM" } ] }, ... ] } ] } }, { "id": "ChIJ_4EAi-pZwokRWe5T1JmmWmc", "displayName": { "text": "Grand Central Station", "languageCode": "en" } } ] }
Znajdowanie wejść i punktów nawigacyjnych
Możesz poprosić o podanie wejść i punktów nawigacyjnych w miejscu docelowym. Wejścia określają punkty wejścia i wyjścia z miejsca (np. różne bramki na lotnisku lub w centrum handlowym). Punkty nawigacyjne określają lokalizacje przy drodze, w których powinna kończyć się nawigacja. Jest to przydatne, gdy chcesz skierować użytkowników na właściwą stronę drogi lub do konkretnego miejsca odbioru.
Punkty nawigacyjne zwracają navigationPointToken. Możesz przekazać ten token do pakietu Navigation SDK (dostępnego na Android i iOS) lub do interfejsu Routes API, aby kierować kierowców do tej konkretnej lokalizacji. Więcej informacji znajdziesz w artykule Tokeny punktów nawigacyjnych.
Poniższy przykład pokazuje zapytanie Wyszukaj tekst (New) dotyczące „San Francisco International Airport”, które zawiera entrances i navigationPoints w masce pola:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.entrances,places.navigationPoints" \
-d '{
"textQuery": "San Francisco International Airport",
"pageSize": 1
}' \
"https://places.googleapis.com/v1/places:searchText"
Odpowiedź zawiera wejścia i punkty nawigacyjne dla danego miejsca:
{ "places": [ { "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ", "displayName": { "text": "San Francisco International Airport", "languageCode": "en" }, "entrances": [ { "location": { "latitude": 37.6172154, "longitude": -122.3839724 } }, { "location": { "latitude": 37.6174073, "longitude": -122.384196 } }, ... ], "navigationPoints": [ { "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...", "displayName": { "text": "International Terminal Departures Level", "languageCode": "en" }, "location": { "latitude": 37.6153121, "longitude": -122.3900833 }, "travelModes": ["WALK"] }, { "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...", "displayName": { "text": "Domestic Garage - SFO Short Term Parking", "languageCode": "en" }, "location": { "latitude": 37.6157153, "longitude": -122.3885012 }, "travelModes": ["DRIVE", "WALK"], "usages": ["PARKING"] }, ... ] } ] }
Wypróbuj
Narzędzie APIs Explorer umożliwia wysyłanie przykładowych żądań, dzięki czemu możesz zapoznać się z interfejsem API i jego opcjami.
Po prawej stronie strony kliknij ikonę interfejsu API api.
Opcjonalnie możesz edytować parametry żądania.
Kliknij przycisk Wykonaj. W oknie wybierz konto, którego chcesz użyć do wysłania prośby.
W panelu APIs Explorer kliknij ikonę pełnego ekranu pełny ekran, aby rozwinąć okno narzędzia.