Serviço Geocoding

Visão geral

Geocodificação é o processo de converter endereços (como "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 inversa (pesquisa de endereço).

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

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

Começar

Antes de usar o serviço Geocoding na API Maps JavaScript, verifique se a API Geocoding está ativada no console do Google Cloud, no mesmo projeto configurado para a API Maps JavaScript.

Para saber quais são as APIs ativadas:

  1. Acesse o console do Google Cloud.
  2. Clique no botão Selecionar um projeto, escolha o que você configurou para a API Maps JavaScript e selecione Abrir.
  3. Na lista de APIs do Painel, procure API Geocoding.
  4. Se achar a API na lista, pode prosseguir. Caso contrário, faça o seguinte para ativar a API:
    1. Na parte de cima da página, selecione ATIVAR API para abrir a guia Biblioteca. Outra opção é selecionar Biblioteca no menu lateral esquerdo.
    2. Pesquise e selecione API Geocoding na lista de resultados.
    3. Clique em ATIVAR. Quando o processo terminar, a API Geocoding vai 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 uso entrou em vigor para o Maps, Routes e Places. Se quiser saber mais sobre os novos limites de preço e uso para utilização do serviço JavaScript Geocoding, consulte Uso e faturamento para a API Geocoding.

Políticas

O uso do serviço Geocoding precisa estar de acordo com as políticas da API Geocoding.

Solicitações do Geocoding

O acesso ao serviço Geocoding é assíncrono porque a API Google Maps precisa chamar um servidor externo. Por isso, você precisa transmitir um método de callback que vai ser executado quando a solicitação for concluída. 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 ao serviço de geocodificação, transmitindo um objeto literal GeocoderRequest que contém os termos de entrada e um método de callback para execução no recebimento da resposta.

O objeto literal GeocoderRequest contém os seguintes campos:

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

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

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

Parâmetros opcionais:

  • bounds: o LatLngBounds em que os resultados de geocódigo são direcionados de forma mais proeminente. O parâmetro bounds não restringe totalmente (apenas influencia) os resultados do geocodificador. Abaixo há mais informações sobre o direcionamento da janela de visualização.
  • componentRestrictions: usado para restringir os resultados a uma área específica. Saiba mais sobre a filtragem de componentes abaixo.
  • region: o código da região, especificado como uma subtag de região Unicode de dois caracteres (não numéricos). Na maioria dos casos, essas tags são convertidas diretamente nos valores usuais ccTLD ("domínio de nível superior") de dois caracteres. O parâmetro region não restringe totalmente, mas apenas influencia, os resultados do geocodificador. Saiba mais sobre direcionamento de código regional abaixo.
  • extraComputations: o único valor permitido para esse parâmetro é ADDRESS_DESCRIPTORS. Consulte descritores de endereço para mais detalhes.
  • fulfillOnZeroResults: cumpre a promessa em um status ZERO_RESULT na resposta. Isso pode ser necessário porque, mesmo sem resultados de geocodificação, ainda podem ser retornados outros campos de nível de resposta. Consulte Entregar sem resultados para mais detalhes.

Respostas do Geocoding

O serviço Geocoding requer um método de callback para execução na recuperação dos resultados do geocodificador. Esse callback precisa transmitir dois parâmetros para conter results e um código status, nessa ordem.

Resultados do Geocoding

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
 }
}

Esses campos são explicados a seguir:

  • 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 "Chicago" retorna "região", que indica que "Chicago" é uma cidade, e também retorna "político", indicando que é uma entidade política. Veja abaixo mais informações sobre os tipos de endereço e de componentes de endereço.
  • formatted_address é uma string que contém o endereço legível do local.

    Esse endereço costuma ser 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 "Avenida Paulista, 111, São Paulo, SP" consiste nos seguintes componentes: "Avenida Paulista" (o trajeto), "111" (o número), "São Paulo" (a cidade) e "SP" (o estado brasileiro).

    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 contendo os componentes separados aplicáveis a esse endereço.

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

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

    Observe os seguintes fatos sobre a matriz address_components[]:

    • A matriz de componentes de endereço pode conter mais componentes do que formatted_address.
    • A matriz não inclui necessariamente todas as entidades políticas que contêm um endereço, além daquelas incluídas em 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 vai 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 para o mesmo endereço. Um componente pode mudar a posição na matriz. O tipo do componente pode mudar. Pode faltar um componente específico em uma resposta posterior.

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

  • partial_match indica que o geocodificador não retornou uma correspondência exata para a solicitação original, mas conseguiu associar parte do endereço. Convém verificar se a solicitação original inclui erros de ortografia e/ou um endereço incompleto.

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

  • place_id é um identificador único de um local, 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 o panorama do ID de lugar.
  • postcode_localities[] é uma matriz que denota todas as localidades contidas em um código postal e está presente apenas quando o resultado é um código postal com várias localidades.

  • geometry contém as seguintes informações:

    • location contém o valor de latitude,longitude geocodificado. Retornamos esse local como um objeto LatLng, não como uma string formatada.
    • location_type armazena dados adicionais sobre o local especificado. 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 (normalmente em uma estrada) interpolada entre dois pontos precisos (como interseções). Resultados interpolados geralmente são retornados quando códigos geográficos de rooftop 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 um polígono (região).
      • APPROXIMATE indica que o resultado retornado é aproximado.

    • viewport armazena a janela de visualização recomendada para o resultado retornado.
    • bounds (retornado opcionalmente) armazena LatLngBounds, o que pode conter totalmente o resultado retornado. Talvez esses valores não correspondam à janela de visualização recomendada. Por exemplo, São Francisco inclui as Ilhas Farallon, que tecnicamente são parte da cidade, mas não precisam ser retornados na janela de informações.

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

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

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

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

  • street_address indica um endereço preciso.
  • route indica uma rota nomeada (como "US 101").
  • intersection indica uma interseção principal, normalmente de duas estradas principais.
  • political indica uma entidade política. Normalmente, esse tipo indica um polígono de administração civil.
  • country indica a entidade política nacional e costuma ser o tipo de ordem mais elevada retornado pelo geocodificador.
  • administrative_area_level_1 indica uma entidade civil de primeira ordem abaixo do nível do país. Nos Estados Unidos, esses níveis administrativos são os estados. Nem todos os países têm esses níveis administrativos. Na maioria dos casos, nomes curtos para administrative_area_level_1 vão respeitar quase que totalmente as subdivisões da ISO 3166-2 e outras normas amplamente divulgadas. Porém, isso não é garantido, já que os resultados da nossa geocodificação se baseiam em vários sinais e dados de localização.
  • 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 os condados. Nem todos os países têm 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 do 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 do 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 do 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 comumente para a entidade.
  • locality indica uma entidade política de cidade ou município incorporada.
  • sublocality indica uma entidade civil de primeira ordem abaixo da localidade. Para alguns locais, é possível receber um dos tipos adicionais: sublocality_level_1 até 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 um conjunto de edifícios com um nome em comum.
  • subpremise indica uma entidade endereçável abaixo do nível da instalação, como um apartamento, uma unidade ou uma suíte.
  • plus_code indica uma referência de local codificada, derivada de latitude e longitude. Os Plus Codes podem ser usados em vez de endereços nos lugares em que não existem, ou seja, quando os imóveis não estão numerados ou as ruas não têm nome. Para mais detalhes, consulte https://plus.codes.
  • postal_code indica um código postal, conforme usado para endereçar correspondências 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 "PDIs" são entidades locais de destaque que não se encaixam facilmente em outra categoria, como "Empire State Building" ou "Torre Eiffel".

Uma lista vazia indica que não há tipos conhecidos para um 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: essa lista não é completa e está sujeita a mudanças.

  • floor indica o andar de um edifício.
  • establishment geralmente indica um lugar que ainda não foi classificado.
  • landmark indica um lugar por perto 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 desse tipo.
  • 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 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 nenhum erro ocorreu; o endereço foi analisado e, pelo menos, um geocódigo foi retornado.
  • "ZERO_RESULTS" indica que o geocódigo deu certo, mas não retornou resultados. Isso pode ocorrer se o geocodificador recebeu um address inexistente.
  • "OVER_QUERY_LIMIT" indica que você ultrapassou sua cota.
  • "REQUEST_DENIED" indica que o pedido foi recusado. A página da Web não tem permissão para usar o geocodificador.
  • "INVALID_REQUEST" normalmente indica que está faltando a consulta (address, components ou latlng).
  • "UNKNOWN_ERROR" indica que a solicitação não foi processada devido a um erro de servidor. Se você tentar novamente, a solicitação pode dar certo.
  • "ERROR" indica que a solicitação expirou ou houve um problema de contato com os servidores do Google. Se você tentar novamente, a solicitação pode dar certo.

Nesse exemplo, geocodificamos um endereço e colocamos um marcador nos valores retornados de latitude e longitude. O manipulador é passado como um literal de função anônimo.

  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>

Exemplo

Direcionamento de porta de visualização

É possível instruir o serviço Geocoding a dar preferência a resultados em uma determinada porta de visualização (expressa como uma caixa delimitadora). Para isso, configure o parâmetro bounds no literal do objeto GeocoderRequest para definir os limites dessa janela de visualização. O direcionamento somente prioriza resultados dentro dos limites. Resultados mais relevantes fora desses limites podem ser incluídos.

Por exemplo, um geocódigo para "Winnetka" geralmente retorna este subúrbio 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"
}

Entretanto, a adição de um parâmetro bounds definindo uma caixa delimitadora para San Fernando Valley em Los Angeles traz um bairro chamado "Winnetka" nessa localização:

{
  "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 regional

Também é possível configurar o serviço Geocoding para trazer resultados direcionados a 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éricos). Essas tags são mapeadas diretamente para valores de dois caracteres de ccTLD familiares ("domínio de nível superior") como "uk" em "co.uk", por exemplo. Em alguns casos, a tag region também aceita códigos ISO-3166-1, que, às vezes, diferem dos valores de ccTLD ("GB" para "Grã-Bretanha", por exemplo).

Quando 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 vão resultar 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 qualquer domínio no qual o aplicativo principal do Google Maps ofereça geocodificação. O direcionamento só prioriza resultados de um domínio específico. Resultados mais relevantes fora desse domínio podem ser incluídos.

Por exemplo, um geocódigo para "Toledo" retorna esse resultado porque o domínio padrão do serviço Geocoding é definido como 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) retorna 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

É possível configurar o serviço Geocoding para retornar resultados de endereço 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 de outras solicitações de geocodificação.

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

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 "localidade" e "sublocalidade"
  • 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 a um nome de país ou um código de país ISO 3166-1 de duas letras. Observação: a API segue a norma ISO para definir países, e a filtragem funciona melhor quando utiliza o respectivo código ISO 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);
  }
});
}

Fulfill on Zero Results

Para a geocodificação reversa, a promessa é quebrada em status=ZERO_RESULTS por padrão. No entanto, os campos adicionais de nível de resposta de plus_code e address_descriptor ainda podem ser preenchidos nesse caso. Se "true" for fornecido para o parâmetro fulfillOnZeroResults, a promessa não será quebrada e esses campos adicionais serão acessíveis pela promessa, se presentes.

Confira a seguir um exemplo desse comportamento para uma latitude/longitude na Antártida. Mesmo que não haja resultados de geocodificação reversa, ainda podemos imprimir o código Plus na promessa se definirmos fulfillOnZeroResults=true. 

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(-75.290330, 38.653861);
      geocoder
        .geocode({
          'location': latlng,
          'fulfillOnZeroResults': true,
        })
        .then((response) => {
          console.log(response.plus_code);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

Descritores de endereço

Os descritores de endereço incluem informações adicionais que ajudam a descrever um local usando pontos de referência e áreas. Confira a demonstração dos descritores de endereço para conhecer o recurso.

Os descritores de endereço podem ser ativados usando o parâmetro extraComputations. Inclua extra_computations=ADDRESS_DESCRIPTORS em uma solicitação de geocodificação, solicitação de geocodificação reversa ou solicitação de geocodificação do Places para receber descritores de endereço na resposta.

Exemplo de geocodificação de lugares

A consulta a seguir contém o endereço de um lugar em Delhi.

function addressDescriptorPlaceIdLookup() {
  geocoder.geocode({ 
    'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q',
    'extraComputations': ['ADDRESS_DESCRIPTORS']
    }, function(results, status) {
    if (status == 'OK') {
      console.log(results[0].address_descriptor);
    } else {
      window.alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

Exemplo de geocodificação inversa

A consulta a seguir contém o valor de latitude/longitude de um local em Delhi.

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(28.640964,77.235875);
      geocoder
        .geocode({
          'location': latlng,
          'extraComputations': ["ADDRESS_DESCRIPTORS"],
        })
        .then((response) => {
          console.log(response.address_descriptor);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

Exemplo de descritor de endereço

Confira um exemplo de address_descriptor.

  {
    "address_descriptor" : {
       "areas" : [
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Turkman Gate"
             },
             "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
          },
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Chandni Chowk"
             },
             "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
          },
          {
             "containment" : "NEAR",
             "display_name" : {
                "language_code" : "en",
                "text" : "Katar Ganj"
             },
             "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
          }
       ],
       "landmarks" : [
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delite Cinema"
             },
             "straight_line_distance_meters" : 29.9306755065918,
             "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
             "travel_distance_meters" : 418.7794799804688,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "establishment", "movie_theater", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "YES Bank"
             },
             "straight_line_distance_meters" : 66.83731079101562,
             "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
             "travel_distance_meters" : 489.0340270996094,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "UCO Bank"
             },
             "straight_line_distance_meters" : 25.38849639892578,
             "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
             "travel_distance_meters" : 403.2246398925781,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delhi By Cycle Meeting Point"
             },
             "straight_line_distance_meters" : 44.02867126464844,
             "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
             "travel_distance_meters" : 97.41281890869141,
             "spatial_relationship" : "AROUND_THE_CORNER",
             "types" : [
                "establishment",
                "point_of_interest",
                "tourist_attraction",
                "travel_agency"
             ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Axis Bank Branch"
             },
             "straight_line_distance_meters" : 102.3495178222656,
             "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
             "travel_distance_meters" : 330.8566284179688,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          }
       ]
    }
  }

Há duas matrizes em cada objeto address_descriptor: landmarks e areas. A matriz landmarks contém até cinco resultados classificados em ordem de relevância, considerando a proximidade da coordenada solicitada, a prevalência do marco e a visibilidade dele. Cada resultado de marco contém os seguintes valores:

  • place_id é o ID do lugar do resultado dos pontos de referência. Consulte a visão geral do ID de lugar.
  • display_name é o nome de exibição do marco e contém language_code e text.
  • straight_line_distance_meters é a distância entre os pontos em metros entre a coordenada de entrada e o resultado dos pontos de referência.
  • travel_distance_meters é a distância em metros percorrida pela rede rodoviária (ignorando restrições de vias) entre a coordenada de entrada e o resultado dos marcos.
  • spatial_relationship é a relação estimada entre a coordenada de entrada e o resultado dos marcos:
    • "NEAR" é a relação padrão quando nenhuma das opções a seguir se aplica.
    • "WITHIN" quando a coordenada de entrada está contida nos limites da estrutura associada ao marco.
    • "BESIDE" quando a coordenada de entrada é adjacente ao ponto de acesso ou ao marco.
    • "ACROSS_THE_ROAD" quando a coordenada de entrada está diretamente oposta ao marco no outro lado do trajeto.
    • "DOWN_THE_ROAD" quando a coordenada de entrada está na mesma rota que o marco, mas não "BESIDES" ou "ACROSS_THE_ROAD".
    • "AROUND_THE_CORNER" quando a coordenada de entrada está em uma rota perpendicular ao marco (restrita a uma única curva).
    • "BEHIND" quando a coordenada de entrada está espacialmente próxima ao ponto de referência, mas longe do ponto de acesso.
  • types são os tipos de lugar do ponto de referência.

O objeto areas contém até três respostas e se limita a lugares que representam pequenas regiões, como bairros, sublocalidades e grandes complexos. As áreas que contêm a coordenada solicitada são listadas primeiro e ordenadas da menor para a maior. Cada resultado areas contém os seguintes valores:

  • place_id é o ID do lugar do resultado das áreas. Consulte a visão geral do ID de lugar.
  • display_name é o nome de exibição da área e contém language_code e text.
  • containment é a relação de contenção estimada entre a coordenada de entrada e o resultado das áreas:
    • "NEAR" é a relação padrão quando nenhuma das opções a seguir se aplica.
    • "WITHIN" quando a coordenada de entrada está próxima ao centro da área.
    • "OUTSKIRTS" quando a coordenada de entrada está próxima à borda da área.

Cobertura do descritor de endereço

Esse recurso está disponível apenas em alguns países.

Este é um recurso em fase de pré-lançamento, e gostaríamos de receber seu feedback. Envie um e-mail para address-descriptors-feedback@google.com.

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

O termo geocodificação geralmente se refere à conversão de um endereço legível em uma localização em um mapa. O processo inverso, ou seja, converter uma localização no mapa em um endereço legível, é conhecido como geocodificação inversa.

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

O exemplo a seguir geocodifica um valor de latitude/longitude e centraliza o mapa nessa localização, 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;
index.ts

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;
index.js
Exemplo

Testar amostra

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

Ele pode corresponder 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 mais proeminente, como neste caso. Retornamos diferentes tipos de endereços, desde o endereço mais específico até entidades políticas menos específicas, como bairros, cidades, municípios, estados, entre outros. Para associar um endereço mais geral, analise o campo results[].types.

Observação: a geocodificação reversa não é uma ciência exata. O geocodificador tenta encontrar a localização endereçável mais próxima dentro de uma determinada tolerância.

Recuperar o endereço de um ID de lugar

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

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 local, encontra o endereço correspondente e centraliza o mapa nesse local. Além disso, ele mostra uma janela de informações com o endereço formatado do local 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;
index.ts

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;
index.js
Exemplo

Testar amostra

JSFiddle.net (link em inglês) Google Cloud Shell