A
Destination
se refere a um ponto de interesse significativo ou um local específico que um usuário
pretende alcançar ou navegar. Um Destination pode incluir informações como pontos de navegação, pontos de referência, entradas e contornos de edifícios.
O
SearchDestinations
método da API Geocoding permite recuperar informações detalhadas sobre vários
destinos com base em diferentes critérios de entrada, como um endereço, ID de lugar ou
coordenadas de latitude e longitude.
Solicitação de pesquisa de destinos
Uma solicitação de pesquisa de destinos é uma solicitação HTTP POST para um URL no formato:
https://geocode.googleapis.com/v4/geocode/destinations
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 '{
"place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations
Você pode especificar o local para pesquisar um destino de três maneiras:
- Endereço
- ID de lugar
- Coordenadas de latitude e longitude
Pesquisar um destino por endereço
Você pode especificar o endereço como uma string não estruturada. A geocodificação de endereços não resolve coordenadas de latitude e longitude ou outras strings não estruturadas que não representam um endereço. As solicitações que usam essas strings não são aceitas e podem levar a respostas de erro ou comportamento não especificado. Confira alguns exemplos de consultas não aceitas:
| Tipo de consulta | Exemplo |
|---|---|
| Coordenadas de latitude e longitude. Use uma consulta de local em vez disso. | "37.422131,-122.084801" |
| Muitos conceitos ou restrições, como os nomes de vários lugares, estradas ou cidades em uma única consulta | "Market Street San Francisco San Jose Airport" |
| Elementos de endereço postal não representados no Google Maps |
"C/O John Smith 123 Main Street" "P.O. Box 13 San Francisco" |
| Nomes de empresas, redes ou categorias combinados com locais em que essas entidades não estão disponíveis | "Tesco near Dallas, Texas" |
| Consultas ambíguas com várias interpretações | "Charger drop-off" |
| Nomes históricos que não estão mais em uso | "Middlesex United Kingdom" |
| Elementos ou intents não geoespaciais | "How many boats are in Ventura Harbor?" |
| Nomes não oficiais ou de vaidade |
"The Jenga" "The Helter Skelter" |
| Grandes entidades políticas (cidades, estados, países) |
"New York City" "California" "USA" |
| Rotas sem endereços específicos |
"1st Ave., NYC, NY" "I-95" |
curl -X POST -d '{
"addressQuery": {
"addressQuery": "601 S Bernardo Ave, Sunnyvale, CA 94087, USA"
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations
ou como um
postalAddress:
curl -X POST -d '{
"addressQuery": {
"address": {
"addressLines": ["601 S Bernardo Ave"],
"locality": "Sunnyvale",
"postalCode": "94087",
"administrativeArea": "CA",
"regionCode": "US"
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations
Normalmente, você usa o formato postalAddress ao processar componentes de endereço capturados em um formulário HTML.
Pesquisar um destino por ID de lugar
Você pode recuperar um destino fornecendo um ID de lugar:
curl -X POST -d '{
"place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations
IDs de lugar aceitos
O método de pesquisa de destinos funciona melhor com IDs de lugar que representam destinos específicos e navegáveis. Os IDs de lugar para tipos como establishment,
point_of_interest, premise, street_address, e subpremise geralmente
são aceitos. Os IDs de lugar que não representam locais discretos, como aqueles inferidos de intervalos de endereços (por exemplo, "10-20 Main St"), seções de uma rota sem um número específico ou plus codes não são aceitos. Os IDs de lugar para resultados que são muito grandes em área (por exemplo, "Oceano Pacífico") também não são aceitos.
Usar a API Places Autocomplete (New) com a pesquisa de destinos
Para garantir a compatibilidade, use API Places Autocomplete
(New) para encontrar IDs de lugar para uso com a pesquisa de destinos. Ao usar o Autocomplete, filtre
os resultados por tipo usando o
includedPrimaryTypes
parâmetro. Os IDs de lugar retornados pelo Autocomplete usando o filtro recomendado a seguir são aceitos pela pesquisa de destinos:
"includedPrimaryTypes": [ "establishment", "point_of_interest", "premise", "street_address", "subpremise" ]
Além disso, não defina a include_pure_service_area_businesses
flag como true na sua solicitação de Autocomplete.
Pesquisar um destino por local
Você pode pesquisar um destino fornecendo coordenadas de latitude e longitude:
curl -X POST -d '{
"locationQuery": {
"location": {
"latitude": 37.37348780,
"longitude": -122.05678064
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations
Usar o OAuth para fazer uma solicitação
A API Geocoding v4 é compatível com o OAuth 2.0 para autenticação. Para usar o OAuth com a API Geocoding, o token do OAuth precisa receber o escopo correto. A API Geocoding aceita os seguintes escopos para uso com o método Destinations:
https://www.googleapis.com/auth/maps-platform.geocode: use com todos os métodos da API Geocoding.
Além disso, você pode usar o escopo geral https://www.googleapis.com/auth/cloud-platform para todos os métodos da API Geocoding. Esse escopo é útil durante o desenvolvimento, mas não na produção, porque é um escopo geral que permite o acesso a todos os métodos.
Para mais informações e exemplos, consulte Usar o OAuth.
Resposta de pesquisa de destinos
A resposta de pesquisa de destinos fornece um contexto rico e hiperlocal sobre o local.
Esta seção descreve os principais campos de resposta. Para detalhes completos sobre todos os campos de resposta, consulte a referência da API.
primary
O lugar principal identificado pela consulta na solicitação.
containingPlaces
Entidades maiores das quais o destino principal faz parte (por exemplo, um shopping center que contém uma loja).
subDestinations
Locais mais específicos dentro do destino principal (por exemplo, apartamentos em um prédio).
entrances
Os objetos na matriz entrances[] têm os seguintes campos:
locationUm único par de coordenadas de latitude/longitude que define o local de um ponto de entrada e saída em um lugar.
entrance_tags[]Uma matriz de tags de entrada que descreve as características da entrada. O valor a seguir é aceito:
"PREFERRED"
Indica que essa entrada provavelmente fornece acesso físico ao lugar retornado. Um lugar pode ter várias entradas preferenciais. Se uma entrada não tiver essa tag, significa que ela está fisicamente no mesmo prédio, mas não necessariamente fornece acesso ao lugar.
Por exemplo, se o lugar retornado for um restaurante em um shopping center, as
"PREFERRED"entradas serão aquelas que levam ao restaurante em si, enquanto as outras entradas retornadas serão outras entradas do prédio, como entradas em outros restaurantes no shopping center.Se o lugar retornado for um prédio, as entradas
"PREFERRED"serão aquelas que levam à parte "principal" do prédio. Por exemplo, em um shopping center, as entradas"PREFERRED"serão aquelas que permitem acesso à área principal do saguão, mas se uma entrada só fornecer acesso a uma loja na lateral do prédio, ela não será uma entrada"PREFERRED".
structureType
O tipo de estrutura que esse lugar representa.
POINTUm local de ponto.
SECTIONUma subseção de um prédio.
BUILDINGUm prédio.
GROUNDSUma área grande que normalmente contém vários edifícios, como um campus universitário, um condomínio ou um shopping center.
navigationPoints
O campo navigationPoints na resposta da API Geocoding contém uma lista de pontos úteis para navegar até o lugar. Especificamente, eles precisam ser usados como pontos de partida ou de chegada ao rotear em uma rede rodoviária de ou para o lugar. Cada ponto de navegação contém os seguintes valores:
navigationPointTokené um token que contém as informações contextuais no camponavigationPoints. Você pode enviar esse token para APIs de roteamento e navegação para melhorar o roteamento e a experiência do usuário no app. Consulte Rota usando tokens de ponto de navegação para mais informações.locationcontém o valor de latitude e longitude do ponto de navegação. Esse local sempre estará muito próximo da rede rodoviária e representa um ponto de parada ou de partida ideal para navegar de e para um lugar. O ponto é intencionalmente ligeiramente deslocado da linha central da estrada para marcar claramente o lado da estrada em que o lugar está localizado.travelModesé uma lista de modos de viagem que o ponto de navegação pode acessar:"DRIVE"é o modo de viagem correspondente às rotas de carro."WALK"é o modo de viagem correspondente às rotas a pé.
usagesé uma lista de usos aceitos pelo ponto de navegação. Os usos podem ser:"DROPOFF""PICKUP""PARKING"
arrivalSummary
Insights com tecnologia de IA para ajudar na chegada. Consulte Resumos com tecnologia de IA summaries.
landmarks
Lugares notáveis nas proximidades para ajudar os usuários a entender os arredores do destino.
Formato da resposta
SearchDestinations retorna um
SearchDestinationsResponse
do seguinte formato JSON:
{ "destinations": [ { "primary": { "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w", "displayName": { "text": "Arby's", "languageCode": "en" }, "primaryType": "fast_food_restaurant", "types": [ "fast_food_restaurant", "sandwich_shop", "deli", "meal_takeaway", "food_delivery", "american_restaurant", "restaurant", "food_store", "store", "food", "point_of_interest", "establishment" ], "formattedAddress": "Arby's, 601 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "601 S Bernardo Ave" ] }, "structureType": "BUILDING", "location": { "latitude": 37.3734545, "longitude": -122.05693269999998 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [ -122.056930138027, 37.3735253692531 ], [ -122.056960139391, 37.3735372663597 ], [ -122.056994129366, 37.3734828786847 ], [ -122.056969677395, 37.3734731161089 ], [ -122.057061762447, 37.3733261309656 ], [ -122.056979388817, 37.3732935577128 ], [ -122.056798860285, 37.3735818838642 ], [ -122.056875858081, 37.3736121235316 ], [ -122.056930138027, 37.3735253692531 ] ] ] } }, "containingPlaces": [ { "place": "places/ChIJYfdAFum2j4ARIcL2tjME3Sw", "displayName": { "text": "Cherry Chase Shopping Center", "languageCode": "en" }, "primaryType": "shopping_mall", "types": [ "shopping_mall", "point_of_interest", "establishment" ], "formattedAddress": "Cherry Chase Shopping Center, 663 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1020", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "663 S Bernardo Ave" ] }, "structureType": "GROUNDS", "location": { "latitude": 37.3731231, "longitude": -122.0578211 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [ -122.057112227103, 37.3714618008523 ], [ -122.057076849821, 37.3715743611411 ], [ -122.056963607756, 37.3719081793948 ], [ -122.056865279559, 37.3722026053835 ], [ -122.056687872374, 37.3727258358476 ], [ -122.056580005889, 37.3730511370747 ], [ -122.056498845827, 37.3732994782583 ], [ -122.056338259713, 37.3737878663325 ], [ -122.056618678291, 37.373887693582 ], [ -122.056912102521, 37.3740010327191 ], [ -122.057532418159, 37.3742476426462 ], [ -122.057673926626, 37.3742441740031 ], [ -122.057735663106, 37.3742328516943 ], [ -122.057766531332, 37.3742220604378 ], [ -122.057797572967, 37.37420520725 ], [ -122.057828267759, 37.3741852342085 ], [ -122.058060299297, 37.3740060842535 ], [ -122.058199726081, 37.3737861673422 ], [ -122.05836707267, 37.373524542556 ], [ -122.058569622393, 37.3732018598683 ], [ -122.0587638478, 37.3728890198039 ], [ -122.058934661823, 37.3726036257774 ], [ -122.059164956851, 37.3722498383629 ], [ -122.058997784906, 37.3721804442035 ], [ -122.057936479838, 37.3717605636234 ], [ -122.057495827092, 37.3715860151634 ], [ -122.057112227103, 37.3714618008523 ] ] ] } } ], "landmarks": [ { "place": { "place": "places/ChIJXXTe7Oi2j4ARoMTA-D6Hjpg", "displayName": { "text": "Chase Bank", "languageCode": "en" }, "primaryType": "bank", "types": [ "bank", "atm", "finance", "point_of_interest", "establishment" ], "formattedAddress": "Chase Bank, 1234 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1234 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.373579, "longitude": -122.05752700000001 } }, "relationalDescription": { "text": "Near Chase Bank", "languageCode": "en" }, "tags": [ "ARRIVAL", "ADDRESS" ], "straightLineDistanceMeters": 61.182193756103516, "travelDistanceMeters": 63.075645446777344 }, { "place": { "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14", "displayName": { "text": "Safeway", "languageCode": "en" }, "primaryType": "grocery_store", "types": [ "grocery_store", "butcher_shop", "florist", "deli", "supermarket", "bakery", "food_delivery", "market", "manufacturer", "food_store", "store", "food", "service", "point_of_interest", "establishment" ], "formattedAddress": "Safeway, 639 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "639 S Bernardo Ave" ] }, "structureType": "POINT", "location": { "latitude": 37.3727912, "longitude": -122.0581172 } }, "relationalDescription": { "text": "Around the corner from Safeway", "languageCode": "en" }, "tags": [ "ARRIVAL", "ADDRESS" ], "straightLineDistanceMeters": 158.65606689453125, "travelDistanceMeters": 131.1669921875 }, { "place": { "place": "places/ChIJu-PSYui2j4ARNiwOwBApGqk", "displayName": { "text": "Oil Changers", "languageCode": "en" }, "types": [ "car_repair", "service", "point_of_interest", "establishment" ], "formattedAddress": "Oil Changers, 1240 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1240 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.3743054, "longitude": -122.0584272 } }, "relationalDescription": { "text": "Down the road from Oil Changers", "languageCode": "en" }, "tags": [ "ARRIVAL" ], "straightLineDistanceMeters": 140.52459716796875, "travelDistanceMeters": 143.24220275878906 }, { "place": { "place": "places/ChIJKRbl5oG3j4ARwuvPGUmtCj0", "displayName": { "text": "Apni Mandi Farmers Market Sunnyvale", "languageCode": "en" }, "primaryType": "grocery_store", "types": [ "grocery_store", "cake_shop", "supermarket", "asian_grocery_store", "indian_restaurant", "meal_takeaway", "bakery", "manufacturer", "wholesaler", "restaurant", "food_store", "store", "food", "point_of_interest", "establishment" ], "formattedAddress": "Apni Mandi Farmers Market Sunnyvale, 1111 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1056", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1111 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.3737199, "longitude": -122.0522958 } }, "relationalDescription": { "text": "Near Apni Mandi Farmers Market Sunnyvale", "languageCode": "en" }, "tags": [ "ADDRESS" ], "straightLineDistanceMeters": 410.37435913085938, "travelDistanceMeters": 479.49893188476562 }, { "place": { "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs", "displayName": { "text": "Starbird Chicken", "languageCode": "en" }, "primaryType": "chicken_restaurant", "types": [ "chicken_restaurant", "fast_food_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "Starbird Chicken, 1241 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1028", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1241 W El Camino Real" ] }, "structureType": "BUILDING", "location": { "latitude": 37.3746764, "longitude": -122.05708860000001 }, "displayPolygon": { "coordinates": [ [ [ -122.057003840785, 37.3747648209809 ], [ -122.057136852459, 37.3747919153144 ], [ -122.057205005705, 37.3745815131859 ], [ -122.057071994114, 37.3745544186944 ], [ -122.057003840785, 37.3747648209809 ] ] ], "type": "Polygon" } }, "relationalDescription": { "text": "Near Starbird Chicken", "languageCode": "en" }, "tags": [ "ADDRESS" ], "straightLineDistanceMeters": 87.348007202148438, "travelDistanceMeters": 214.08084106445312 } ], "entrances": [ { "location": { "latitude": 37.3735328, "longitude": -122.05694879999999 }, "tags": [ "PREFERRED" ], "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w" } ], "navigationPoints": [ { "navigationPointToken": "ChIJeMt61tqvQkARWT2716SDXsASEgljyy_n6LaPgBH9LoGUMNHjbBoSCWPLL-foto-AEf0ugZQw0eNsIhIJhf5y6ei2j4ARz7yBW5KAPI4", "location": { "latitude": 37.3738659, "longitude": -122.05693620000001 }, "travelModes": [ "DRIVE", "WALK" ], "usages": [ "PARKING" ] } ] } ] }
Parâmetros obrigatórios
- Um dos três parâmetros a seguir precisa estar na solicitação da API, que
especifica o endereço, o lugar ou o local para pesquisar um destino:
addressQuery: o endereço a ser pesquisado.place: o ID do lugar a ser pesquisado.locationQuery: as coordenadas de latitude e longitude do o local a ser pesquisado.
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
$fieldsoufields, ou usando o cabeçalho HTTPX-Goog-FieldMask. Por exemplo, a solicitação abaixo retornará apenas as entradas, os pontos de navegação e o ID do lugar do destino principal.curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \ -H "X-Goog-Api-Key: API_KEY" \ -H "Content-Type: application/json" \ -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary.place" \ https://geocode.googleapis.com/v4/geocode/destinationsNã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. Defina a máscara de campo como
*para retornar todos os campos. Consulte Escolher campos a serem retornados para mais detalhes.
Parâmetros opcionais
-
travelModes
Especifica quais tipos de
navigationPointsretornar. Os pontos de navegação para outros modos de viagem serão filtrados. SetravelModesnão estiver definido, os pontos de navegação de todos os modos de viagem poderão ser retornados. languageCode
O idioma em que os resultados serão retornados.
- Consulte a lista de idiomas aceitos. O Google atualiza os idiomas aceitos com frequência, então essa lista pode não ser exaustiva.
-
Se
languageCodenão for fornecido, a API vai usarencomo padrão. Se você especificar um código de idioma inválido, a API retornará umINVALID_ARGUMENTerro. - A API faz o possível para fornecer um endereço de rua legível para o usuário e os moradores locais. Para atingir esse objetivo, ela retorna endereços de rua no idioma local, transliterados 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 preferido. 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 regional como um código CLDR de duas letras valor. Não há valor padrão. A maioria dos códigos CLDR é idêntica aos códigos ISO 3166-1.
Ao geocodificar um endereço, geocodificação direta, esse parâmetro pode influenciar, mas não restringir totalmente, os resultados do serviço à região especificada. Ao geocodificar um local ou um lugar, geocodificação inversa ou geocodificação de lugar, esse parâmetro pode ser usado para formatar o endereço. Em todos os casos, esse parâmetro pode afetar os resultados com base na legislação aplicável.
-
placeFilter
Permite filtrar os resultados de uma
locationQuerypesquisa para atender aos seus requisitos, como retornar apenas destinos que são edifícios ou apenas destinos que têm endereços claros.Filtrar por granularidade estrutural
O filtro
structureTypepermite especificar o tipo de estruturas que são retornadas pela consulta:- Isolar edifícios: use
"structureType": "BUILDING"para mostrar contornos de edifícios em um mapa ou receber detalhes de uma estrutura específica. - Entender complexos: use
"structureType": "GROUNDS"para garantir que o resultado principal seja o terreno geral. Isso é útil ao consultar áreas maiores, como campi universitários ou shopping centers. - Focar em unidades/seções: use
"structureType": "SECTION"para identificar seções dentro de um prédio.
Garantir endereços úteis
Nem todos os lugares têm endereços claros no nível da rua. O filtro
addressabilityajuda a controlar a qualidade dos endereços nos resultados:- Exigir um endereço principal claro: para garantir que o resultado do destino principal
sempre tenha um endereço ou nome de rua, use
"addressability": "PRIMARY". Isso é útil para fins de navegação ou exibição em que um endereço claro é fundamental. - Permitir endereços em subdestinos: nos casos em que o lugar principal
pode não ter um endereço, mas as unidades dentro dele têm (como apartamentos em um
prédio),
"addressability": "WEAK"garante que pelo menos o lugar principal ou um dos subdestinos tenha um endereço. - Qualquer resultado: se a presença do endereço não for relevante para seu caso de uso, use
"addressability": "ANY".
Exemplo: filtragem de edifícios endereçáveis
curl -X POST -d '{ "locationQuery": { "location": { "latitude": 37.37348780, "longitude": -122.05678064 }, "placeFilter": { "structureType": "BUILDING", "addressability": "PRIMARY" } }, "languageCode": "en" }' \\ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \\ -H "X-Goog-FieldMask: place" \\ https://geocode.googleapis.com/v4/geocode/destinations - Isolar edifícios: use