Żądanie Wyszukiwanie w pobliżu (nowe) przyjmuje co najmniej jeden typ miejsca i zwraca listę pasujących miejsc na określonym obszarze. Wymagana jest maska pola określająca co najmniej 1 typ danych. Wyszukiwanie w pobliżu (nowe) obsługuje tylko żądania POST.
Eksplorator interfejsów API umożliwia wysyłanie żądań na żywo, dzięki czemu możesz zapoznać się z interfejsem API i jego opcjami:
WypróbujWypróbuj interaktywną prezentację, aby zobaczyć wyniki szukania w pobliżu (Nowe) na mapie.
Prośby o wyszukiwanie w pobliżu (nowe)
Żądanie wyszukiwania w pobliżu (nowe) to żądanie HTTP POST kierowane na adres URL w formacie:
https://places.googleapis.com/v1/places:searchNearby
Przekazuj wszystkie parametry w treści żądania JSON lub w nagłówkach w ramach żądania POST. Na przykład:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "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" \ https://places.googleapis.com/v1/places:searchNearby
Wyszukiwanie w pobliżu (nowe) odpowiedzi
Wyszukiwanie w pobliżu (nowe) zwraca w odpowiedzi obiekt JSON. W odpowiedzi:
- Tablica
places
zawiera wszystkie pasujące miejsca. - Każde miejsce w tablicy jest reprezentowane przez obiekt
Place
. ObiektPlace
zawiera szczegółowe informacje o jednym miejscu. - Wartość FieldMask przekazana w żądaniu określa listę pól zwracanych w obiekcie
Place
.
Pełny obiekt JSON ma postać:
{ "places": [ { object (Place) } ] }
Wymagane parametry
-
FieldMask
Określ listę pól, które mają być zwracane w odpowiedzi, tworząc maskę pola odpowiedzi. Przekaż do metody maskę pola odpowiedzi, używając parametru adresu URL
$fields
lubfields
albo nagłówka HTTPX-Goog-FieldMask
. W odpowiedzi nie ma domyślnej listy zwróconych pól. Jeśli pominiesz maskę pola, metoda zwróci błąd.Maskowanie pól to dobra praktyka projektowa, która pozwala uniknąć żądania zbędnych danych, co pozwala uniknąć niepotrzebnego czasu przetwarzania i opłat.
Określ rozdzieloną przecinkami listę typów danych miejsc do zwrócenia. Na przykład, aby pobrać wyświetlaną nazwę i adres miejsca.
X-Goog-FieldMask: places.displayName,places.formattedAddress
Aby pobrać wszystkie pola, użyj polecenia
*
.X-Goog-FieldMask: *
Określ co najmniej jedno z tych pól:
Następujące pola aktywują kod SKU wyszukiwania w pobliżu (podstawowe):
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,places.businessStatus
,places.displayName
,places.formattedAddress
,places.googleMapsUri
,places.iconBackgroundColor
,places.iconMaskBaseUri
,places.id
,places.location
,places.name
*,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
,places.subDestinations
, w tym polu: /}, w tym polu:places.subDestinations
,places.name
places.types
places.utcOffsetMinutes
places.viewport
places/PLACE_ID
Użyj opcjiplaces.displayName
, by uzyskać dostęp do tekstowej nazwy miejsca.Następujące pola aktywują kod SKU wyszukiwania w pobliżu (zaawansowane):
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,places.rating
,places.regularOpeningHours
,places.regularSecondaryOpeningHours
,places.userRatingCount
,places.websiteUri
Następujące pola wywołują kod SKU wyszukiwania w pobliżu (preferowane):
places.allowsDogs
,places.curbsidePickup
,places.delivery
,places.dineIn
,places.editorialSummary
,places.evChargeOptions
,places.fuelOptions
,places.goodForChildren
,places.goodForGroups
,places.goodForWatchingSports
,places.liveMusic
,places.menuForChildren
,places.parkingOptions
,places.paymentOptions
,places.outdoorSeating
,places.reservable
,places.restroom
,places.reviews
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.servesBeer
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDesserts
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
locationRestriction
Region do wyszukiwania określony jako okrąg, 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. Musisz ustawić w żądaniu wartość większą niż 0,0.
Na przykład:
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Parametry opcjonalne
-
includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes
Umożliwia określenie listy typów z typów Tabela A służących do filtrowania wyników wyszukiwania. W każdej kategorii ograniczeń typu można określić do 50 typów.
Miejsce może mieć tylko jeden typ podstawowy z powiązanych z nim typów tabeli A. Typem podstawowym może być na przykład
"mexican_restaurant"
lub"steak_house"
. Użyj właściwościincludedPrimaryTypes
iexcludedPrimaryTypes
, aby filtrować wyniki według podstawowego typu miejsca.Miejsce może też mieć wartości wielu typów z powiązanych z nim typów tabeli A. Na przykład restauracja może mieć te typy:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. Użyj właściwościincludedTypes
iexcludedTypes
, aby filtrować wyniki na liście typów powiązanych z miejscem.Jeśli wyszukiwanie jest określone z wieloma ograniczeniami typów, zwracane są tylko miejsca, które spełniają wszystkie te ograniczenia. Jeśli na przykład określisz
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, zwrócone miejsca świadczą usługi powiązane z"restaurant"
, ale nie działają głównie jako"steak_house"
.includedTypes
Rozdzielona przecinkami lista typów miejsc z tabeli A do wyszukania. W przypadku pominięcia tego parametru zwracane są miejsca wszystkich typów.
excludedTypes
Rozdzielona przecinkami lista typów miejsc z tabeli A, które mają zostać wykluczone z wyszukiwania.
Jeśli w żądaniu podasz zarówno właściwość
includedTypes
( np."school"
), jak iexcludedTypes
(np."primary_school"
), odpowiedź będzie zawierała miejsca zaklasyfikowane jako"school"
, ale nie jako"primary_school"
. Odpowiedź zawiera miejsca pasujące do co najmniej 1 z parametrówincludedTypes
i żadnego z podanych parametrówexcludedTypes
.Jeśli wystąpią jakiekolwiek sprzeczne typy, np. typy występujące zarówno w
includedTypes
, jak i wexcludedTypes
, zostanie zwrócony błądINVALID_REQUEST
.includedPrimaryTypes
Rozdzielona przecinkami lista typów miejsc głównych z tabeli A, które mają zostać uwzględnione w wyszukiwaniu.
excludedPrimaryTypes
Rozdzielona przecinkami lista głównych typów miejsc z tabeli A, które mają zostać wykluczone z wyszukiwania.
Jeśli wystąpią jakiekolwiek sprzeczne typy podstawowe, takie jak typ występujący zarówno w atrybutach
includedPrimaryTypes
, jak iexcludedPrimaryTypes
, zwracany jest błądINVALID_ARGUMENT
. -
languageCode
Język, w którym mają być zwracane wyniki.
- Zobacz listę obsługiwanych języków. Google często aktualizuje obsługiwane języki, więc ta lista może nie być pełna.
- Jeśli nie zostanie podany
languageCode
, interfejs API przyjmuje domyślnie wartośćen
. Jeśli podasz nieprawidłowy kod języka, interfejs API zwróci błądINVALID_ARGUMENT
. - Interfejs API staramy się, aby adres był czytelny zarówno dla użytkownika, jak i dla lokalnych lokalizacji. W tym celu funkcja zwraca adresy w języku lokalnym, transliterację do skryptu zrozumiałego dla użytkownika w razie potrzeby z uwzględnieniem preferowanego języka. Wszystkie inne adresy są zwracane w preferowanym języku. Komponenty adresu są zwracane w tym samym języku, który jest wybierany z pierwszego komponentu.
- Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API używa 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ść ich zwracania. Geokoder interpretuje skróty w różny sposób w zależności od języka, np. angażowanie rodzaju ulic lub synonimów, które mogą być prawidłowe w jednym języku, ale nie w innym.
-
maxResultCount
Określa maksymalną liczbę zwracanych wyników wyszukiwania miejsc. Wartość musi mieścić się w przedziale od 1 do 20 (domyślnie) włącznie.
-
rankPreference
Typ rankingu, który ma zostać użyty. Jeśli pominiesz ten parametr, wyniki będą uporządkowane według popularności. Może mieć jedną z tych wartości:
POPULARITY
(domyślnie) – sortuje wyniki na podstawie ich popularności.DISTANCE
sortuje wyniki w kolejności rosnącej według odległości od określonej lokalizacji.
-
regionCode
Kod regionu używany do formatowania odpowiedzi, określony jako dwuznakowy kod CLDR. Brak wartości domyślnej.
Jeśli nazwa kraju w polu
formattedAddress
w odpowiedzi jest zgodna z wartościąregionCode
, kod kraju jest pomijany w poluformattedAddress
. Ten parametr nie ma wpływu na elementadrFormatAddress
, który zawsze zawiera nazwę kraju, lub nashortFormattedAddress
, który nigdy go nie uwzględnia.Większość kodów CLDR jest identyczna z kodami ISO 3166-1 z kilkoma wyjątkami. Na przykład domena ccTLD w Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie oznaczający jednostkę „Wielka Brytania i Irlandia Północna”). Parametr może wpływać na wyniki w zależności od obowiązującego prawa.
Przykłady wyszukiwania w pobliżu (nowe)
Znajdź miejsca jednego typu
Poniższy przykład przedstawia żądanie Wyszukiwanie w pobliżu (nowe) dotyczące wyświetlanych nazw wszystkich restauracji w promieniu 500 metrów zdefiniowanych przez funkcję circle
:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "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" \ https://places.googleapis.com/v1/places:searchNearby
Pamiętaj, że nagłówek X-Goog-FieldMask
określa, że odpowiedź zawiera te pola danych: places.displayName
.
Odpowiedź ma wtedy postać:
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
Aby zwrócić dodatkowe informacje, do maski pola dodaj więcej typów danych.
Na przykład dodaj places.formattedAddress,places.types,places.websiteUri
, aby umieścić w odpowiedzi adres, typ i adres internetowy restauracji:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "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,places.types,places.websiteUri" \ https://places.googleapis.com/v1/places:searchNearby
Odpowiedź ma teraz postać:
{ "places": [ { "types": [ "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA", "websiteUri": "http://lamarsf.com/", "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "types": [ "greek_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA", "websiteUri": "https://kokkari.com/", "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, ... }
Znajdowanie miejsc różnych typów
Poniższy przykład przedstawia żądanie Wyszukiwanie w pobliżu (nowe) dotyczące wyświetlanych nazw wszystkich sklepów osiedlowych i alkoholi w promieniu 1000 metrów od określonego zakresu circle
:
curl -X POST -d '{ "includedTypes": ["liquor_store", "convenience_store"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \ https://places.googleapis.com/v1/places:searchNearbyW tym przykładzie do maski pola dodano wartości
places.primaryType
i places.types
, dzięki czemu odpowiedź będzie zawierać informacje o typie każdego miejsca, co ułatwi wybranie odpowiedniego miejsca z wyników.
Wykluczanie typu miejsca z wyszukiwania
Ten przykład przedstawia żądanie Wyszukiwania w pobliżu (nowego) dla wszystkich miejsc typu "school"
z wyłączeniem wszystkich miejsc typu "primary_school"
, które porządkują wyniki według odległości:
curl -X POST -d '{ "includedTypes": ["school"], "excludedTypes": ["primary_school"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } }, "rankPreference": "DISTANCE" }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Wyszukaj wszystkie miejsca w pobliżu danego obszaru, uporządkuj według odległości
Poniższy przykład przedstawia nowe wyszukiwanie w pobliżu miejsc w pobliżu punktu w centrum San Francisco. W tym przykładzie użyjesz parametru rankPreference
, aby uszeregować wyniki według odległości:
curl -X POST -d '{ "maxResultCount": 10, "rankPreference": "DISTANCE", "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Wypróbuj
Eksplorator interfejsów API umożliwia wykonywanie przykładowych żądań, aby ułatwić Ci zapoznanie się z interfejsem API i jego opcjami.
- Wybierz ikonę interfejsu API po prawej stronie.
- Opcjonalnie rozwiń opcję Pokaż parametry standardowe i ustaw parametr
fields
na maskę pola. - Opcjonalnie zmodyfikuj treść żądania.
- Kliknij przycisk Wykonaj. W wyskakującym okienku wybierz konto, którego chcesz użyć, aby przesłać prośbę.
W panelu Eksplorator interfejsów API wybierz ikonę rozwijania (), aby rozwinąć okno API Explorer.