Pesquisar destinos

Desenvolvedores do Espaço Econômico Europeu (EEE)

Um Destination se refere a um ponto de interesse significativo ou a um local específico que um usuário pretende alcançar ou para onde quer navegar. Um Destination pode incluir informações como pontos de navegação, pontos de referência, entradas e contornos de edifícios.

O endpoint SearchDestinations 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/v4alpha/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/v4alpha/geocode/destinations

Você pode especificar o local para pesquisar um destino de três maneiras:

  • Endereço
  • ID do lugar
  • Coordenadas de latitude e longitude

Pesquisar um destino por endereço

É possível especificar o endereço como uma string não estruturada:

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/v4alpha/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/v4alpha/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

Para recuperar um destino, forneça 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/v4alpha/geocode/destinations

Pesquisar um destino por local

Você pode pesquisar um destino fornecendo as 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/v4alpha/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 OAuth precisa receber o escopo correto. A API Geocoding aceita os seguintes escopos para uso com o endpoint Destinations:

  • https://www.googleapis.com/auth/maps-platform.geocode — Use com todos os endpoints da API Geocoding.

Além disso, é possível usar o escopo geral https://www.googleapis.com/auth/cloud-platform para todos os endpoints 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 endpoints.

Para mais informações e exemplos, consulte Usar o OAuth.

Resposta da pesquisa de destinos

Contexto hiperlocal sobre o local

A resposta da pesquisa de destinos fornece um contexto rico e hiperlocal sobre o local. Os principais campos incluem:

  • primary: o principal lugar identificado pela consulta na solicitação.
  • containingPlaces: entidades maiores de que 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: pontos específicos de entrada e saída do destino.
  • navigationPoints: locais adequados perto de uma via para o fim da navegação.
  • arrivalSummary: insights com tecnologia de IA para ajudar na chegada. Consulte Resumos com tecnologia de IA.
  • landmarks: lugares notáveis nas proximidades para ajudar os usuários a entender os arredores do destino.

Para mais detalhes sobre todos os campos de resposta, consulte a Referência da API.

Formato da resposta

O 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",
          "american_restaurant",
          "meal_takeaway",
          "restaurant",
          "food_store",
          "food",
          "point_of_interest",
          "store",
          "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/ChIJteQ0Fum2j4ARGi3tqK4Zm14",
            "displayName": {
              "text": "Safeway",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "florist",
              "butcher_shop",
              "deli",
              "bakery",
              "food_delivery",
              "supermarket",
              "market",
              "food_store",
              "food",
              "point_of_interest",
              "store",
              "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
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "relationalDescription": {
            "text": "Around the corner from Safeway",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 158.65607,
          "travelDistanceMeters": 131.16699
        },
        {
          "place": {
            "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs",
            "displayName": {
              "text": "Starbird Chicken",
              "languageCode": "en"
            },
            "types": [
              "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":
 { ... } {
              "type": "Polygon",
              "coordinates": [
                [
                  [
                    -122.057003840785,
                    37.3747648209809
                  ],
                  [
                    -122.057136852459,
                    37.3747919153144
                  ],
                  [
                    -122.057205005705,
                    37.3745815131859
                  ],
                  [
                    -122.057071994114,
                    37.3745544186944
                  ],
                  [
                    -122.057003840785,
                    37.3747648209809
                  ]
                ]
              ]
            }

          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "relationalDescription": {
            "text": "Near Starbird Chicken",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 87.34801,
          "travelDistanceMeters": 214.08084
        },
        {
          "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
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "relationalDescription": {
            "text": "Near Chase Bank",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 61.182194,
          "travelDistanceMeters": 63.075645
        },
        {
          "place": {
            "place": "places/ChIJlbIO1Oi2j4ARp17Uf24xkHk",
            "displayName": {
              "text": "Madras Café",
              "languageCode": "en"
            },
            "primaryType": "indian_restaurant",
            "types": [
              "indian_restaurant",
              "coffee_shop",
              "cafe",
              "restaurant",
              "food_store",
              "food",
              "point_of_interest",
              "store",
              "establishment"
            ],
            "formattedAddress": "Madras Café, 1177 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1026",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1177 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3743,
              "longitude": -122.0549333
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "relationalDescription": {
            "text": "Near Madras Café",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 204.45102,
          "travelDistanceMeters": 235.12041
        }
      ]
,
      "entrances": [
        {
          "location": {
            "latitude": 37.373531299999996,
            "longitude": -122.05694519999999
          },
          "tags": [
            "PREFERRED"
          ],
          "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
        }
      ],
      "navigationPoints": [
        {
          "location": {
            "latitude": 37.3738659,
            "longitude": -122.05693620000001
          },
          "travelModes": [
            "DRIVE",
            "WALK"
          ],
          "usages": [
            "UNKNOWN"
          ]
        }
      ]
    }
  ]
}

Parâmetros obrigatórios

  • Um dos três parâmetros a seguir precisa estar na solicitação de 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 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 $fields ou fields ou o cabeçalho HTTP X-Goog-FieldMask. Por exemplo, a solicitação abaixo retorna 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/v4alpha/geocode/destinations

    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. Defina a máscara de campo como * para retornar todos os campos. Consulte Escolher campos para retornar para mais detalhes.

Parâmetros opcionais

  • travelModes

    Especifica quais tipos de navigationPoints serão retornados. Os pontos de navegação para outros meios de transporte serão filtrados. Se travelModes não estiver definido, os pontos de navegação de todos os meios de transporte poderão ser retornados.

  • languageCode

    O idioma em que os resultados serão retornados.

    • Consulte a lista de idiomas compatíveis. O Google atualiza os idiomas compatíveis com frequência, então esta lista pode não estar completa.
    • Se languageCode não for fornecido, a API usará en como padrão. Se você especificar um código de idioma inválido, a API vai retornar um erro INVALID_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 preferido. 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 regional como um valor código CLDR de dois caracteres. 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 pesquisa locationQuery para atender aos seus requisitos, como retornar apenas destinos que são edifícios ou apenas destinos com endereços claros.

    Filtrar por granularidade estrutural

    Com o filtro structureType, você especifica o tipo de estruturas retornadas pela consulta:

    • Isolar edifícios: use "structureType": "BUILDING" para mostrar os contornos de edifícios em um mapa ou receber detalhes de uma estrutura específica.
    • Entender proposições complexas: use "structureType": "GROUNDS" para garantir que o resultado principal seja o motivo geral. Isso é útil ao consultar áreas maiores, como campi universitários ou shopping centers.
    • Foco em unidades/seções: use "structureType": "SECTION" para identificar seções em um edifício.

    Garantir endereços úteis

    Nem todos os lugares têm endereços claros no nível da rua. O filtro addressability ajuda a controlar a qualidade dos endereços nos resultados:

    • Exigir um endereço principal claro: para garantir que o resultado principal do destino 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 é crucial.
    • 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), o "addressability": "WEAK" garante que pelo menos o lugar principal ou um dos subdestinos tenha um endereço.
    • Qualquer resultado: se a presença de 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/v4alpha/geocode/destinations

Feedback

Este é um endpoint experimental da API Geocoding. Agradecemos seu feedback em geocoding-feedback-channel@google.com.