Quando você tiver um ID de lugar, poderá solicitar mais detalhes sobre um determinado estabelecimento ou ponto de interesse iniciando uma solicitação de Place Details (New). Uma solicitação de Place Details (New) retorna informações mais abrangentes sobre o local indicado, como o endereço completo, o número de telefone, a classificação e as avaliações dos usuários.
Há muitas maneiras de conseguir um ID de local. Você pode usar:
- Text Search (novo) ou Nearby Search (novo)
- API Geocoding
- API Routes
- API Address Validation
- Place Autocomplete
O API Explorer permite fazer solicitações em tempo real para que você se familiarize com a API e as opções dela:
Faça um testeSolicitações de Place Details (novo)
Uma solicitação de Place Details é uma solicitação HTTP GET no formulário:
https://places.googleapis.com/v1/places/PLACE_ID
Transmita todos os parâmetros como parâmetros de URL ou em cabeçalhos como parte da solicitação GET. Exemplo:
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?fields=id,displayName&key=API_KEY
Ou em um comando cURL:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
Respostas do Place Details (novo)
O método "Place Details (New)" retorna um objeto JSON como resposta. Na resposta:
- A resposta é representada por um objeto
Place
. O objetoPlace
contém informações detalhadas sobre o lugar. - O FieldMask transmitido na solicitação especifica a lista de campos
retornados no objeto
Place
.
O objeto JSON completo está no formato:
{ "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g", "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g", "displayName": { "text": "Trinidad" } ... }
Parâmetros obrigatórios
-
FieldMask
Especifique a lista de campos a serem retornados na resposta criando uma máscara de campo de resposta. Transmita a máscara de 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 vai 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: displayName,formattedAddress
Use
*
para recuperar todos os campos.X-Goog-FieldMask: *
Especifique um ou mais dos seguintes campos:
Os campos a seguir acionam a SKU Place Details (somente IDs):
attributions
,id
,name
*,photos
* O camponame
contém o nome do recurso do lugar no formulário:places/PLACE_ID
. UsedisplayName
para acessar o nome do lugar.Os campos a seguir acionam a SKU Place Details (Only Location):
addressComponents
,adrFormatAddress
,formattedAddress
,location
,plusCode
,shortFormattedAddress
,types
,viewport
Os campos a seguir acionam a SKU Place Details (Basic):
accessibilityOptions
,businessStatus
,containingPlaces
,displayName
,googleMapsLinks
*,googleMapsUri
,iconBackgroundColor
,iconMaskBaseUri
,primaryType
,primaryTypeDisplayName
,pureServiceAreaBusiness
,subDestinations
,utcOffsetMinutes
* O campogoogleMapsLinks
está na fase de pré-lançamento do GA4 e não há cobrança, ou seja, o faturamento é de US $0,00, para uso durante a fase de pré-lançamento.Os campos a seguir acionam a SKU Place Details (Advanced):
currentOpeningHours
,currentSecondaryOpeningHours
,internationalPhoneNumber
,nationalPhoneNumber
,priceLevel
,priceRange
,rating
,regularOpeningHours
,regularSecondaryOpeningHours
,userRatingCount
,websiteUri
Os campos a seguir acionam a SKU do Place Details (Preferencial):
allowsDogs
,curbsidePickup
,delivery
,dineIn
,editorialSummary
,evChargeOptions
,fuelOptions
,goodForChildren
,goodForGroups
,goodForWatchingSports
,liveMusic
,menuForChildren
,parkingOptions
,paymentOptions
,outdoorSeating
,reservable
,restroom
,reviews
,routingSummaries
,*servesBeer
,servesBreakfast
,servesBrunch
,servesCocktails
,servesCoffee
,servesDessert
,servesDinner
,servesLunch
,servesVegetarianFood
,servesWine
,takeout
* Somente Pesquisa de texto e Pesquisa por proximidades
-
placeId
Um identificador textual que identifica um local de forma exclusiva, retornado de um Text Search (novo) ou Nearby Search (novo). Para mais informações sobre IDs de local, consulte a visão geral de IDs de local.
A string
places/PLACE_ID
também é chamada de nome do recurso do lugar. Na resposta de uma solicitação do Place Details (novo), do Nearby Search (novo) e do Text Search (novo), essa string está contida no camponame
da resposta. O ID de lugar autônomo fica no campoid
da resposta.
Parâmetros opcionais
languageCode
O idioma em que os resultados serão retornados.
- Consulte a lista de idiomas aceitos. O Google atualiza com frequência os idiomas compatíveis, portanto, esta lista pode não estar completa.
-
Se
languageCode
não for fornecido, a API vai usaren
como padrão. 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 residencial legível tanto para o usuário quanto para os locais. Para atingir este objetivo, ele retorna os endereços residenciais no idioma local, transliterado para um script legível pelo usuário, se necessário, observando o idioma preferencial. 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 vai 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 codificador geográfico interpreta abreviações de formas variadas 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 outros.
regionCode
O código de 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 aoregionCode
, 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 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 da Irlanda do Norte"). O parâmetro pode afetar os resultados com base na legislação aplicável.
-
sessionToken
Os tokens de sessão são strings geradas pelo usuário que rastreiam chamadas de preenchimento automático (Novas) como "sessões". O Autocomplete (novo) usa tokens de sessão para agrupar as fases de consulta e seleção de local de uma pesquisa com preenchimento automático do usuário em uma sessão discreta para fins de faturamento. Os tokens de sessão são transmitidos para as chamadas do Place Details (novo) que seguem as chamadas do Autocomplete (novo). Para mais informações, consulte Tokens de sessão.
Exemplo de Place Details
O exemplo a seguir solicita os detalhes de um lugar por
placeId
:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
O cabeçalho X-Goog-FieldMask
especifica que a
resposta
contém os seguintes campos de dados: id,displayName
.
A resposta estará no formato:
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "displayName": { "text": "Googleplex", "languageCode": "en" } }
Adicione mais tipos de dados à máscara de campo para retornar mais informações.
Por exemplo, adicione formattedAddress,plusCode
para incluir o endereço e o Plus Code na resposta:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,formattedAddress,plusCode" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
A resposta agora está no formato:
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "plusCode": { "globalCode": "849VCWC7+RW", "compoundCode": "CWC7+RW Mountain View, CA, USA" }, "displayName": { "text": "Googleplex", "languageCode": "en" } }
Confira!
Com o APIs Explorer, é possível fazer solicitações de amostra para se familiarizar com a API e as opções relacionadas.
Para fazer uma solicitação:
- Selecione o ícone da API, , no lado direito da página.
- Opcionalmente, defina o parâmetro
name
como:places/PLACE_ID
- Opcionalmente, abra Mostrar parâmetros padrão e defina
o parâmetro
fields
na máscara de campo. - Selecione o botão Executar. 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 abrir a janela do API Explorer.