Introdução
Depois de ter um ID de lugar, você pode solicitar mais detalhes sobre um estabelecimento ou ponto de interesse específico iniciando uma solicitação de Place Details (novo). Uma solicitação de Place Details (New) retorna informações mais abrangentes sobre o lugar indicado, como endereço completo, número de telefone, avaliação de usuários e avaliações.
Há muitas maneiras de conseguir um ID de lugar. Você pode usar:
- Text Search (novo) ou Nearby Search (novo)
- API Geocoding
- API Routes
- API Address Validation
- Preenchimento automático (novo)
Com o APIs Explorer, você pode fazer solicitações em tempo real para se familiarizar com a API e as opções dela:
Solicitações do Place Details (novo)
Uma solicitação de Place Details (New) é uma solicitação HTTP GET no formato:
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_KEYOu 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 Place Details (New) retorna um objeto JSON como resposta. Na resposta:
- A resposta é representada por um objeto
Place. O objetoPlacecontém informações detalhadas sobre o lugar. - A FieldMask transmitida na solicitação especifica a lista de campos
retornados no objeto
Place.
O objeto JSON completo tem o seguinte 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 ao método usando o parâmetro de URL
$fieldsoufields, 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 vai retornar um erro.A máscara de campo é uma boa prática de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento e cobranças desnecessárias.
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 lugar.
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 Essentials IDs Only:
attributions
consumerAlert
id
movedPlace
movedPlaceId
name*
photos
* O campo
namecontém o nome do recurso do lugar no formato:places/PLACE_ID. Para receber o nome de texto do lugar, solicite o campodisplayNamena SKU Pro.Para conferir uma lista completa de campos e as SKUs associadas, consulte Campos de dados de lugar (novo).
Os campos a seguir acionam a SKU Place Details Essentials:
addressComponents
addressDescriptor*
adrFormatAddress
formattedAddress
location
plusCode
postalAddress
shortFormattedAddress
types
viewport
* Os descritores de endereço estão disponíveis para clientes na Índia e são experimentais em outros lugares.
Para conferir uma lista completa de campos e as SKUs associadas, consulte Campos de dados de lugar (novo).
Os seguintes campos acionam a SKU Place Details Pro:
accessibilityOptions
businessStatus
containingPlaces
displayName
googleMapsLinks
googleMapsTypeLabel
googleMapsUri
iconBackgroundColor
iconMaskBaseUri
openingDate
primaryType
primaryTypeDisplayName
pureServiceAreaBusiness
subDestinations
timeZone
utcOffsetMinutes
Para conferir uma lista completa de campos e as SKUs associadas, consulte Campos de dados de lugar (novo).
Os seguintes campos acionam a SKU do Place Details Enterprise:
currentOpeningHours
currentSecondaryOpeningHours
internationalPhoneNumber
nationalPhoneNumber
priceLevel
priceRange
rating
regularOpeningHours
regularSecondaryOpeningHours
transitStation
userRatingCount
websiteUriPara conferir uma lista completa de campos e as SKUs associadas, consulte Campos de dados de lugar (novo).
Os campos a seguir acionam a SKU Place Details Enterprise + Atmosphere:
allowsDogs
curbsidePickup
delivery
dineIn
editorialSummary
evChargeAmenitySummary
evChargeOptions
fuelOptions
generativeSummary
goodForChildren
goodForGroups
goodForWatchingSports
liveMusic
menuForChildren
neighborhoodSummary
parkingOptions
paymentOptions
outdoorSeating
reservable
restroom
reviews
reviewSummary
routingSummaries*
servesBeer
servesBreakfast
servesBrunch
servesCocktails
servesCoffee
servesDessert
servesDinner
servesLunch
servesVegetarianFood
servesWine
takeout
* Pesquisa de texto e pesquisa por proximidade apenasPara conferir uma lista completa de campos e as SKUs associadas, consulte Campos de dados de lugar (novo).
-
placeId
Um identificador textual que identifica um lugar de forma exclusiva, retornado de uma Text Search (New) ou Nearby Search (New). Para mais informações sobre IDs de lugar, consulte a visão geral de IDs de lugar.
A string
places/PLACE_IDtambém é chamada de nome do recurso do lugar. Na resposta de uma solicitação de Place Details (novo), Nearby Search (novo) e Text Search (novo), essa string está contida no camponameda resposta. O ID do lugar independente está contido no campoidda resposta.displayName.
Parâmetros opcionais
languageCode
O idioma em que os resultados serão retornados.
- Consulte a lista de idiomas disponíveis. O Google atualiza os idiomas compatíveis com frequência, então esta lista pode não estar completa.
-
Se
languageCodenão for fornecido, a API usaráencomo padrão. Se você especificar um código de idioma inválido, a API vai retornar um erroINVALID_ARGUMENT. - A API faz o possível para fornecer um endereço legível para o usuário e os moradores locais. Para isso, ele retorna endereços em português, transliterados para um script legível pelo usuário, se necessário, observando o idioma de preferência. Todos os outros endereços são retornados no idioma preferido. Todos os componentes de endereço são retornados no mesmo idioma, que é escolhido no primeiro componente.
- Se um nome não estiver disponível no idioma preferido, 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 eles são retornados. O geocodificador interpreta abreviações de maneira diferente dependendo do idioma, como as abreviações de tipos de rua ou sinônimos que podem ser válidos em um idioma, mas não em outro.
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
formattedAddressna resposta corresponder aoregionCode, o código do país será omitido deformattedAddress. Esse parâmetro não afetaadrFormatAddress, que sempre inclui o nome do país, nemshortFormattedAddress, 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 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 do Autocomplete (New) 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 de preenchimento automático do usuário em uma sessão discreta para fins de faturamento. Os tokens de sessão são transmitidos para chamadas de Place Details (novo) que seguem chamadas de Autocomplete (novo). Para mais informações, consulte Tokens de sessão.
Exemplo de Place Details (novo)
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 fica assim:
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "displayName": { "text": "Googleplex", "languageCode": "en" } }
Adicione mais tipos de dados à máscara de campo para retornar informações adicionais.
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" } }
Receber descritores de endereço
Os descritores de endereço fornecem informações relacionais sobre a localização de um lugar, incluindo pontos de referência próximos e áreas que o contêm.
O exemplo a seguir mostra uma solicitação de Place Details (New) para uma loja de departamentos
em um shopping de San José. Neste exemplo, inclua addressDescriptors
na máscara de campo:
curl -X GET https://places.googleapis.com/v1/places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4 \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: name,displayName,addressDescriptor"
A resposta inclui o lugar especificado na solicitação, uma lista de pontos de referência próximos e a distância deles até o lugar, além de uma lista de áreas e a relação de contenção delas com o lugar:
{ "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4", "displayName": { "text": "Macy's", "languageCode": "en" }, "addressDescriptor": { "landmarks": [ { "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s", "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s", "displayName": { "text": "Westfield Valley Fair", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "food", "movie_theater", "point_of_interest", "restaurant", "shoe_store", "shopping_mall", "store" ], "spatialRelationship": "WITHIN", "straightLineDistanceMeters": 220.29175 }, { "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4", "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4", "displayName": { "text": "Nordstrom", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "point_of_interest", "shoe_store", "store" ], "straightLineDistanceMeters": 329.45178 }, { "name": "places/ChIJmx1c5x7Lj4ARJXJy_CU_JbE", "placeId": "ChIJmx1c5x7Lj4ARJXJy_CU_JbE", "displayName": { "text": "Monroe Parking Garage", "languageCode": "en" }, "types": [ "establishment", "parking", "point_of_interest" ], "straightLineDistanceMeters": 227.05153 }, { "name": "places/ChIJxcwBziHLj4ARUQLAvtzkRCM", "placeId": "ChIJxcwBziHLj4ARUQLAvtzkRCM", "displayName": { "text": "Studios Inn by Daiwa Living California Inc.", "languageCode": "en" }, "types": [ "establishment", "lodging", "point_of_interest", "real_estate_agency" ], "straightLineDistanceMeters": 299.9955 }, { "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI", "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI", "displayName": { "text": "Din Tai Fung", "languageCode": "en" }, "types": [ "establishment", "food", "point_of_interest", "restaurant" ], "straightLineDistanceMeters": 157.70943 } ], "areas": [ { "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI", "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI", "displayName": { "text": "Westfield Valley Fair", "languageCode": "en" }, "containment": "WITHIN" }, { "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q", "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q", "displayName": { "text": "Valley Fair", "languageCode": "en" }, "containment": "WITHIN" }, { "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM", "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM", "displayName": { "text": "Central San Jose", "languageCode": "en" }, "containment": "WITHIN" } ] } }
Gerar detalhes de um lugar que foi movido
Se um lugar referenciado no seu app tiver sido realocado, use os campos
movedPlace e movedPlaceId para receber os detalhes do novo lugar.
Para lugares permanentemente fechados, o Place Details (novo) retorna CLOSED_PERMANENTLY no campo businessStatus e omite os campos movedPlace e movedPlaceId no corpo da resposta.
Para lugares que mudaram para um novo local, o Place Details (novo) retorna CLOSED_PERMANENTLY no campo businessStatus e o novo local nos campos movedPlace e movedPlaceId do corpo da resposta.
Para lugares que não foram movidos, o Place Details (novo) não retorna movedPlace ou movedPlaceId no corpo da resposta.
O exemplo a seguir solicita informações sobre o Marche IGA St-Canut em Quebec, Canadá:
curl -X GET -H 'Content-Type: application/json' \ -H 'x-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: id,displayName,businessStatus,movedPlace,movedPlaceId' \ https://places.googleapis.com/v1/places/ChIJUfQdGInVzkwRzAjmjzWB7CQ
A solicitação retorna a seguinte resposta:
{ "id": "ChIJUfQdGInVzkwRzAjmjzWB7CQ", "businessStatus": "CLOSED_PERMANENTLY", "displayName": { "text": "Marche IGA St-Canut", "languageCode": "en" }, "movedPlace": "places/ChIJ36QT7n8qz0wRDqVZ_UBlUlQ", "movedPlaceId": "ChIJ36QT7n8qz0wRDqVZ_UBlUlQ" }
Para solicitar detalhes sobre o novo lugar, use o nome do recurso de lugar no campo movedPlace em uma nova solicitação de Place Details (New).
Para lugares que mudaram várias vezes, conseguir detalhes sobre o local atual pode exigir várias solicitações encadeadas de Place Details (novo). Os campos movedPlace e movedPlaceId de um resultado de lugar apontam apenas para o próximo local, não para o último local conhecido. Um lugar está na localização atual se uma solicitação de Place Details (novo)
omitir os campos movedPlace e movedPlaceId no corpo da resposta.
Encontrar empresas que vão abrir no futuro
Você pode pedir detalhes sobre empresas que devem abrir no futuro.
O Nearby Search (novo) vai preencher o campo openingDate se a data de abertura prevista incluir pelo menos o mês e estiver a menos de 90 dias.
O exemplo a seguir mostra uma solicitação de Nearby Search (nova) para uma empresa que será inaugurada no futuro em New Meadows, Idaho:
curl -X GET \ -H "Content-Type: application/json" \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,businessStatus,openingDate" \ "https://places.googleapis.com/v1/places/ChIJp1-VoKWJplQRMz8g-7Wa3Do"
A resposta inclui o status da empresa do lugar e a data de abertura prevista:
{ "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do", "businessStatus": "FUTURE_OPENING", "openingDate": { "year": 2026, "month": 4, "day": 15 } }
Receber informações sobre estações de transporte público
Você pode usar o Place Details (New) para receber informações sobre estações de transporte público. O corpo da resposta inclui informações sobre a estação, como nome, empresas de transporte público afiliadas e linhas de transporte público que atendem a estação. Além disso, a resposta inclui um ícone de veículo e cores que podem ser usadas para mostrar as informações da estação de transporte público.
O exemplo a seguir mostra uma solicitação de informações sobre a estação de transporte público Grand Central:
curl -X GET \ -H "Content-Type: application/json" \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,transitStation" \ "https://places.googleapis.com/v1/places/ChIJLVaKiQFZwokRgcybX3K6Pzg"
O corpo da resposta inclui informações sobre cada estação dentro do raio, linhas atendidas pela estação, alertas emitidos pelas agências de transporte público naquele ponto e informações de partida:
{ "id": "ChIJLVaKiQFZwokRgcybX3K6Pzg", "displayName": { "text": "Grand Central", "languageCode": "en" }, "transitStation": { "displayName": { "text": "Grand Central", "languageCode": "en" }, "agencies": [ { "displayName": { "text": "MTA New York City Transit", "languageCode": "en" }, "url": "http://www.mta.info/", "lines": [ { "id": "ChIJ420yFwBZwokR903kVZLSsFc", "vehicleType": "SUBWAY", "displayName": { "text": "42 St Shuttle", "languageCode": "en" }, "shortDisplayName": { "text": "S", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#808183", "url": "https://www.mta.info/schedules/subway/42-st-shuttle", "icon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/S.svg", "nameIncluded": true }, "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg" } }, { "id": "ChIJDdd_uEdfwokRHbLvWrdBdDM", "vehicleType": "SUBWAY", "displayName": { "text": "5 Train (Lexington Av Express)", "languageCode": "en" }, "shortDisplayName": { "text": "5 Line", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#00933C", "url": "https://www.mta.info/schedules/subway/5-train", "icon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/5.svg", "nameIncluded": true }, "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg" } } ... ] }, { "displayName": { "text": "MTA", "languageCode": "en" }, "url": "https://new.mta.info/", "lines": [ { "id": "ChIJcwVpzKpZwokR24EBeh8arww", "vehicleType": "BUS", "displayName": { "text": "United Nations - W 42 St Pier", "languageCode": "en" }, "shortDisplayName": { "text": "M42", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#1D59B3", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg" } } ] }, { "displayName": { "text": "Long Island Rail Road", "languageCode": "en" }, "url": "http://www.mta.info/lirr", "lines": [ { "id": "ChIJv9m8uWM56IkRUcVBQ6Q_In0", "vehicleType": "HEAVY_RAIL", "displayName": { "text": "Ronkonkoma Branch", "languageCode": "en" }, "shortDisplayName": { "text": "LIRR", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#A626AA", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg" } } ... ] } ], "stops": [ { "id": "ChIJRcemlf1YwokRhFqqw5jKBFM", "stopCode": { "text": "GCT" }, "location": { "latitude": 40.755161, "longitude": -73.975456 }, "wheelchairAccessibleEntrance": true }, { "id": "ChIJ57l2zANZwokRD1pyhuwpfKY", "signageText": { "text": "34 St-Hudson Yards & Main St-Flushing, Queens, 7", "languageCode": "en" }, "location": { "latitude": 40.750983, "longitude": -73.9750686 }, "wheelchairAccessibleEntrance": true }, { "id": "ChIJoVXJgQFZwokR1yzq_WVuEuc", "displayName": { "text": "E 42 St/Park Av", "languageCode": "en" }, "location": { "latitude": 40.7518199, "longitude": -73.9771918 }, "wheelchairAccessibleEntrance": true } ... ] } }
Encontrar entradas e pontos de navegação
Você pode solicitar entradas e pontos de navegação para um destino. As entradas definem pontos de entrada e saída de um lugar (por exemplo, diferentes portões em um aeroporto ou shopping). Os pontos de navegação definem locais à beira da estrada onde a navegação deve terminar, o que é útil para direcionar os usuários ao lado correto da via ou a um ponto de desembarque específico.
Os pontos de navegação retornam um navigationPointToken. Você pode transmitir esse token para o SDK de navegação (disponível para Android ou iOS) ou para a API Routes e orientar os motoristas até esse local específico. Para mais informações, consulte Tokens de ponto de navegação.
O exemplo a seguir solicita detalhes do Aeroporto Internacional de São Francisco (ID do lugar ChIJVVVVVYx3j4ARP-3NGldc8qQ), incluindo entrances e navigationPoints na máscara de campo:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,entrances,navigationPoints" \ https://places.googleapis.com/v1/places/ChIJVVVVVYx3j4ARP-3NGldc8qQ
A resposta inclui as entradas e os pontos de navegação do lugar:
{ "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ", "displayName": { "text": "San Francisco International Airport", "languageCode": "en" }, "entrances": [ { "location": { "latitude": 37.6172154, "longitude": -122.3839724 } }, { "location": { "latitude": 37.6174073, "longitude": -122.384196 } }, ... ], "navigationPoints": [ { "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...", "displayName": { "text": "International Terminal Departures Level", "languageCode": "en" }, "location": { "latitude": 37.6153121, "longitude": -122.3900833 }, "travelModes": ["WALK"] }, { "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...", "displayName": { "text": "Domestic Garage - SFO Short Term Parking", "languageCode": "en" }, "location": { "latitude": 37.6157153, "longitude": -122.3885012 }, "travelModes": ["DRIVE", "WALK"], "usages": ["PARKING"] }, ... ] }
Confira!
Com o APIs Explorer, você pode fazer solicitações de amostra para se familiarizar com a API e as opções dela.
Selecione o ícone da API api no lado direito da página.
Se quiser, edite os parâmetros da solicitação.
Selecione o botão Executar. Na caixa de diálogo, escolha a conta que você quer usar para fazer a solicitação.
No painel do APIs Explorer, selecione o ícone de tela cheia fullscreen para expandir a janela.