Começar a usar a API Geocoding v4

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

Se o endereço de faturamento estiver no Espaço Econômico Europeu, a partir de 8 de julho de 2025, os Termos de Serviço da Plataforma Google Maps para o EEE vão valer para o uso dos serviços. A funcionalidade varia de acordo com a região. Saiba mais.

Antes de começar : para usar a API Geocoding, você precisa ter um projeto com uma conta de faturamento e ativar a API Geocoding . Recomendamos ter vários Proprietários do projeto e administradores de faturamento para que sempre haja alguém disponível com essas funções na sua equipe. Para saber mais, consulte Configurar no console do Cloud.

A API Geocoding v4 oferece duas famílias de recursos principais: pesquisa de destino para atributos hiperlocais avançados e geocodificação básica (conversão de coordenadas em endereços). Não sabe qual método usar? Consulte Escolher um método de geocodificação.

• Pesquisar destinos (SearchDestinations): recupera detalhes de chegada avançados para um destino, incluindo entradas de edifícios, pontos de navegação roteáveis, contornos de edifícios/terrenos, subdestinos e pontos de referência próximos.
• Geocodificação (GeocodeAddress): converte endereços em coordenadas de latitude e longitude para posicionar marcadores básicos ou centralizar um mapa.
• Geocodificação inversa (GeocodeLocation): converte coordenadas geográficas em um endereço legível por humanos.
• Geocodificação de lugar (GeocodePlace): encontra o endereço formatado e as coordenadas de um ID de lugar conhecido.

Exemplos de solicitações e respostas

A API Geocoding é acessada por uma interface HTTP. Confira abaixo exemplos de guias de início rápido para Pesquisar destinos, geocodificação direta e geocodificação inversa.

Solicitação e resposta de pesquisa de destinos (dados de chegada hiperlocal)

O exemplo a seguir envia uma solicitação HTTP POST para SearchDestinations para "1600 Amphitheatre Parkway, Mountain View, CA". SearchDestinations requer um cabeçalho X-Goog-FieldMask que especifique os campos a serem retornados:

curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "1600 Amphitheatre Parkway, Mountain View, CA"
  }
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.formattedAddress,destinations.primary.location,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \
-H "X-Goog-Api-Key: YOUR_API_KEY" \
"https://geocode.googleapis.com/v4/geocode/destinations"

Confira abaixo um exemplo de resposta SearchDestinations que mostra o polígono da planta da construção, as entradas preferenciais, os pontos de navegação roteáveis e os pontos de referência próximos:

{
  "destinations": [
    {
      "primary": {
        "displayName": { "text": "Googleplex", "languageCode": "en" },
        "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
        "location": { "latitude": 37.4220656, "longitude": -122.0840897 },
        "displayPolygon": {
          "type": "Polygon",
          "coordinates": [
            [
              [-122.084958, 37.422145],
              [-122.084112, 37.422610],
              [-122.083510, 37.421980],
              [-122.084958, 37.422145]
            ]
          ]
        }
      },
      "entrances": [
        {
          "location": { "latitude": 37.422189, "longitude": -122.084215 },
          "tags": ["PREFERRED"]
        }
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "Eg...",
          "displayName": { "text": "Amphitheatre Pkwy Dropoff", "languageCode": "en" },
          "location": { "latitude": 37.421912, "longitude": -122.084301 },
          "travelModes": ["DRIVE"],
          "usages": ["DROPOFF", "PICKUP"]
        }
      ],
      "landmarks": [
        {
          "place": { "displayName": { "text": "Charleston Park", "languageCode": "en" } },
          "relationalDescription": { "text": "Adjacent to Charleston Park", "languageCode": "en" },
          "straightLineDistanceMeters": 85.4
        }
      ]
    }
  ]
}

Solicitação e resposta de geocodificação (pesquisa de latitude/longitude)

O exemplo a seguir solicita a latitude e a longitude de "1600 Amphitheatre Parkway, Mountain View, CA" e especifica que a saída precisa estar no formato JSON.

curl -H "X-Goog-Api-Key: YOUR_API_KEY" \
"https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

Para testar, insira o URL no navegador da Web (substitua YOUR_API_KEY pela sua chave de API). A resposta inclui a latitude e a longitude do endereço.

Consulte o guia para desenvolvedores para mais informações sobre como criar URLs de solicitação de geocodificação, parâmetros disponíveis e como entender a resposta.

Veja a seguir um exemplo de resposta de geocodificação em JSON:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJ2Z2idB66j4ARI43TG-9RoCQ",
      "placeId": "ChIJ2Z2idB66j4ARI43TG-9RoCQ",
      "location": {
        "latitude": 37.4438238,
        "longitude": -122.0869895
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4424748197085,
          "longitude": -122.0883384802915
        },
        "high": {
          "latitude": 37.445172780291493,
          "longitude": -122.08564051970852
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "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"
          ]
        },
        {
          "longText": "1351",
          "shortText": "1351",
          "types": [
            "postal_code_suffix"
          ]
        }
      ],
      "types": [
        "premise",
        "street_address"
      ]
    }
  ]
}

Solicitação e resposta de geocodificação reversa (pesquisa de endereço)

O exemplo a seguir solicita o endereço correspondente a uma determinada latitude/longitude no Brooklyn, NY, EUA. Ele especifica que a saída deve ser no formato JSON.

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=YOUR_API_KEY

Para testar, insira o URL no navegador da Web (substitua "YOUR_API_KEY" pela sua chave de API). A resposta inclui um endereço legível para humanos referente à latitude e longitude do local.

Consulte o guia para desenvolvedores para mais informações sobre como criar URLs de solicitação de geocodificação inversa, parâmetros disponíveis e como entender a resposta.

Veja a seguir um exemplo de resposta de geocodificação reversa em JSON:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJHRNUiQK6j4ARJ__Hrbt6qsE",
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE",
      "location": {
        "latitude": 37.4225657,
        "longitude": -122.08465439999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421214719708509,
          "longitude": -122.08603273029148
        },
        "high": {
          "latitude": 37.423912680291508,
          "longitude": -122.0833347697085
        }
      },
      "bounds": {
        "low": {
          "latitude": 37.4225178,
          "longitude": -122.08484599999998
        },
        "high": {
          "latitude": 37.422609600000008,
          "longitude": -122.0845215
        }
      },
      "formattedAddress": "Google Building 40, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "Google Building 40",
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "Google Building 40",
          "shortText": "Google Building 40",
          "types": [
            "premise"
          ],
          "languageCode": "en"
        },
        {
          "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": [
        "street_address",
        "subpremise"
      ]
    },
    ... Additional results truncated in this example[] ...
}

Autenticação, cotas, preços e políticas

Autenticação

Para usar a API Geocoding, primeiro é necessário ativá-la e conseguir as credenciais de autenticação adequadas. Para mais informações, consulte Começar a usar a Plataforma Google Maps.

Cotas e preços

Consulte a página de uso e faturamento para saber mais sobre as cotas e os preços definidos para a API Geocoding.

Observação: durante o pré-lançamento, os métodos da API Geocoding v4 são limitados a 25 consultas por segundo (QPS). Para saber como solicitar uma cota maior, consulte Ver e gerenciar cotas e selecione API Geocoding como o serviço.

Aviso: devido a riscos de segurança, não chame os métodos da API Geocoding v4 diretamente do JavaScript do lado do cliente. Se você estiver fazendo isso contra as recomendações, saiba que solicitar cotas mais altas aumenta o impacto potencial do abuso de chaves de API. Consulte Considerações sobre segurança.

Políticas

O uso da API Geocoding precisa estar de acordo com as políticas da API.