Wyszukiwanie w pobliżu (nowość) żądanie przyjmuje co najmniej jeden typ miejsca i zwraca listę pasujących miejsc w w określonym obszarze. Maska pola określająca co najmniej 1 typ danych jest wymagane. Wyszukiwanie w pobliżu (nowość) obsługuje tylko żądania POST.
API Explorer umożliwia wysyłanie żądań na żywo, dzięki czemu możesz zapoznać się z interfejsem API Opcje interfejsu API:
WypróbujWypróbuj interaktywny demo, aby zobaczyć wyniki wyszukiwania w pobliżu (nowość) wyświetlane na mapie.
Żądania wyszukiwania w pobliżu (nowe)
Żądanie Wyszukiwanie w pobliżu (nowe) to żądanie HTTP POST wysyłane do formularz:
https://places.googleapis.com/v1/places:searchNearby
Przekazuj wszystkie parametry w treści żądania JSON lub w nagłówkach jako część żądanie 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
Odpowiedzi Wyszukiwanie w pobliżu (nowe)
Wyszukiwanie w pobliżu (Nowość) zwraca błąd Obiekt JSON jako odpowiedź. W odpowiedzi:
- Tablica
places
zawiera wszystkie pasujące miejsca. - Każde miejsce w tablicy jest reprezentowane przez
Place
obiektu. ObiektPlace
zawiera szczegółowe informacje o jednym miejsce. - FieldMask przekazana w żądaniu określa listę pól
zwracaną w obiekcie
Place
.
Pełny obiekt JSON ma następujący format:
{ "places": [ { object (Place) } ] }
Wymagane parametry
-
FieldMask
Określ listę pól, które mają być zwracane w odpowiedzi, tworząc maską pola odpowiedzi. Przekaż maskę pola odpowiedzi do metody, używając parametru adresu URL
$fields
lubfields
albo za pomocą nagłówka HTTPX-Goog-FieldMask
Odpowiedź nie zawiera domyślnej listy zwróconych pól. Jeśli pominiesz maskę pola, metoda zwróci błąd.Dobrą metodą projektowania jest maskowanie pól, dzięki którym zbędnych danych, co pozwala uniknąć niepotrzebnego czasu przetwarzania opłaty rozliczeniowe.
Podaj oddzieloną przecinkami listę typów danych miejsc do zwrócenia. 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: *
Wypełnij co najmniej jedno z tych pól:
Te pola aktywują kod SKU Wyszukiwanie w pobliżu (podstawowe):
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,places.attributions
,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
,places.types
,places.utcOffsetMinutes
,places.viewport
* Poleplaces.name
zawiera miejsce nazwa zasobu w formie:places/PLACE_ID
. Użyj formatu:places.displayName
aby uzyskać dostęp do tekstowej nazwy miejsca.Te pola aktywują kod SKU Wyszukiwanie w pobliżu (zaawansowane):
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,places.rating
,places.regularOpeningHours
places.regularSecondaryOpeningHours
,places.userRatingCount
,places.websiteUri
Te pola aktywują kod SKU (preferowany) funkcji wyszukiwania w pobliżu:
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.servesBeer
,places.servesBreakfast
,places.servesBrunch
,places.servesCocktails
,places.servesCoffee
,places.servesDessert
,places.servesDinner
,places.servesLunch
,places.servesVegetarianFood
,places.servesWine
,places.takeout
-
locationRestriction
Region do przeszukania 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 ustaw go w żądaniu na 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 listy typów Tabela A używana do filtrowania w wynikach wyszukiwania. W każdej kategorii ograniczeń typu można określić maksymalnie 50 typów.
Miejsce może mieć tylko jeden typ główny Tabela A powiązana z . Na przykład typ podstawowy to
"mexican_restaurant"
lub"steak_house"
. UżywajincludedPrimaryTypes
iexcludedPrimaryTypes
, według których filtrować wyniki główny typ miejsca.Miejsce może też mieć wiele wartości typów z typów Tabela A i powiązane z nią. Na przykład restauracja może mieć następujące typy:
"seafood_restaurant"
,"restaurant"
,"food"
"point_of_interest"
,"establishment"
. Użyj formatu:includedTypes
iexcludedTypes
, aby filtrować wyniki na liście typów powiązanych z danego miejsca.Gdy określisz ogólny typ podstawowy, na przykład
"restaurant"
lub"hotel"
, odpowiedź może zawierać miejsca o bardziej konkretnym typie głównym niż określony przez Ciebie. Na przykład określasz, że ma być uwzględniony główny typ"restaurant"
Odpowiedź może wtedy zawierać miejsca o głównym typie"restaurant"
, ale odpowiedź może też zawierać miejsca o bardziej szczegółowych typ główny, na przykład"chinese_restaurant"
lub"seafood_restaurant"
.Jeśli wyszukiwanie jest określone z ograniczeniami wielu typów, tylko miejsca które są zgodne ze wszystkimi ograniczeniami. Jeśli na przykład wpiszesz
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, zwrócone miejsca świadczą usługi związane z"restaurant"
, ale nie działają głównie jako"steak_house"
.includedTypes
Rozdzielona przecinkami lista typów miejsc z tabeli A do wyszukania. Jeśli pominiesz ten parametr, zwracane będą miejsca wszystkich typów.
excludedTypes
Rozdzielona przecinkami lista typów miejsc z tabeli A, które mają zostać wykluczone z .
Jeśli podasz zarówno
includedTypes
( np."school"
), jak iexcludedTypes
(np."primary_school"
) w żądaniu, wtedy odpowiedź zawiera miejsca zaklasyfikowane jako"school"
, ale nie jako"primary_school"
Odpowiedź zawiera miejsca pasujące do co najmniej jednego z tych atrybutówincludedTypes
i żadne zexcludedTypes
.Jeśli występują kolidujące typy, takie jak typ występujący w obiekcie
includedTypes
iexcludedTypes
, zwracany jest błądINVALID_REQUEST
.includedPrimaryTypes
Rozdzielona przecinkami lista głównych typów miejsc z tabeli A do uwzględnienia do wyszukiwania.
excludedPrimaryTypes
Rozdzielona przecinkami lista głównych typów miejsc z tabeli A do wykluczenia z wyników wyszukiwania.
Jeśli występują sprzeczne typy główne, takie jak typ występujący w obu
includedPrimaryTypes
iexcludedPrimaryTypes
, Zwracany jestINVALID_ARGUMENT
błąd. -
languageCode
Język, w którym mają być zwracane wyniki.
- Zobacz listę obsługiwanych języków. Często Google aktualizuje obsługiwane języki, więc ta lista może nie być wyczerpująca.
- Jeśli nie podano
languageCode
, domyślną wartością interfejsu API jesten
. Jeśli jeśli określisz nieprawidłowy kod języka, API zwróciINVALID_ARGUMENT
. - Staramy się, aby adres interfejsu API był czytelny zarówno dla użytkownika, jak i lokalnych. Aby osiągnąć ten cel, funkcja zwraca adresy w języku lokalnym, transliterację na skrypt możliwy do odczytania przez użytkownika w razie potrzeby, przy jednoczesnym zachowaniu język. Pozostałe adresy są zwracane w preferowanym języku. Komponenty adresu są wszystkie zwrócone 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 zestaw wyników wybieranych przez interfejs API. oraz kolejność ich zwracania. Geokoder interpretuje skróty w zależności od języka, np. skróty typów ulic lub synonimy które mogą obowiązywać w jednym języku, ale nie w innym.
-
maxResultCount
Określa maksymalną liczbę wyników miejsc do zwrócenia. Wymagana wartość z zakresu 1 i 20 (domyślnie) włącznie.
-
rankPreference
Typ rankingu, który ma zostać użyty. Jeśli ten parametr zostanie pominięty, wyniki będą uporządkowane według popularności. Możliwe 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śloną lokalizację.
-
regionCode
Kod regionu używany do formatowania odpowiedzi podany jako dwuznakową wartość kodu CLDR. Nie ma wartości domyślnej.
Jeśli nazwa kraju w polu
formattedAddress
w odpowiedzi jest zgodna z nazwą krajuregionCode
, kod kraju został pominięty w poluformattedAddress
. Ten parametr nie ma wpływu na tabelęadrFormatAddress
, która zawsze obejmuje kraj lub w domenieshortFormattedAddress
, która nigdy jej nie zawiera.Większość kodów CLDR jest identycznych z kody ISO 3166-1, z kilkoma istotnymi wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (co.uk), natomiast kod ISO 3166-1 to „gb”. (technicznie dla funkcji podmiotu „Wielkiej Brytanii i Irlandii Północnej”). Ten parametr może wpływać na wyniki w zależności od obowiązującego prawa.
Przykłady wyszukiwania w pobliżu (nowe)
Znajdowanie miejsc jednego typu
Poniższy przykład pokazuje żądanie wyszukiwania w pobliżu (nowe) dla wyświetlacza.
nazwy wszystkich restauracji w promieniu 500 metrów, zdefiniowane przez 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 następujące pola danych: places.displayName
.
Odpowiedź.
ma postać:
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
Aby zwracać dodatkowe informacje, dodaj do maski pola więcej typów danych.
Na przykład dodaj places.formattedAddress,places.types,places.websiteUri
, aby uwzględnić
adres restauracji, typ i adres internetowy w odpowiedzi:
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 format:
{ "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 to żądanie wyszukiwania w pobliżu (Nowe) dla
Wyświetlane nazwy wszystkich sklepów wielobranżowych i AGD w promieniu 1000 metrów od
określono 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 każdym miejscu, co ułatwi wybranie
odpowiednie miejsce na stronie wyników.
Wykluczanie typu miejsca z wyszukiwania
Poniższy przykład pokazuje zapytanie Wyszukiwanie w pobliżu (nowe) dla wszystkich miejsc
typu "school"
, z wyłączeniem wszystkich miejsc typu "primary_school"
, ranking wyników
wg 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
Wyszukiwanie wszystkich miejsc w pobliżu obszaru, ranking według odległości
Poniższy przykład zawiera zapytanie „Wyszukiwanie w pobliżu (nowe)” dla miejsc
w pobliżu punktu w centrum San Francisco. W tym przykładzie uwzględniasz tag rankPreference
.
do sortowania wyników 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
API Explorer umożliwia wysyłanie przykładowych żądań, aby zapoznać się z interfejsem API i jego opcjami.
- Kliknij ikonę interfejsu API
. w prawej części strony.
- Opcjonalnie rozwiń opcję Pokaż parametry standardowe i ustaw
parametr
fields
do maski pola. - Opcjonalnie edytuj Treść żądania.
- Kliknij przycisk Wykonaj. W wyskakującym okienku wybierz konto, z którego chcesz przesłać prośbę.
W panelu Eksplorator API kliknij ikonę rozwijania.
, aby rozwinąć okno Eksploratora interfejsów API.