Serviço Geocoding

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Visão geral

Geocoding é o processo de conversão de endereços (como "quot;1600 Amphitheatre Parkway, Mountain View, CA") em coordenadas geográficas (como latitude 37.423021 e longitude -122.083739), que você pode usar para colocar marcadores ou posicionar o mapa.

A geocodificação inversa é o processo de conversão de coordenadas geográficas em um endereço legível. Consulte Geocodificação reversa (pesquisa de endereço).

Você também pode usar o geocodificador para encontrar o endereço de um determinado ID de lugar.

A API Maps JavaScript oferece uma classe de geocodificador para geocodificação e geocodificação inversa, de acordo com a entrada do usuário. Se você quiser geocodificar endereços estáticos e conhecidos, consulte o Serviço da Web de geocodificação.

Primeiros passos

Antes de usar o serviço Geocoding na API Maps JavaScript, verifique se ela está ativada no Console do Google Cloud, no mesmo projeto que você configurou para a API Maps JavaScript.

Para ver a lista de APIs ativadas:

  1. Acesse o Console do Google Cloud.
  2. Clique no botão Selecionar um projeto, escolha o mesmo projeto configurado para a API Maps JavaScript e clique em Abrir.
  3. Na lista de APIs no Painel, procure API Geocoding.
  4. Se achar a API na lista, está tudo pronto. Se a API não estiver listada, ative-a:
    1. Na parte superior da página, selecione ATIVAR API para exibir a guia Biblioteca. Como alternativa, no menu lateral à esquerda, selecione Biblioteca.
    2. Pesquise API Geocoding e selecione-a na lista de resultados.
    3. Selecione ATIVAR. Quando o processo terminar, a API Geocoding aparecerá na lista de APIs do Painel.

Preços e políticas

Preços

Em 16 de julho de 2018, um novo plano de pagamento por utilização entrou em vigor para o Maps, Routes e Places. Para saber mais sobre os novos limites de preço e uso do serviço JavaScript, consulte Uso e faturamento da API Geocoding.

Limites de taxas

Observações sobre os limites de taxa em solicitações adicionais:

A limitação de taxa extra é aplicada por sessão de usuário, independentemente de quantos usuários compartilham o mesmo projeto. Ao carregar a API pela primeira vez, você recebe uma cota inicial de solicitações. Depois de usar essa cota, a API aplica limites de taxa em outras solicitações por segundo. Se muitas solicitações forem feitas em um determinado período, a API retornará um código de resposta OVER_QUERY_LIMIT.

O limite de taxa por sessão impede o uso de serviços do lado do cliente para solicitações em lote, como geocodificação em lote. Para solicitações em lote, use o serviço da Web da API Geocoding.

Políticas

O uso do serviço de geocodificação precisa estar de acordo com as políticas descritas para a API Geocoding.

Solicitações de Geocoding

O acesso ao serviço de geocodificação é assíncrono, pois a API do Google Maps precisa fazer uma chamada para um servidor externo. Por isso, é necessário transmitir um método de callback para ser executado após a conclusão da solicitação. Esse método de callback processa os resultados. O geocodificador pode retornar mais de um resultado.

Para acessar o serviço de geocodificação da API Google Maps no seu código, use o objeto construtor google.maps.Geocoder. O método Geocoder.geocode() inicia uma solicitação para o serviço de geocodificação, transmitindo um literal de objeto GeocoderRequest que contém os termos de entrada e um método de callback a ser executado no recebimento da resposta.

O literal do objeto GeocoderRequest contém os seguintes campos:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

Parâmetros obrigatórios:é necessário fornecer apenas um dos seguintes campos:

  • address: o endereço que você quer geocodificar.
    ou
    location: o LatLng (ou LatLngLiteral) em que você quer receber o endereço mais próximo legível. O geocodificador executa uma geocodificação reversa. Consulte Geocoding inversa para mais informações.
    ou
    placeId: o ID do lugar em que você quer encontrar o endereço mais próximo e legível. Saiba mais sobre como recuperar um endereço para um ID de lugar.

Parâmetros opcionais:

  • bounds: o LatLngBounds em que os resultados de geocódigo são direcionados de maneira mais proeminente. O parâmetro bounds influencia apenas os resultados do geocodificador, sem restringi-los totalmente. Veja abaixo mais informações sobre a viés de janela de visualização.
  • componentRestrictions: usado para restringir os resultados a uma área específica. Veja mais informações sobre filtragem de componentes abaixo.
  • region: o código da região, especificado como uma especificada como uma subtag de região Unicode de dois caracteres (não numérico). Na maioria dos casos, essas tags mapeiam diretamente para valores de dois caracteres ccTLD ("top-level") conhecidos. O parâmetro region influencia, mas não restringe totalmente, os resultados do geocodificador. Veja mais informações sobre vieses de código regional abaixo.

Respostas de geocodificação

O serviço de geocodificação requer que um método de callback seja executado após a recuperação dos resultados do geocodificador. Esse callback precisa transmitir dois parâmetros para conter o código results e status, nessa ordem.

Resultados da geocodificação

O objeto GeocoderResult representa um único resultado de geocodificação. Uma solicitação de geocodificação pode retornar vários objetos de resultado:

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

Estes campos são explicados abaixo:

  • types[] é uma matriz que indica o tipo de endereço do resultado retornado. Essa matriz contém um conjunto de zero ou mais tags que identificam o tipo de recurso retornado no resultado. Por exemplo, um geocódigo de "quot;Chicago" retorna "locality" que indica que "Chicago" é uma cidade e também retorna "quot;Political", que indica que ela é uma entidade política. Veja abaixo mais informações sobre os tipos de endereço e os tipos de componentes de endereço.
  • formatted_address é uma string que contém o endereço legível desse local.

    Muitas vezes, esse endereço é equivalente ao endereço postal. Alguns países, como o Reino Unido, não permitem a distribuição de endereços postais verdadeiros devido a restrições de licenciamento.

    O endereço formatado é composto de maneira lógica por um ou mais componentes de endereço. Por exemplo, o endereço "111 8th Avenue, New York, NY" consiste nos seguintes componentes: "111" (o número da rua), "8th Avenue" (o trajeto), "New York" (a cidade) e "NY" (estado dos EUA).

    Não analise o endereço formatado de maneira programática. Em vez disso, use os componentes de endereço individuais, que a resposta da API inclui, além do campo de endereço formatado.

  • address_components[] é uma matriz que contém os componentes separados aplicáveis a esse endereço.

    Geralmente, cada componente de endereço contém os seguintes campos:

    • types[] é uma matriz que indica o tipo do componente de endereço. Veja a lista de tipos compatíveis.
    • long_name é a descrição de texto completa ou o nome do componente de endereço retornado pelo geocodificador.
    • short_name é um nome abreviado para o componente de endereço, se disponível. Por exemplo, um componente de endereço para o estado do Alasca pode ter um long_name de "quot;Alasca" e um short_name de "AK" usando a abreviação postal de duas letras.

    Observe os seguintes fatos sobre a matriz address_components[]:

    • A matriz de componentes de endereço pode conter mais componentes do que o formatted_address.
    • A matriz não inclui necessariamente todas as entidades políticas que contêm um endereço, além daquelas incluídas no formatted_address. Para recuperar todas as entidades políticas que contêm um endereço específico, use a geocodificação inversa, transmitindo a latitude/longitude do endereço como um parâmetro para a solicitação.
    • Não há garantia de que o formato da resposta permanecerá o mesmo entre as solicitações. Especificamente, o número de address_components varia de acordo com o endereço solicitado e pode mudar com o tempo para o mesmo endereço. Um componente pode mudar a posição na matriz. O tipo do componente pode mudar. Um componente específico pode estar ausente em uma resposta posterior.

    Veja abaixo mais informações sobre os tipos de endereço e os tipos de componentes de endereço.

  • partial_match indica que o geocodificador não retornou exatamente uma correspondência para a solicitação original, embora tenha sido capaz de corresponder parte do endereço solicitado. Examine a solicitação original para verificar erros ortográficos e/ou um endereço incompleto.

    As correspondências parciais ocorrem com mais frequência para endereços que não existem na localidade que você informa na solicitação. As correspondências parciais também podem ser retornadas quando uma solicitação corresponde a dois ou mais locais na mesma localidade. Por exemplo, "Hillpar St, Bristol, UK" retornará uma correspondência parcial para Henry Street e Henrietta Street. Se uma solicitação incluir um componente de endereço com ortografia incorreta, o serviço de geocodificação poderá sugerir um endereço alternativo. As sugestões acionadas dessa maneira também serão marcadas como uma correspondência parcial.

  • place_id é um identificador exclusivo de um lugar, que pode ser usado com outras APIs do Google. Por exemplo, você pode usar place_id com a biblioteca da API Google Places para ver detalhes de uma empresa local, como número de telefone, horário de funcionamento, avaliações de usuários e muito mais. Consulte a visão geral do ID de lugar.
  • postcode_localities[] é uma matriz que indica todas as localidades contidas em um código postal e está presente apenas quando o resultado é um código postal que contém várias localidades.
  • geometry contém as seguintes informações:

    • location contém o valor de latitude e longitude geocodificado. Retornamos esse local como um objeto LatLng, não como uma string formatada.
    • location_type armazena dados adicionais sobre o local especificado. No momento, os seguintes valores são aceitos:
      • ROOFTOP indica que o resultado retornado reflete um geocódigo preciso.
      • RANGE_INTERPOLATED indica que o resultado retornado reflete uma aproximação (geralmente em uma via) interpolada entre dois pontos precisos (como interseções). Os resultados intercalados geralmente são retornados quando os geocódigos telhado não estão disponíveis para um endereço.
      • GEOMETRIC_CENTER indica que o resultado retornado é o centro geométrico de um resultado, como uma polilinha (por exemplo, uma rua) ou polígono (região).
      • APPROXIMATE indica que o resultado retornado é aproximado.

    • viewport armazena a janela de visualização recomendada para o resultado retornado.
    • bounds (opcionalmente) armazena o LatLngBounds que pode conter totalmente o resultado retornado. Observe que esses valores podem não corresponder à porta de visualização recomendada. Por exemplo, São Francisco inclui as Ilhas Farallon, que tecnicamente fazem parte da cidade, mas não devem ser retornadas na janela de visualização.

Os endereços serão retornados pelo geocodificador usando a configuração de idioma preferido do navegador ou o idioma especificado ao carregar o JavaScript da API usando o parâmetro language. Para mais informações, consulte Localização.

Tipos de endereço e tipos de componentes de endereço

A matriz types[] em geocodificadorResult indica o tipo de endereço. A matriz types[] também pode ser retornada dentro de um geocodificadorAddressComponent para indicar o tipo do componente de endereço específico. Os endereços retornados pelo geocodificador podem ter vários tipos, que podem ser considerados tags. Por exemplo, muitas cidades são marcadas com os tipos political e locality.

Os geocodificadores a seguir são aceitos e retornados pelo geocodificador nos tipos de endereço e de componente de endereço:

  • street_address indica um endereço exato.
  • route indica um trajeto nomeado (como "US 101").
  • intersection indica um cruzamento importante, geralmente de duas estradas principais.
  • political indica uma entidade política. Normalmente, esse tipo indica um polígono de alguma administração civil.
  • country indica a entidade política nacional e normalmente é o tipo de ordem mais alta retornado pelo geocodificador.
  • administrative_area_level_1 indica uma entidade civil de primeira ordem abaixo do nível de país. Nos Estados Unidos, esses níveis administrativos são estados. Nem todas as nações exibem esses níveis administrativos. Na maioria dos casos, os nomes curtos de admin_area_level_1 corresponderão de perto às subdivisões da ISO 3166-2 e de outras listas amplamente circuladas. No entanto, isso não é garantido, já que nossos resultados de geocodificação são baseados em vários sinais e dados de local.
  • administrative_area_level_2 indica uma entidade civil de segunda ordem abaixo do nível de país. Nos Estados Unidos, esses níveis administrativos são condados. Nem todas as nações exibem esses níveis administrativos.
  • administrative_area_level_3 indica uma entidade civil de terceira ordem abaixo do nível de país. Esse tipo indica uma divisão civil secundária. Nem todos os países incluem esses níveis administrativos.
  • administrative_area_level_4 indica uma entidade civil de quarta ordem abaixo do nível de país. Esse tipo indica uma divisão civil secundária. Nem todos os países incluem esses níveis administrativos.
  • administrative_area_level_5 indica uma entidade civil de quinta ordem abaixo do nível de país. Esse tipo indica uma divisão civil secundária. Nem todos os países incluem esses níveis administrativos.
  • administrative_area_level_6 indica uma entidade civil de sexta ordem abaixo do nível de país. Esse tipo indica uma divisão civil secundária. Nem todos os países incluem esses níveis administrativos.
  • administrative_area_level_7 indica uma entidade civil de sétima ordem abaixo do nível de país. Esse tipo indica uma divisão civil secundária. Nem todos os países incluem esses níveis administrativos.
  • colloquial_area indica um nome alternativo usado com frequência para a entidade.
  • locality indica uma entidade política de cidade incorporada.
  • sublocality indica uma entidade civil de primeira ordem abaixo de uma localidade. Em alguns locais, é possível receber um dos tipos adicionais: sublocality_level_1 a sublocality_level_5. Cada nível de sublocalidade é uma entidade civil. Números maiores indicam uma área geográfica menor.
  • neighborhood indica um bairro nomeado.
  • premise indica um local nomeado, geralmente um edifício ou conjunto de edifícios com um nome comum.
  • subpremise indica uma entidade de primeira ordem abaixo de um local nomeado, normalmente um edifício dentro de um conjunto de edifícios com um nome comum
  • plus_code indica uma referência de local codificada, derivada de latitude e longitude. Os Plus Codes podem ser usados para substituir endereços em lugares que não existem, ou seja, quando os edifícios não estão numerados ou as ruas não têm nome. Consulte https://plus.codes para ver detalhes.
  • postal_code indica um código postal, conforme usado para atender aos correios no país.
  • natural_feature indica um recurso natural de destaque.
  • airport indica um aeroporto.
  • park indica um parque nomeado.
  • point_of_interest indica um ponto de interesse nomeado. Normalmente, esses pontos de interesse são entidades locais de destaque que não se encaixam facilmente em outra categoria, como o Edifício Estadual do Império e a Torre Eiffel.

Uma lista vazia de tipos indica que não há tipos conhecidos para o componente de endereço específico, por exemplo, Lieu-dit na França.

Além do indicado acima, os componentes de endereço podem incluir os tipos abaixo.

Observação:esta lista não está completa e está sujeita a alterações.

  • floor indica o andar de um endereço do edifício.
  • establishment geralmente indica um lugar que ainda não foi classificado.
  • landmark indica um lugar próximo que é usado como referência para ajudar na navegação.
  • point_of_interest indica um ponto de interesse nomeado.
  • parking indica um estacionamento ou uma estrutura de estacionamento.
  • post_box indica uma caixa postal específica.
  • postal_town indica um agrupamento de áreas geográficas, como locality e sublocality, usadas para endereços de correspondência em alguns países.
  • room indica a sala de um endereço de um edifício.
  • street_number indica o número exato da rua.
  • bus_station, train_station e transit_station indicam a localização de um ponto de ônibus, trem ou transporte público.

Códigos de status

O código status pode retornar um dos seguintes valores:

  • "OK" indica que não houve erros. O endereço foi analisado e pelo menos um geocódigo foi retornado.
  • "ZERO_RESULTS" indica que o geocódigo foi bem-sucedido, mas não retornou resultados. Isso pode ocorrer se o geocodificador recebeu uma address inexistente.
  • "OVER_QUERY_LIMIT" indica que você ultrapassou a sua cota.
  • "REQUEST_DENIED" indica que a solicitação foi negada. A página da Web não tem permissão para usar o geocodificador.
  • "INVALID_REQUEST" geralmente indica que a consulta (address, components ou latlng) está ausente.
  • "UNKNOWN_ERROR" indica que não foi possível processar a solicitação devido a um erro de servidor. A solicitação poderá ser bem-sucedida se você tentar novamente.
  • "ERROR" indica que a solicitação expirou ou houve um problema de contato com os servidores do Google. A solicitação poderá ser bem-sucedida se você tentar novamente.

Neste exemplo, geocodificamos um endereço e colocamos um marcador nos valores de latitude e longitude retornados. O gerenciador é transmitido como um literal de função anônima.

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

Veja um exemplo.

Direcionamento de porta de visualização

Você pode instruir o serviço de geocodificação a preferir resultados dentro de uma determinada janela de visualização (expressa como uma caixa delimitadora). Para fazer isso, defina o parâmetro bounds no literal de objeto GeocoderRequest para definir os limites dessa janela de visualização. A polarização prefere apenas os resultados dentro dos limites. Se os resultados mais relevantes existirem fora desses limites, eles poderão ser incluídos.

Por exemplo, um geocode para "Winnetka" geralmente retorna este bairro de Chicago:

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

No entanto, especificar um parâmetro bounds que defina uma caixa delimitadora para o Vale de San Fernando de Los Angeles resulta neste geocódigo, que retorna o bairro chamado "Winnetka" nesse local:

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"California",
    "short_name":"CA",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

Direcionamento de código da região

Você pode configurar o serviço Geocoding para retornar resultados polarizados para uma região específica usando explicitamente o parâmetro region. Esse parâmetro usa um código regional, especificado como uma subtag de região Unicode de dois caracteres (não numérico). Essas tags mapeiam diretamente valores de dois caracteres ccTLD conhecidos ("de nível superior"), como "uk" em "co.uk" por exemplo. Em alguns casos, a tag region também é compatível com códigos ISO-3166-1, que às vezes são diferentes dos valores de ccTLD ("GB" para "Reino Unido" por exemplo).

Ao usar o parâmetro region:

  • Especifique apenas um país ou região. Vários valores são ignorados e podem resultar em uma solicitação com falha.
  • Use apenas subtags de região de dois caracteres (formato CLDR Unicode). Todas as outras entradas resultarão em erros.
  • Somente os países e regiões listados nos detalhes da cobertura da Plataforma Google Maps são aceitos.

As solicitações de geocodificação podem ser enviadas para cada domínio em que o aplicativo principal do Google Maps oferece o recurso. A polarização prefere apenas resultados para um domínio específico. Se resultados mais relevantes existirem fora desse domínio, eles podem ser incluídos.

Por exemplo, um geocódigo para "quot;Toledo" retorna este resultado, porque o domínio padrão do serviço de geocodificação está definido como os Estados Unidos:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

Um geocódigo para "Toledo" com o campo region definido como 'es' (Espanha) retornará a cidade espanhola:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Toledo",
    "short_name":"TO",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

Filtragem de componentes

Você pode configurar o serviço de geocodificação para retornar resultados de endereços restritos a uma área específica, usando um filtro de componentes. Especifique o filtro no parâmetro componentRestrictions. Os valores de filtro são compatíveis com os mesmos métodos de correção ortográfica e correspondência parcial como outras solicitações de geocodificação.

O geocodificador retorna apenas os resultados que correspondem a todos os filtros do componente. Ou seja, ele avalia as especificações do filtro como AND, e não OR.

Um filtro de componentes consiste em um ou mais dos seguintes itens:

  • route corresponde ao nome longo ou curto de uma rota.
  • locality corresponde aos tipos de localidade e sub-região.
  • administrativeArea corresponde a todos os níveis da área político-administrativa.
  • postalCode corresponde a códigos postais e prefixos de códigos postais.
  • country corresponde ao nome de um país ou um código de país ISO 3166-1 de duas letras. Observação:a API segue o padrão ISO para definir países, e a filtragem funciona melhor ao usar o código ISO correspondente do país.

O exemplo a seguir demonstra o uso do parâmetro componentRestrictions para filtrar por country e postalCode:

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

Geocodificação inversa (busca de endereço)

O termo geocodificação geralmente se refere à tradução de um endereço legível para um local no mapa. O processo de conversão, ou seja, a tradução de um local no mapa em um endereço legível, é conhecida como geocodificação inversa.

Em vez de fornecer um address textual, forneça um par de latitude/longitude separado por vírgula no parâmetro location.

O exemplo a seguir geocodifica um valor de latitude/longitude e centraliza o mapa nesse local, mostrando uma janela de informações com o endereço formatado:

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.731, lng: -73.997 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodeLatLng(geocoder, map, infowindow);
    }
  );
}

function geocodeLatLng(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const input = (document.getElementById("latlng") as HTMLInputElement).value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.731, lng: -73.997 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  const input = document.getElementById("latlng").value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
Ver exemplo

Testar amostra

No exemplo anterior, mostramos o primeiro resultado selecionando results[0]. O geocodificador inverso geralmente retorna mais de um resultado. Os endereços geocodificados não são apenas endereços postais, mas qualquer maneira de nomear geograficamente um local. Por exemplo, ao geocodificar um ponto na cidade de Chicago, o ponto geocodificado pode ser rotulado como um endereço, como a cidade (Chicago), como o estado (Illinois) ou como um país (Estados Unidos). Todas essas opções são endereços para o geocodificador. O geocodificador inverso retorna todos esses resultados.

O geocodificador inverso corresponde a entidades políticas (países, províncias, cidades e bairros), endereços e códigos postais.

Veja um exemplo da lista de endereços que a consulta acima pode retornar:

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

Os endereços são retornados na ordem de correspondência, da melhor para a pior. Geralmente, o endereço mais exato é o resultado com mais destaque, como neste caso. Observe que retornamos diferentes tipos de endereço, desde o endereço mais específico a entidades políticas menos específicas, como bairros, cidades, municípios, estados etc. Para fazer a correspondência com um endereço mais geral, inspecione o campo results[].types.

Observação: a geocodificação inversa não é uma ciência exata. O geocodificador tentará encontrar o local endereçável mais próximo com uma certa tolerância.

Recuperar um endereço de um ID de lugar

Forneça um placeId para encontrar o endereço de um determinado ID de lugar. O ID do lugar é um identificador exclusivo que pode ser usado com outras APIs do Google. Por exemplo, você pode fornecer o placeId retornado pela API Roads para receber o endereço de um ponto alinhado. Para mais informações sobre IDs de lugar, consulte a visão geral deles.

Quando você fornece um placeId, a solicitação não pode conter nenhum dos seguintes campos:

  • address
  • latLng
  • location
  • componentRestrictions

O exemplo a seguir aceita um ID de lugar, encontra o endereço correspondente e centraliza o mapa nesse local. Ele também abre uma janela de informações mostrando o endereço formatado do lugar relevante:

TypeScript

// Initialize the map.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, map, infowindow);
    }
  );
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
Ver exemplo

Testar amostra