Uma solicitação de Nearby Search (novo) usa um ou mais tipos de lugar e retorna uma lista de lugares correspondentes dentro da área especificada. Uma máscara de campo que especifica um ou mais tipos de dados é obrigatória. O Nearby Search (novo) só é compatível com solicitações POST.
Com o API Explorer, é possível fazer solicitações ativas para se familiarizar com a API e as opções de API:
Faça um testeUse a demonstração interativa 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 HTTP POST para um URL no formato:
https://places.googleapis.com/v1/places:searchNearby
Transmita todos os parâmetros no corpo da solicitação JSON ou nos cabeçalhos como parte da solicitação 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 um objeto
Place
. 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
Crie uma máscara de campo de resposta para especificar a lista de campos a serem retornados na resposta. Transmita a máscara do campo de resposta para o método usando o parâmetro de URL
$fields
oufields
ou 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. Isso ajuda a evitar cobranças desnecessárias no tempo de processamento e nas cobranças.
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.primaryTypeDisplayName
,places.adrFormatAddress
, {2/2}, {2/4}, {2, {2/4}, {2places.name
places.shortFormattedAddress
places.subDestinations
places.types
places.utcOffsetMinutes
places.viewport
places/PLACE_ID
Useplaces.displayName
para acessar o texto do 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.parkingOptions
,places.parkingOptions
,places.parkingOptions
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. Defina-o na solicitação como 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 dos tipos da Tabela A usados para filtrar os 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 da Tabela A associados a ele. Por exemplo, o tipo principal pode ser
"mexican_restaurant"
ou"steak_house"
. UseincludedPrimaryTypes
eexcludedPrimaryTypes
para filtrar os resultados com base no tipo principal de um lugar.Um lugar também pode ter vários valores de tipo dos tipos da Tabela A associados a ele. Por exemplo, um restaurante pode ter os seguintes tipos:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. UseincludedTypes
eexcludedTypes
para filtrar os resultados na lista de tipos associados a um lugar.Se uma pesquisa for especificada com várias restrições de tipo, apenas lugares que atenderem a todas elas serão retornados. Por exemplo, se você especificar
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, os lugares retornados fornecerão serviços relacionados ao"restaurant"
, mas não funcionarão 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 lugares da Tabela A a serem excluídos de uma pesquisa.
Se você especificar
includedTypes
( como"school"
) eexcludedTypes
(como"primary_school"
) na solicitação, a resposta incluirá locais categorizados como"school"
, mas não como"primary_school"
. A resposta inclui locais que correspondem a pelo menos um dosincludedTypes
e nenhuma doexcludedTypes
.Se houver algum tipo conflitante, como um tipo que aparece em
includedTypes
eexcludedTypes
, um erroINVALID_REQUEST
será retornado.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 em
includedPrimaryTypes
eexcludedPrimaryTypes
, um erroINVALID_ARGUMENT
será retornado. -
languageCode
O idioma no qual os resultados serão retornados.
- Veja a lista de idiomas compatíveis. O Google atualiza os idiomas compatíveis com frequência, portanto, essa 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 retornará um erroINVALID_ARGUMENT
. - A API faz o possível para fornecer um endereço que seja legível para o usuário e os moradores. 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 idioma preferido. Todos os outros endereços são retornados no idioma preferencial. Todos os componentes de endereço são retornados no mesmo idioma, escolhido no 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 retornar e na ordem em que são retornados. O geocodificador interpreta abreviações de maneiras diferentes 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 local especificado.
-
regionCode
O código da região usado para formatar a resposta, especificado como um valor de código CLDR de dois caracteres. Não há valor padrão.
Se o nome do país do campo
formattedAddress
na resposta corresponder aregionCode
, o código do país será omitido deformattedAddress
. Esse parâmetro não tem efeito emadrFormatAddress
, que sempre inclui o nome do país, ou emshortFormattedAddress
, que nunca o inclui.A maioria dos códigos CLDR é idêntica aos 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 a entidade "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 do Nearby Search (novo) para os nomes de exibição de todos os restaurantes em um raio de 500 metros, definido 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
Observe que o cabeçalho X-Goog-FieldMask
especifica que a resposta
contém os seguintes campos de dados: places.displayName
.
A resposta
estará, então, 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, o tipo e o endereço da Web do restaurante 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 exibição de todas as lojas de conveniência e lojas de bebidas 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 nos 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 próximos a um ponto no centro de São Francisco. Neste exemplo, você inclui o parâmetro 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, é possível fazer solicitações de amostra para se familiarizar com a API e as opções relacionadas.
- Selecione o ícone da API, , no lado direito da página.
- Se quiser, expanda Mostrar parâmetros padrão e defina o parâmetro
fields
como a 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 API Explorer, selecione o ícone de expansão para expandir a janela do API Explorer.