Servicio de geocodificación

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Descripción general

La codificación geográfica es el proceso que convierte direcciones (como "1600 Amphitheatre Parkway, Mountain View, CA&quot) en coordenadas geográficas (como latitud 37,423021 y longitud -122,083739) que puedes usar para colocar marcadores o posicionar el mapa.

La geocodificación inversa es el proceso de conversión de coordenadas geográficas en direcciones en lenguaje natural (consulta Geocodificación inversa (búsqueda de direcciones)).

También puedes usar el geocodificador para buscar la dirección de un ID de lugar específico.

La API de Maps JavaScript proporciona una clase Geocoder para realizar la codificación geográfica y la codificación geográfica inversa de forma dinámica a partir de las entradas del usuario. En cambio, si deseas geocodificar direcciones conocidas y estáticas, consulta el servicio web de geocodificación.

Cómo comenzar

Antes de usar el servicio de Geocoding en la API de Maps JavaScript, asegúrate de que esté habilitada en Google Cloud Console, en el mismo proyecto que configuraste para la API de Maps JavaScript.

Para ver tu lista de API habilitadas:

  1. Ve a Google Cloud Console.
  2. Haz clic en el botón Seleccionar un proyecto, selecciona el mismo proyecto que configuraste para la API de Maps JavaScript y haz clic en Abrir.
  3. En la lista de API del Panel, busca API de Geocoding.
  4. Si ves la API en la lista, no necesitas hacer nada más. Si la API no está en la lista, habilítala:
    1. En la parte superior de la página, selecciona HABILITAR API para mostrar la pestaña Biblioteca. Como alternativa, en el menú lateral izquierdo, selecciona Biblioteca.
    2. Busca Geocoding API y selecciónala en la lista de resultados.
    3. Selecciona HABILITAR. Cuando finalice el proceso, la API de Geocoding aparecerá en la lista de API del Panel.

Precios y políticas

Precios

El 16 de julio de 2018, entró en vigencia un nuevo plan de precios prepagos para Maps, Routes y Places. Para obtener más información sobre los nuevos precios y límites de uso del servicio de geocodificación de JavaScript, consulta Uso y facturación para la API de Geocoding.

Límites de frecuencia

Ten en cuenta lo siguiente sobre los límites de frecuencia para las solicitudes adicionales:

El límite de frecuencia adicional se aplica por sesión de usuario, independientemente de la cantidad de usuarios que compartan el mismo proyecto. Cuando cargas la API por primera vez, se te asigna una cuota inicial de solicitudes. Una vez que usas esta cuota, la API aplica límites de frecuencia sobre las solicitudes adicionales por segundo. Si se realizan demasiadas solicitudes en un período determinado, la API muestra un código de respuesta OVER_QUERY_LIMIT.

El límite de frecuencia por sesión evita el uso de servicios del cliente para solicitudes por lotes, como la codificación geográfica por lotes. Para solicitudes por lotes, usa el servicio web de la API de Geocoding.

Políticas

El uso del servicio de geocodificación debe cumplir con las políticas que se describen para la API de Geocoding.

Solicitudes de geocodificación

El acceso al servicio de geocodificación es asincrónico, ya que la Google Maps API debe realizar una llamada a un servidor externo. Por esa razón, debes pasar un método de callback para la ejecución al completarse la solicitud. Este método de devolución de llamada procesa los resultados. Ten en cuenta que el geocodificador puede devolver más de un resultado.

Puedes acceder al servicio de codificación geográfica de la API de Google Maps en tu código mediante el objeto constructor google.maps.Geocoder. El método Geocoder.geocode() inicia una solicitud al servicio de geocodificación y le pasa un literal de objeto GeocoderRequest que contiene los términos de entrada y un método de devolución de llamada para ejecutar al recibir la respuesta.

El literal de objeto GeocoderRequest contiene los siguientes campos:

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

Parámetros obligatorios: Debes proporcionar solo uno de los siguientes campos:

  • address: la dirección que deseas codificar geográficamente.
    o
    location: La LatLng (o LatLngLiteral) para la que deseas obtener la dirección más cercana en lenguaje natural. El geocodificador aplica un geocódigo inverso. Consulta Geocodificación inversa para obtener más información.
    o
    placeId: El ID de lugar del lugar para el que deseas obtener la dirección más cercana en lenguaje natural. Obtén más información sobre cómo recuperar una dirección para un ID de lugar.

Parámetros opcionales:

  • bounds: Es el objeto LatLngBounds dentro del que se pueden restringir los resultados de codificación geográfica de forma más destacada. El parámetro bounds solo influirá, no restringirá por completo, los resultados del geocodificador. A continuación, puedes obtener más información sobre la personalización de viewports.
  • componentRestrictions: Se usa para restringir los resultados a un área específica. Obtén más información sobre el filtrado de componentes a continuación.
  • region: Es el código de región, especificado como una subetiqueta de la región Unicode de dos caracteres (no numérica). En la mayoría de los casos, estas etiquetas se asignan directamente a valores de ccTLD conocidos (dominios de nivel superior). El parámetro region solo influirá, no restringirá por completo, los resultados del geocodificador. Obtén más información sobre la personalización del código regional a continuación.

Respuestas de geocodificación

El servicio de geocodificación requiere que se ejecute un método de devolución de llamada al momento de recuperar los resultados del geocodificador. Esta devolución de llamada debe pasar dos parámetros para contener el código results y status, en ese orden.

Resultados de geocodificación

El objeto GeocoderResult representa un solo resultado de geocodificación. Una solicitud de geocódigo puede devolver varios objetos de resultados:

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

Estos campos se explican a continuación:

  • types[] es un arreglo que indica el tipo de dirección del resultado que se muestra. Este arreglo contiene un conjunto de cero o más etiquetas que identifican el tipo de función que se muestra en el resultado. Por ejemplo, un geocódigo de “Chicago” muestra “localidad” que indica que “Chicago” es una ciudad y también muestra “político” que indica que es una entidad política. Consulta más información sobre los tipos de dirección y los tipos de componentes de dirección a continuación.
  • formatted_address es una string que contiene la dirección legible de esta ubicación.

    A menudo, esta dirección es equivalente a la dirección postal. Ten en cuenta que algunos países, como el Reino Unido, no permiten la distribución de direcciones postales verdaderas debido a restricciones de licencias.

    La dirección con formato se compone de manera lógica de uno o más componentes de dirección. Por ejemplo, la dirección "111 8th Avenue, Nueva York, NY" consta de los siguientes componentes: "111" (el número de calle), "8th Avenue" (la ruta), "New York" (la ciudad) y "NY" (el estado de los EE. UU.).

    No analices la dirección con formato de manera programática. En su lugar, debes usar los componentes de dirección individuales, que la respuesta de la API incluye, además del campo de dirección con formato.

  • address_components[] es un arreglo que contiene los componentes independientes aplicables a esta dirección.

    Por lo general, cada componente de dirección contiene los siguientes campos:

    • types[] es un arreglo que indica el tipo de componente de la dirección. Consulta la lista de tipos admitidos.
    • long_name es la descripción de texto completa o el nombre del componente de la dirección que muestra el codificador geográfico.
    • short_name es un nombre textual abreviado para el componente de dirección, si está disponible. Por ejemplo, un componente de dirección para el estado de Alaska puede tener un long_name de Alaska y un short_name de "AK" con la abreviatura postal de dos letras.

    Ten en cuenta los siguientes datos sobre el arreglo address_components[]:

    • El arreglo de componentes de dirección puede contener más componentes que formatted_address.
    • El arreglo no necesariamente incluye todas las entidades políticas que contienen una dirección, además de las incluidas en el formatted_address. Para recuperar todas las entidades políticas que contienen una dirección específica, debes usar la codificación geográfica inversa y pasar la latitud y longitud de la dirección como parámetro a la solicitud.
    • No se garantiza que el formato de la respuesta siga siendo el mismo entre solicitudes. En particular, la cantidad de address_components varía según la dirección solicitada y puede cambiar con el tiempo para la misma dirección. Un componente puede cambiar la posición en el arreglo. El tipo de componente puede cambiar. Es posible que falte un componente en particular en una respuesta posterior.

    Consulta más información sobre los tipos de dirección y los tipos de componentes de dirección a continuación.

  • partial_match indica que el geocodificador no mostró una coincidencia exacta para la solicitud original, aunque sí pudo hacer coincidir parte de la dirección solicitada. Te recomendamos examinar la solicitud original en busca de errores ortográficos o una dirección incompleta.

    Las coincidencias parciales con mayor frecuencia ocurren para las direcciones que no existen dentro de la localidad que pasas en la solicitud. Las coincidencias parciales también se pueden mostrar cuando una solicitud coincide con dos o más ubicaciones en la misma localidad. Por ejemplo, "Hillpar St., Bristol, Reino Unido" mostrará una coincidencia parcial para Henry Street y Henrietta Street. Ten en cuenta que si una solicitud incluye un componente de dirección mal escrito, el servicio de geocodificación puede sugerir una dirección alternativa. Las sugerencias activadas de esta manera también se marcarán como una coincidencia parcial.

  • place_id es un identificador único de un lugar, que se puede usar con otras API de Google. Por ejemplo, puedes usar place_id con la biblioteca de la API de Google Places para obtener detalles de una empresa local, como el número de teléfono, el horario de atención, las opiniones de usuarios y mucho más. Consulta la descripción general del ID de lugar.
  • postcode_localities[] es un arreglo que denota todas las localidades que contiene un código postal y solo está presente cuando el resultado es un código postal que contiene varias localidades.
  • geometry contiene la siguiente información:

    • location contiene el valor de latitud y longitud geocodificado. Ten en cuenta que mostramos esta ubicación como un objeto LatLng, no como una string con formato.
    • location_type almacena datos adicionales sobre la ubicación especificada. Actualmente, se admiten los siguientes valores:
      • ROOFTOP indica que el resultado que se muestra refleja un geocódigo preciso.
      • RANGE_INTERPOLATED indica que el resultado que se muestra refleja una aproximación (generalmente en una ruta) interpolada entre dos puntos precisos (como intersecciones). Los resultados interpolados generalmente se muestran cuando los códigos geográficos del techo no están disponibles para una dirección.
      • GEOMETRIC_CENTER indica que el resultado que se muestra es el centro geométrico de un resultado, como una polilínea (por ejemplo, una calle) o un polígono (región).
      • APPROXIMATE indica que el resultado que se muestra es aproximado.

    • viewport almacena el viewport recomendado para el resultado que se muestra.
    • bounds (opcional) muestra el LatLngBounds que puede contener por completo el resultado mostrado. Ten en cuenta que probablemente estos límites no coincidan con el viewport recomendado. (Por ejemplo, San Francisco incluye las Islas Farallón, que técnicamente son parte de la ciudad, pero no se deben mostrar en el viewport).

El geocodificador devolverá las direcciones con la configuración de idioma preferida del navegador o el idioma especificado cuando se cargue el código JavaScript de la API con el parámetro language. (Para obtener más información, consulta Localización).

Tipos de dirección y tipos de componentes de dirección

El arreglo types[] en el GeocoderResult indica el tipo de dirección. El arreglo types[] también se puede mostrar dentro de un GeocoderAddressComponent para indicar el tipo del componente de dirección en particular. Las direcciones que muestra el geocodificador pueden tener varios tipos, y estos pueden considerarse etiquetas. Por ejemplo, muchas ciudades se etiquetan con el tipo political y locality.

El geocodificador admite y muestra los siguientes tipos en los tipos de dirección y en los de componente de dirección:

  • street_address indica una dirección precisa.
  • route indica una ruta con nombre (como &US 101).
  • intersection indica una intersección principal, generalmente de dos rutas principales.
  • political indica una entidad política. Por lo general, este tipo indica un polígono de alguna administración civil.
  • country indica la entidad política nacional y, por lo general, es el tipo de orden más alto que muestra el geocodificador.
  • administrative_area_level_1 indica una entidad civil de primer orden por debajo del nivel de país. En Estados Unidos, estos niveles administrativos son estados. No todas las naciones tienen estos niveles administrativos. En la mayoría de los casos, los nombres cortos de management_area_level_1 coincidirán estrechamente con las subdivisiones de ISO 3166-2 y otras listas ampliamente distribuidas; sin embargo, esto no está garantizado, ya que nuestros resultados de codificación geográfica se basan en diversos indicadores y datos de ubicación.
  • administrative_area_level_2 indica una entidad civil de segundo orden por debajo del nivel de país. En Estados Unidos, estos niveles administrativos son condados. No todas las naciones tienen estos niveles administrativos.
  • administrative_area_level_3 indica una entidad civil de tercer orden por debajo del nivel de país. Este tipo indica una división civil inferior. No todos los países poseen estos niveles administrativos.
  • administrative_area_level_4 indica una entidad civil de cuarto orden por debajo del nivel de país. Este tipo indica una división civil inferior. No todos los países poseen estos niveles administrativos.
  • administrative_area_level_5 indica una entidad civil de quinto orden por debajo del nivel de país. Este tipo indica una división civil inferior. No todos los países poseen estos niveles administrativos.
  • administrative_area_level_6 indica una entidad civil de sexto orden por debajo del nivel de país. Este tipo indica una división civil inferior. No todos los países poseen estos niveles administrativos.
  • administrative_area_level_7 indica una entidad civil de séptimo orden por debajo del nivel de país. Este tipo indica una división civil inferior. No todos los países poseen estos niveles administrativos.
  • colloquial_area indica un nombre alternativo de uso común para la entidad.
  • locality indica una entidad política constituida de una ciudad o un pueblo.
  • sublocality indica una entidad civil de primer orden por debajo de una localidad. Algunas ubicaciones pueden recibir uno de los tipos adicionales: sublocality_level_1 a sublocality_level_5. Cada nivel de sublocalidad es una entidad civil. Los números más altos indican un área geográfica más pequeña.
  • neighborhood indica un barrio con nombre.
  • premise indica una ubicación con nombre, que por lo general es un edificio o una colección de edificios con un nombre común.
  • subpremise indica una entidad de primer orden debajo de una ubicación determinada, que suele ser un edificio singular dentro de un conjunto de edificios con un nombre común.
  • plus_code indica una referencia de ubicación codificada, derivada de latitud y longitud. Los Plus Codes se pueden usar como reemplazo de las direcciones en lugares donde no existen (donde los edificios no están numerados o las calles no tienen nombre). Consulta https://plus.codes para obtener más información.
  • postal_code indica un código postal que se usa para dirigirse al correo postal dentro del país.
  • natural_feature indica un rasgo natural destacado.
  • airport indica un aeropuerto.
  • park indica un parque con nombre.
  • point_of_interest indica un lugar de interés con nombre. Por lo general, estos lugares de interés son entidades locales destacadas que no encajan con facilidad en otra categoría, como “Empire State Building” o “Torre Eiffel”.

Una lista vacía de tipos indica que no hay tipos conocidos para el componente de dirección en particular, por ejemplo, Lieu-dit en Francia.

Además de lo dicho antes, los componentes de dirección pueden incluir los siguientes tipos.

Nota: Esta lista no es exhaustiva y está sujeta a cambios.

  • floor indica el piso de la dirección de un edificio.
  • establishment suele indicar un lugar que aún no se categorizó.
  • landmark indica un lugar cercano que se usa como referencia para facilitar la navegación.
  • point_of_interest indica un lugar de interés con nombre.
  • parking indica un estacionamiento o una estructura de estacionamiento.
  • post_box indica un cuadro postal específico.
  • postal_town indica un grupo de áreas geográficas, como locality y sublocality, que se usa para las direcciones de correo postal en algunos países.
  • room indica la sala de la dirección de un edificio.
  • street_number indica el número exacto de una calle.
  • bus_station, train_station y transit_station indican la ubicación de una parada de autobús, tren o transporte público.

Códigos de estado

El código status puede mostrar uno de los siguientes valores:

  • "OK" indica que no se produjeron errores, que la dirección se analizó correctamente y que se mostró al menos un geocódigo.
  • "ZERO_RESULTS" indica que el geocódigo se realizó correctamente, pero no mostró resultados. Esto puede ocurrir si se pasa un valor address inexistente al geocodificador.
  • "OVER_QUERY_LIMIT" indica que superaste tu cuota.
  • "REQUEST_DENIED" indica que se rechazó tu solicitud. La página web no puede usar el geocodificador.
  • "INVALID_REQUEST" suele indicar que falta la consulta (address, components o latlng).
  • "UNKNOWN_ERROR" indica que no se pudo procesar la solicitud debido a un error del servidor. La solicitud puede tener éxito si vuelves a intentarlo.
  • "ERROR" indica que se agotó el tiempo de espera de la solicitud o que se produjo un problema al comunicarse con los servidores de Google. La solicitud puede tener éxito si vuelves a intentarlo.

En este ejemplo, geocodificamos una dirección y colocamos un marcador en los valores de latitud y longitud que se muestran. Ten en cuenta que el controlador se pasa como un literal de función 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>

Ver el ejemplo

Restricción de viewports

Puedes indicar al servicio de geocodificación que prefiera resultados dentro de un viewport determinado (expresado como un cuadro de límite). Para ello, configura el parámetro bounds dentro del literal de objeto GeocoderRequest a fin de definir los límites de este viewport. Ten en cuenta que la personalización solo prefiere los resultados dentro de los límites; si hay resultados más relevantes fuera de estos límites, se pueden incluir.

Por ejemplo, un geocódigo para "Winnetka" generalmente devuelve este suburbio 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"
}

Sin embargo, la especificación de un parámetro bounds que define un cuadro de límite para el Valle de San Fernando en Los Ángeles da como resultado este geocódigo que muestra el barrio llamado "Winnetka" en esa ubicación:

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

Restricción de códigos por región

Puedes configurar el servicio de geocodificación para que muestre resultados restringidos a una región en particular con el parámetro region. Este parámetro toma un código de región, especificado como una subetiqueta de región Unicode de dos caracteres (no numérica). Estas etiquetas se asignan directamente a valores de ccTLD (dominio de nivel superior) conocidos de dos caracteres, como &uk;por ejemplo, en &co.uk. En algunos casos, la etiqueta region también admite códigos ISO-3166-1, que a veces difieren de los valores ccTLD (por ejemplo, “Gran Bretaña”).

Cuando uses el parámetro region, sucederá lo siguiente:

  • Especifica solo un país o una región. Se ignoran varios valores y podrían dar como resultado una solicitud con errores.
  • Use solo subetiquetas de región de dos caracteres (formato CLDR de Unicode). Todas las demás entradas generarán errores.
  • Solo se admiten los países y las regiones que figuran en los Detalles de cobertura de Google Maps Platform.

Se pueden enviar solicitudes de geocodificación para cada dominio en el que la aplicación principal de Google Maps ofrezca geocodificación. Ten en cuenta que la personalización solo prefiere los resultados para un dominio específico. Si hay resultados más relevantes fuera de este dominio, se pueden incluir.

Por ejemplo, un geocódigo para &Totodo muestra este resultado, ya que el dominio predeterminado para el Servicio de geocodificación se establece en 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"
}

Un geocódigo para &Totdo; con el campo region configurado en 'es' (España) mostrará la ciudad española:

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

Filtrado de componentes

Puedes configurar el servicio de geocodificación para que muestre resultados de direcciones restringidos a un área específica con un filtro de componentes. Especifica el filtro en el parámetro componentRestrictions. Los valores de filtro admiten los mismos métodos de corrección ortográfica y coincidencia parcial que otras solicitudes de codificación geográfica.

El geocodificador muestra solo los resultados que coinciden con todos los filtros de componentes. Es decir, evalúa las especificaciones del filtro como un Y, no como un OR.

Un filtro de componentes consta de uno o más de los siguientes elementos:

  • route coincide con el nombre largo o corto de una ruta.
  • locality coincide con los tipos de localidad y sublocalidad.
  • administrativeArea coincide con todos los niveles del área administrativa.
  • postalCode coincide con los códigos postales y los prefijos de códigos postales.
  • country coincide con un nombre de país o con un código de país ISO 3166-1 de dos letras. Nota: La API sigue el estándar ISO para definir países, y el filtrado funciona mejor cuando se usa el código ISO correspondiente del país.

En el siguiente ejemplo, se muestra cómo usar el parámetro componentRestrictions para filtrar por country y 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);
  }
});
}

Geocodificación inversa (búsqueda de direcciones)

Por lo general, el término codificación geográfica hace referencia a la traducción de una dirección en lenguaje natural en una ubicación de un mapa. El proceso de hacer lo inverso, de convertir una ubicación en el mapa en una dirección en lenguaje natural, se conoce como codificación geográfica inversa.

En lugar de proporcionar un address textual, proporciona un par de latitud/longitud separado por comas en el parámetro location.

En el siguiente ejemplo, se geocodifica un valor de latitud/longitud y se centra el mapa en esa ubicación, lo que abre una ventana de información con la dirección con formato:

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 ejemplo

Probar la muestra

Ten en cuenta que, en el ejemplo anterior, mostramos el primer resultado seleccionando results[0]. El geocodificador inverso a menudo muestra más de un resultado. Las direcciones codificadas geográficamente no son solo direcciones postales, sino cualquier forma de asignar un nombre geográfico a una ubicación. Por ejemplo, cuando codificas geográficamente un punto en la ciudad de Chicago, el punto geocodificado puede etiquetarse como una dirección, como la ciudad (Chicago), como su estado (Illinois) o como un país (Estados Unidos). Todas las direcciones corresponden al geocodificador. El geocodificador inverso devuelve todos estos resultados.

El geocodificador inverso establece coincidencias con entidades políticas (países, provincias, ciudades y barrios), direcciones y códigos postales.

A continuación, te mostramos un ejemplo de la lista de direcciones que puede mostrar la consulta anterior:

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"

Las direcciones se devuelven en el orden de mayor a menor coincidencia. En general, la dirección más exacta es el resultado más importante, como en este caso. Ten en cuenta que mostramos diferentes tipos de direcciones, desde la dirección más específica hasta entidades políticas menos específicas, como barrios, ciudades, condados, estados, etc. Si deseas hacer coincidir una dirección más general, es posible que desees inspeccionar el campo results[].types.

Nota: La codificación geográfica inversa no es una ciencia exacta. El geocodificador intentará encontrar la ubicación direccionable más cercana dentro de una tolerancia determinada.

Cómo recuperar una dirección para un id. de sitio

Proporciona un placeId para encontrar la dirección de un ID de lugar determinado. El id. de sitio es un identificador único que se puede usar con otras API de Google. Por ejemplo, puedes proporcionar el placeId que muestra la API de Roads para obtener la dirección de un punto ajustado. Para obtener más información sobre los ID de lugar, consulta la descripción general de los ID de lugar.

Cuando proporcionas un placeId, la solicitud no puede contener ninguno de los siguientes campos:

  • address
  • latLng
  • location
  • componentRestrictions

En el siguiente ejemplo, se acepta un id. de sitio, se encuentra la dirección correspondiente y se centra el mapa en esa ubicación. También abre una ventana de información que muestra la dirección con formato del 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 ejemplo

Probar la muestra