Geocodificar um lugar

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

A geocodificação de lugares permite recuperar um endereço de um ID de lugar.

IDs de lugares identificam um local de modo exclusivo no banco de dados do Google Places e no Google Maps. Recupere IDs de lugares ao Geocodificar um endereço. Você também pode recuperar um ID de lugar de muitas outras APIs, como Place Details (New), Text Search (New), and Nearby Search (New).

Solicitações de geocodificação de lugares

Uma solicitação de geocodificação de lugares é uma solicitação HTTP GET no formato:

https://geocode.googleapis.com/v4/geocode/places/PLACE_ID

Em que PLACE_ID contém o ID de lugar do local de interesse.

Transmita todos os outros parâmetros como parâmetros de URL ou, para parâmetros como a chave de API ou a máscara de campo, em cabeçalhos como parte da solicitação GET. Exemplo:

https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?key=API_KEY

Ou em um comando curl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

Usar o OAuth para fazer uma solicitação

A API Geocoding v4 oferece suporte ao 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 oferece suporte aos seguintes escopos para uso com a geocodificação de lugares:

  • https://www.googleapis.com/auth/maps-platform.geocode : use com todos os métodos da API Geocoding.
  • https://www.googleapis.com/auth/maps-platform.geocode.place : use apenas com GeocodePlace para geocodificação de lugares.

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.

Respostas de geocodificação de lugares

A geocodificação de lugar retorna um GeocodeResult objeto que representa o lugar correspondente ao ID de lugar.

As respostas da API Geocoding incluem types matrizes em dois lugares principais no GeocodeResult:

  1. GeocodeResult.types: essa matriz indica o tipo geral dos resultados. Os valores possíveis são extraídos dos tipos de lugar usados pela API Places. Para mais informações, consulte as tabelas A e B de tipos de lugar.
  2. GeocodeResult.addressComponents[].types: cada componente de endereço tem uma types matriz que indica o tipo dessa parte específica do endereço. Esses valores são extraídos da tabela Tipos de endereço e de componentes de endereço usada pela API Places.

O objeto JSON completo está no formato:

{
  "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "location": {
    "latitude": 37.4220541,
    "longitude": -122.08532419999999
  },
  "granularity": "ROOFTOP",
  "viewport": {
    "low": {
      "latitude": 37.4209489697085,
      "longitude": -122.08846930000001
    },
    "high": {
      "latitude": 37.4236469302915,
      "longitude": -122.0829156
    }
  },
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  "addressComponents": [
    {
      "longText": "1600",
      "shortText": "1600",
      "types": [
        "street_number"
      ]
    },
    {
      "longText": "Amphitheatre Parkway",
      "shortText": "Amphitheatre Pkwy",
      "types": [
        "route"
      ],
      "languageCode": "en"
    },
    {
      "longText": "Mountain View",
      "shortText": "Mountain View",
      "types": [
        "locality",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "Santa Clara County",
      "shortText": "Santa Clara County",
      "types": [
        "administrative_area_level_2",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "California",
      "shortText": "CA",
      "types": [
        "administrative_area_level_1",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "United States",
      "shortText": "US",
      "types": [
        "country",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "94043",
      "shortText": "94043",
      "types": [
        "postal_code"
      ]
    }
  ],
  "types": [
    "establishment",
    "point_of_interest"
  ]
}

Parâmetros obrigatórios

  • place — o ID de lugar para que você quer encontrar o endereço legível por humanos. O ID de local é um identificador exclusivo que pode ser usado com outras APIs do Google. Por exemplo, você pode usar o placeID retornado pela API Roads para conferir o endereço de um ponto alinhado. Para mais informações sobre IDs de lugar, consulte IDs de lugar.

Parâmetros opcionais

  • 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 essa lista pode não ser exaustiva.
    • Se languageCode não for fornecido, a API vai usar o idioma e o script locais do local como padrão. Se você especificar um código de idioma inválido, a API vai retornar um INVALID_ARGUMENT erro.
    • 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 da região como um código CLDR de dois caracteres 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.

  • FieldMask

    Crie uma máscara de campo de resposta para especificar os campos a serem retornados na resposta. Transmita a máscara de campo de resposta para o método usando o parâmetro de URL $fields ou fields, ou usando o cabeçalho HTTP X-Goog-FieldMask. Por exemplo, a solicitação abaixo vai retornar apenas o campo formattedAddress da resposta.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: formattedAddress' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    A resposta é: 
    {
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA"
}

    Consulte Escolher campos a serem retornados para mais detalhes.