Uma Nearby Search (novo) request toma um ou mais tipos de locais e retorna uma lista de locais correspondentes dentro da na área especificada. Máscara de campo que especifica um ou mais tipos de dados. é obrigatório. O Nearby Search (novo) só é compatível com solicitações POST.
O APIs Explorer permite que você faça solicitações ativas para se familiarizar com a API e a Opções de API:
Faça um testeExperimente a ferramenta demo para ver os resultados do Nearby Search (novo) exibidos em um mapa.
Solicitações do Nearby Search (novo)
Uma solicitação de Nearby Search (novo) é uma solicitação POST HTTP para um URL na formulário:
https://places.googleapis.com/v1/places:searchNearby
Transmita todos os parâmetros no corpo da solicitação JSON ou nos cabeçalhos como parte do POST. Exemplo:
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
Respostas do Nearby Search (novo)
O Nearby Search (novo) retorna um objeto JSON como resposta. Na resposta:
- A matriz
places
contém todos os lugares correspondentes. - Cada local na matriz é representado por uma
Place
objeto. O objetoPlace
contém informações detalhadas sobre um único lugar - O FieldMask transmitido na solicitação especifica a lista de campos.
retornados no objeto
Place
.
O objeto JSON completo está no formato:
{ "places": [ { object (Place) } ] }
Parâmetros obrigatórios
-
FieldMask
Especifique a lista de campos a serem retornados na resposta criando um máscara do campo de resposta. Transmita a máscara do campo de resposta ao método usando o parâmetro de URL
$fields
oufields
ou usando o cabeçalho HTTPX-Goog-FieldMask
Não há uma lista padrão de campos retornados na resposta. Se você omitir a máscara de campo, o método retornará um erro.O mascaramento de campo é uma prática recomendada de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento desnecessário e cobranças de faturamento adicionais.
Especifique uma lista separada por vírgulas de tipos de dados de lugar a serem retornados. Por exemplo: para recuperar o nome de exibição e o endereço do local.
X-Goog-FieldMask: places.displayName,places.formattedAddress
Use
*
para recuperar todos os campos.X-Goog-FieldMask: *
Especifique um ou mais dos seguintes campos:
Os campos a seguir acionam a SKU do Nearby Search (Basic):
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
* O campoplaces.name
contém o nome do recurso do lugar na forma:places/PLACE_ID
. Usar oplaces.displayName
para acessar o texto nome do lugar.Os campos a seguir acionam a SKU do Nearby Search (Advanced):
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,places.rating
,places.regularOpeningHours
,places.regularSecondaryOpeningHours
,places.userRatingCount
,places.websiteUri
Os campos a seguir acionam a SKU do Nearby Search (Preferencial):
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
A região a ser pesquisada especificada como um círculo, definida pelo ponto central e pelo raio em metros. O raio deve estar entre 0,0 e 50.000,0, inclusive. O raio padrão é 0,0. Você deve defina-o na solicitação para um valor maior que 0,0.
Exemplo:
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Parâmetros opcionais
-
allowedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes
Permite especificar uma lista de tipos de tipos Tabela A usada para filtrar nos resultados da pesquisa. Até 50 tipos podem ser especificados em cada categoria de restrição.
Um lugar só pode ter um único tipo principal dos tipos Tabela A associada a reimplantá-lo. Por exemplo, o tipo principal pode ser
"mexican_restaurant"
ou"steak_house"
. UsarincludedPrimaryTypes
eexcludedPrimaryTypes
para filtrar os resultados o tipo principal de um lugar.Um lugar também pode ter vários valores de tipo de tipos. Tabela A associados a ele. Por exemplo, um restaurante pode ter os seguintes tipos:
"seafood_restaurant"
,"restaurant"
e"food"
."point_of_interest"
,"establishment"
. Usar oincludedTypes
eexcludedTypes
para filtrar os resultados na lista de tipos associados a de um lugar.Quando você especifica um tipo principal geral, como
"restaurant"
ou"hotel"
, a resposta pode conter locais com um tipo principal mais específico do que o especificado. Por exemplo, você especifica a inclusão de um tipo primário de"restaurant"
: A resposta pode então conter locais com um tipo primário de"restaurant"
, mas a resposta também pode conter locais com um nome tipo primário, como"chinese_restaurant"
ou"seafood_restaurant"
.Se uma pesquisa for especificada com várias restrições de tipo, apenas lugares que satisfaçam todas as restrições são retornadas. Por exemplo, se você especificar
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, o Os lugares retornados oferecem serviços relacionados a"restaurant"
, mas não funcionam principalmente como um"steak_house"
.includedTypes
Uma lista separada por vírgulas dos tipos de lugares da Tabela A que devem ser pesquisados. Se esse parâmetro for omitido, lugares de todos os tipos serão retornados.
excludedTypes
Uma lista separada por vírgulas de tipos de lugar da Tabela A para excluir de uma pesquisa.
Se você especificar o
includedTypes
( como"school"
) e oexcludedTypes
(como"primary_school"
) na solicitação, depois o a resposta inclui lugares categorizados como"school"
, mas não como"primary_school"
. A resposta inclui locais que correspondem a pelo menos um dos aincludedTypes
e nenhuma daexcludedTypes
.Se houver algum tipo conflitante, como um tipo que aparece em
includedTypes
eexcludedTypes
, será retornado um erroINVALID_REQUEST
.includedPrimaryTypes
Uma lista separada por vírgulas dos principais tipos de lugares da Tabela A para incluir em uma pesquisa.
excludedPrimaryTypes
Uma lista separada por vírgulas dos principais tipos de lugares da Tabela A para excluir de uma pesquisa.
Se houver algum tipo principal conflitante, como um tipo que aparece
includedPrimaryTypes
eexcludedPrimaryTypes
, umaINVALID_ARGUMENT
será retornado. -
languageCode
O idioma no qual os resultados serão retornados.
- Veja a lista de idiomas compatíveis. Google com frequência atualiza os idiomas compatíveis, portanto, esta lista pode não estar completa.
- Se
languageCode
não for fornecido, o padrão da API seráen
. Se você especificar um código de idioma inválido, a API vai retornar umINVALID_ARGUMENT
erro. - A API faz o possível para fornecer um endereço que seja legível tanto para o usuário quanto para dos habitantes locais. Para atingir esse objetivo, ele retorna endereços no idioma local, transliterado para um script legível pelo usuário, se necessário, observando o método idioma de destino. Todos os outros endereços são retornados no idioma preferencial. Os componentes de endereço são todos retornados no mesmo idioma, escolhido pelo primeiro componente.
- Se um nome não estiver disponível no idioma preferencial, a API usará a correspondência mais próxima.
- O idioma preferido tem uma pequena influência no conjunto de resultados que a API escolhe e a ordem em que foram devolvidos. O geocodificador interpreta abreviações de maneira diferente dependendo do idioma, como abreviações de tipos de rua ou sinônimos que podem ser válidos em um idioma, mas não em outro.
-
maxResultCount
Especifica o número máximo de resultados de lugar a serem retornados. Precisa estar entre 1 e 20 (padrão).
-
rankPreference
O tipo de classificação a ser usado. Se esse parâmetro for omitido, os resultados serão classificados por popularidade. Pode ser uma das seguintes opções:
POPULARITY
(padrão) classifica os resultados com base na popularidade.DISTANCE
Classifica os resultados em ordem crescente de distância do em um local específico.
-
regionCode
O código da região usado para formatar a resposta, especificado como um de dois caracteres. Não há valor padrão.
Se o nome do país do campo
formattedAddress
na resposta corresponder aoregionCode
, o código do país é omitido deformattedAddress
. Esse parâmetro não tem efeito sobreadrFormatAddress
, que sempre inclui o país nome, ou emshortFormattedAddress
, que nunca o inclui.A maioria dos códigos CLDR é idêntica códigos ISO 3166-1, com algumas exceções notáveis. Por exemplo, o ccTLD do Reino Unido é "uk" (.co.uk), enquanto o código ISO 3166-1 é "gb" (tecnicamente para os "Reino Unido da Grã-Bretanha e Irlanda do Norte"). O parâmetro pode afetar os resultados com base na legislação aplicável.
Exemplos do Nearby Search (novo)
Encontrar lugares de um tipo
O exemplo a seguir mostra uma solicitação de Nearby Search (novo) para a tela.
nomes de todos os restaurantes em um raio de 500 metros, definidos por 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
O cabeçalho X-Goog-FieldMask
especifica que a resposta
contém os seguintes campos de dados: places.displayName
.
A resposta
estará no formato:
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
Adicione mais tipos de dados à máscara de campo para retornar mais informações.
Por exemplo, adicione places.formattedAddress,places.types,places.websiteUri
para incluir o
endereço do restaurante, tipo e endereço da Web na resposta:
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
A resposta agora está no formato:
{ "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" } }, ... }
Encontrar lugares de vários tipos
O exemplo a seguir mostra uma solicitação de Nearby Search (novo) para os
nomes de todas as lojas de conveniência e de bebidas alcoólicas em um raio de 1.000 metros do
circle
especificado:
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:searchNearbyEste exemplo adiciona
places.primaryType
e places.types
à máscara de campo
para que a resposta inclua informações de tipo sobre cada local, facilitando a seleção do
local apropriado dos resultados.
Excluir um tipo de lugar de uma pesquisa
O exemplo a seguir mostra uma solicitação de Nearby Search (novo) para todos os lugares
do tipo "school"
, excluindo todos os lugares do tipo "primary_school"
, classificando os resultados
por distância:
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
Pesquisar todos os lugares perto de uma área, classificados por distância
O exemplo a seguir mostra uma solicitação de Nearby Search (novo) para locais
perto de um ponto no centro de São Francisco. Neste exemplo, você inclui rankPreference
para classificar os resultados por distância:
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
Confira!
Com o APIs Explorer, você pode fazer solicitações de amostra para se familiarizar com a API e as opções de API.
- Selecione o ícone da API,
, no lado direito da página.
- Como opção, expanda Mostrar parâmetros padrão e defina
O parâmetro
fields
à máscara de campo. - É possível editar o Corpo da solicitação.
- Selecione o botão Execute. No pop-up, escolha a conta que você quer usar para fazer a solicitação.
No painel do APIs Explorer, selecione o ícone de expansão,
para expandir a janela do APIs Explorer.