Żądanie Wyszukiwanie w pobliżu (nowe) uwzględnia 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 (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 i jego opcjami:
WypróbujZobacz interaktywną demonstrację, aby zobaczyć wyniki wyszukiwania w pobliżu (nowość) wyświetlane na mapie.
Żądania wyszukiwania w pobliżu (nowe)
Żądanie wyszukiwania w pobliżu (nowe) to żądanie HTTP POST wysyłane na adres URL w postaci:
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
Odpowiedzi Wyszukiwanie w pobliżu (nowe)
Wyszukiwanie w pobliżu (nowość) 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. - FieldMask przekazana w żądaniu określa listę pól zwróconych 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 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.Maskowanie pól to sprawdzona metoda projektowania, która pozwala uniknąć żądania zbędnych danych. Pozwala to uniknąć niepotrzebnego czasu przetwarzania i opłat.
Podaj oddzieloną przecinkami listę typów danych miejsc do zwrócenia. Na przykład w celu pobrania wyświetlanej nazwy i adresu 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
, {/4/4},places.iconMaskBaseUri
,places.id
,places.location
,places.name
*,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
, ,places.shortFormattedAddress
, .places.subDestinations
places.iconBackgroundColor
places.name
places.types
places.utcOffsetMinutes
places.viewport
places/PLACE_ID
Użyjplaces.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.servesBreakfast
,places.servesBreakfast
,places.servesBreakfast
places.servesBeer
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. W żądaniu musisz ustawić 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 używanych do filtrowania wyników wyszukiwania. W każdej kategorii ograniczeń typu można określić maksymalnie 50 typów.
Miejsce może mieć tylko jeden typ podstawowy z powiązanych z nim typów Tabela A. Typem głównym może być np.
"mexican_restaurant"
lub"steak_house"
. Aby filtrować wyniki według głównego typu miejsca, użyj właściwościincludedPrimaryTypes
iexcludedPrimaryTypes
.Miejsce może też mieć wiele wartości 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 przefiltrować wyniki na liście typów powiązanych z miejscem.Jeśli wyszukiwanie jest określone z ograniczeniami wielu typów, zwracane są tylko miejsca, które spełniają wszystkie warunki. Jeśli na przykład podasz
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, zwracane 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. 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 wyszukiwania.
Jeśli w żądaniu określisz zarówno atrybut
includedTypes
( np."school"
), jak iexcludedTypes
(np."primary_school"
), odpowiedź będzie zawierać miejsca zaklasyfikowane jako"school"
, ale nie jako"primary_school"
. Odpowiedź zawiera miejsca, które pasują do co najmniej 1 z wartościincludedTypes
i żadnego z wartościexcludedTypes
.Jeśli występują kolidujące typy, takie jak typ występujący zarówno w polu
includedTypes
, jak i wexcludedTypes
, zostanie zwrócony błądINVALID_REQUEST
.includedPrimaryTypes
Rozdzielona przecinkami lista głównych typów miejsc 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ępują sprzeczne typy główne, takie jak typ występujący zarówno w
includedPrimaryTypes
, jak i wexcludedPrimaryTypes
, 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ć wyczerpująca.
- Jeśli nie podano
languageCode
, domyślną wartością interfejsu API jesten
. Jeśli podasz nieprawidłowy kod języka, interfejs API zwróci błądINVALID_ARGUMENT
. - Interfejs API stara się dostarczyć adres, który będzie czytelny zarówno dla użytkownika, jak i lokalnego użytkownika. Aby osiągnąć ten cel, funkcja zwraca adresy w języku lokalnym, transliterację na skrypt, który w razie potrzeby może odczytać użytkownik, z zachowaniem preferowanego języka. Pozostałe 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 zestaw wyników zwracanych przez interfejs API oraz na kolejność, w jakiej są one zwracane. Geokoder różnie interpretuje skróty w zależności od języka. Dotyczy to na przykład skrótów typów ulic lub synonimów, które mogą być prawidłowe w jednym języku, a w innym nie.
-
maxResultCount
Określa maksymalną liczbę wyników miejsc do zwrócenia. 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 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ślonej lokalizacji.
-
regionCode
Kod regionu używany do formatowania odpowiedzi podany jako wartość dwuznakowego kodu CLDR. Nie ma wartości domyślnej.
Jeśli nazwa kraju w polu
formattedAddress
w odpowiedzi jest zgodna z nazwąregionCode
, kod kraju jest pomijany w poluformattedAddress
. Ten parametr nie ma wpływu na metodęadrFormatAddress
, która zawsze zawiera nazwę kraju, ani na obiektshortFormattedAddress
, który go nigdy nie zawiera.Większość kodów CLDR jest identyczna z kodami ISO 3166-1 z kilkoma wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Wielka Brytania i Irlandia Północna”). 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) o wyświetlane nazwy wszystkich restauracji w promieniu 500 metrów (zgodnie z definicją za pomocą funkcji 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
wskazuje, że odpowiedź zawiera te pola danych: places.displayName
.
Odpowiedź ma wówczas 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 atrybut places.formattedAddress,places.types,places.websiteUri
, aby w odpowiedzi uwzględnić adres restauracji, jej typ i adres internetowy:
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
Ten przykład pokazuje żądanie wyszukiwania w pobliżu (nowe) o wyświetlane nazwy wszystkich sklepów osiedlowych i sklepów monopolowych w promieniu 1000 metrów od określonej wartości 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 dodano właściwości
places.primaryType
i places.types
do maski pola, dzięki czemu odpowiedź zawiera informacje o każdym miejscu, co ułatwia wybranie odpowiedniego miejsca w wynikach.
Wykluczanie typu miejsca z wyszukiwania
Poniższy przykład pokazuje żądanie wyszukiwania w pobliżu (nowe) dla wszystkich miejsc typu "school"
z wyłączeniem wszystkich miejsc typu "primary_school"
. W ten sposób wyniki wyszukiwania są uporządkowane 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
Wyszukiwanie wszystkich miejsc w pobliżu obszaru, ranking według odległości
Poniższy przykład pokazuje żądanie wyszukiwania w pobliżu (nowe) dla miejsc w pobliżu punktu w centrum San Francisco. W tym przykładzie uwzględniamy parametr rankPreference
, aby uporządkować 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
API Explorer umożliwia wykonywanie przykładowych żądań, aby zapoznać się z interfejsem API i jego opcjami.
- Wybierz ikonę interfejsu API () po prawej stronie.
- Opcjonalnie rozwiń sekcję Pokaż parametry standardowe i ustaw parametr
fields
na maskę pola. - Opcjonalnie edytuj Treść żądania.
- Kliknij przycisk Wykonaj. W wyskakującym okienku wybierz konto, z którego chcesz przesłać prośbę.
W panelu API Explorer kliknij ikonę rozwijania , aby rozwinąć okno API Explorer.