Anuncio: Pronto se lanzarán nuevos diseños de mapas base en Google Maps Platform. Esta actualización del diseño de mapas incluye una nueva paleta de colores predeterminada, pines modernizados y mejoras en la experiencia y la usabilidad del mapa. Todos los diseños de mapa se actualizarán automáticamente en marzo de 2025. Para obtener más información sobre la disponibilidad y cómo habilitar esta actualización antes, consulta Nuevo diseño de mapa para Google Maps Platform.

Se usó la API de Cloud Translation para traducir esta página.

Servicio Geocoding

Nota: Bibliotecas del servidor

Descripción general

La geocodificación es el proceso que convierte direcciones (como "1600 Amphitheatre Parkway, Mountain View, CA") 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 legibles por humanos (consulta Geocodificación inversa [búsqueda de direcciones]).

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

La API de Maps JavaScript proporciona una clase de Geocoder que permite realizar la geocodificación y la geocodificación inversa de forma dinámica a partir de las entradas de los usuarios. En cambio, si deseas geocodificar direcciones conocidas y estáticas, consulta el servicio web Geocoding.

Cómo comenzar

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

Para ver tu lista de APIs habilitadas, haz lo siguiente:

Ve a la consola de Google Cloud.
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.
En la lista de APIs del Panel, busca API de Geocoding.
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 abrir la pestaña Biblioteca. También puedes seleccionar Biblioteca en el menú lateral izquierdo.
2. Busca la opción API de Geocoding y selecciónala en la lista de resultados.
3. Selecciona HABILITAR. Cuando finalice el proceso, aparecerá la opción API de Geocoding en la lista de APIs del Panel.

Precios y políticas

Precios

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

Políticas

El uso del servicio Geocoding debe cumplir con las políticas establecidas para la API de Geocoding.

Solicitudes de Geocoding

El acceso al servicio Geocoding es asíncrono, ya que la API de Google Maps debe realizar una llamada a un servidor externo. Por ese motivo, debes pasar un método de devolución de llamada para la ejecución una vez que se complete la solicitud. Este método de devolución de llamada procesa los resultados. Ten en cuenta que el geocodificador puede mostrar más de un resultado.

Puedes acceder al servicio Geocoding de la API de Google Maps dentro de tu código mediante el objeto constructor google.maps.Geocoder. El método Geocoder.geocode() inicia una solicitud dirigida al servicio Geocoding 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: Indica la dirección que deseas geocodificar.
o
location: Indica el LatLng (o LatLngLiteral) para el que deseas obtener la dirección más cercana legible por humanos. El geocodificador ejecuta un geocódigo inverso. Consulta Geocodificación inversa para obtener más información.
o
placeId: Indica el ID de lugar del sitio para el que deseas obtener la dirección más cercana legible por humanos. Obtén más información sobre cómo recuperar una dirección de un ID de lugar.

Parámetros opcionales:

bounds: Es el elemento LatLngBounds en el que se personalizan resultados de geocódigos de forma más prominente. El parámetro bounds afecta a los resultados del geocodificador, pero no los restringe por completo. A continuación, puedes consultar 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 regional, que se indica mediante una subetiqueta regional Unicode de dos caracteres (no numéricos). En la mayoría de los casos, estas etiquetas se asignan directamente a valores de ccTLD ("dominio de nivel superior") conocidos de dos caracteres. El parámetro region afecta los resultados del geocodificador, pero no los restringe por completo. Obtén más información sobre la personalización del código regional a continuación.
extraComputations: El único valor permitido para este parámetro es ADDRESS_DESCRIPTORS. Consulta los descriptores de direcciones para obtener más detalles.
fulfillOnZeroResults: Cumple la promesa de un estado ZERO_RESULT en la respuesta. Esto puede ser conveniente porque, incluso con cero resultados de geocodificación, es posible que se devuelvan campos adicionales a nivel de la respuesta. Consulta Cómo realizar la entrega con cero resultados para obtener más detalles.

Respuestas de Geocoding

El servicio Geocoding exige que se ejecute un método de devolución de llamada cuando se obtengan resultados del geocodificador. Esta devolución de llamada debe pasar dos parámetros para contener results y el código status, en ese orden.

Nota: La respuesta de la geocodificación también contiene campos plus_code y address_descriptor a nivel de la respuesta, pero no se puede acceder a ellos a través de la devolución de llamada. En su lugar, se debe acceder a ellos a través de la promesa. Consulta Cómo realizar la entrega con cero resultados para obtener más detalles.

Resultados de Geocoding

El objeto GeocoderResult representa un solo resultado de la geocodificación. Una solicitud de geocódigo puede mostrar varios 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
 }
}

Estos campos se explican a continuación:

types[] es un array que indica el tipo de dirección del resultado que se muestra. Este array incluye un conjunto de cero o varias etiquetas que identifican el tipo de componente que se muestra en el resultado. Por ejemplo, un geocódigo de "Chicago" muestra la etiqueta "localidad", que indica que "Chicago" es una ciudad, y también "política", que indica que es una entidad política. Obtén más información sobre los tipos de dirección y los componentes de las direcciones a continuación.
formatted_address es una cadena que contiene la dirección legible por humanos de esta ubicación.
A menudo, esta dirección equivale a la dirección postal. Ten en cuenta que, en algunos países, como los que integran el Reino Unido, no se permite la distribución de direcciones postales verdaderas debido a restricciones de licencia.

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

No analices la dirección con formato por vía programática. En cambio, utiliza los componentes individuales de la dirección, que la respuesta de la API incluye además del campo de dirección con formato.
address_components[] es un array que contiene los componentes independientes que se aplican a esta dirección.

Por lo general, cada componente de la dirección incluye los siguientes campos:
- types[]: Es un array que indica el tipo de componente de la dirección. Consulta la lista de tipos admitidos.
- long_name: Es la descripción textual completa o el nombre del componente de la dirección que muestra el geocodificador.
- short_name: Es un nombre textual abreviado para el componente de la 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 2 letras.
Ten en cuenta lo siguiente acerca del array address_components[]:
- El array de componentes de dirección puede incluir más componentes que formatted_address.
- El array no necesariamente incluye todas las entidades políticas que contienen una dirección, además de las incluidas en formatted_address. Para obtener datos sobre todas las entidades políticas que contienen una dirección específica, debes usar la geocodificación inversa, y pasar la latitud y la longitud de la dirección como parámetro a la solicitud.
- No se garantiza que el formato de la respuesta permanezca igual entre las distintas 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 de posición en el array. El tipo de componente puede cambiar. Es posible que falte un componente en particular en una respuesta posterior.
Obtén más información sobre los tipos de dirección y los componentes de las direcciones a continuación.
partial_match indica que el geocodificador no mostró una concordancia exacta para la solicitud original, aunque sí encontró una coincidencia parcial para la dirección solicitada. Te recomendamos que examines la solicitud original para comprobar que no haya errores ortográficos y que la dirección no esté incompleta.

Las coincidencias parciales generalmente ocurren cuando las direcciones que se pasan en la solicitud no existen en la localidad. También se pueden mostrar coincidencias parciales cuando una solicitud concuerda con dos o más ubicaciones en la misma localidad. Por ejemplo, "Hillpar St, Bristol, UK" mostrará una coincidencia parcial tanto para Henry Street como para Henrietta Street. Ten en cuenta que si una solicitud incluye una dirección con un componente que contiene errores ortográficos, el servicio de geocodificación puede sugerir una dirección alternativa. Las sugerencias propuestas 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 APIs de Google. Por ejemplo, puedes usar el 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 los usuarios y mucho más. Consulta la descripción general del ID de lugar.
postcode_localities[] es un array que denota todas las localidades incluidas en un código postal y solo aparece cuando el resultado es un código postal que contiene varias localidades.
geometry contiene la siguiente información:
- location contiene los valores de latitud y longitud geocodificados. Ten en cuenta que esta ubicación se muestra como un objeto LatLng, no como una cadena 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). Generalmente, se devuelven resultados interpolados cuando no se encuentran geocódigos exactos disponibles para una dirección.
  - GEOMETRIC_CENTER indica que el resultado que se muestra refleja 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 (se muestra de manera opcional) abarca el LatLngBounds que puede contener por completo el resultado mostrado. Ten en cuenta que estos límites podrían no coincidir 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 mostrará las direcciones con la configuración de idioma preferida del navegador o el idioma especificado al cargar la API de JavaScript con el parámetro language. (Para obtener más información, consulta el artículo Localización).

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

El array types[] en GeocoderResult indica el tipo de dirección. El array types[] también se puede mostrar dentro de un GeocoderAddressComponent para indicar el tipo del componente de dirección particular. Las direcciones que muestra el geocodificador pueden ser de varios tipos, los cuales se pueden considerar como etiquetas. Por ejemplo, muchas ciudades están etiquetadas con los tipos political y locality.

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

street_address indica una dirección precisa.
route indica una ruta designada (como "US 101").
intersection indica una intersección principal, generalmente de dos rutas principales.
political indica una entidad política. Generalmente, este tipo indica un polígono de alguna Administración pública.
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 pública de primer orden por debajo del nivel de país. En Estados Unidos, estos niveles administrativos son los estados. No todos los países poseen estos niveles administrativos. En la mayoría de los casos, los nombres cortos de administrative_area_level_1 coincidirán considerablemente con las subdivisiones de ISO 3166-2 y otras listas conocidas; sin embargo, no podemos garantizarlo debido a que nuestros resultados de geocodificación se basan en diferentes indicadores y datos de ubicación.
administrative_area_level_2 indica una entidad pública de segundo orden por debajo del nivel de país. En Estados Unidos, estos niveles administrativos son los condados. No todos los países poseen estos niveles administrativos.
administrative_area_level_3 indica una entidad pública de tercer orden por debajo del nivel de país. Este tipo indica una división política inferior. No todos los países poseen estos niveles administrativos.
administrative_area_level_4 indica una entidad pública de cuarto orden por debajo del nivel de país. Este tipo indica una división política inferior. No todos los países poseen estos niveles administrativos.
administrative_area_level_5 indica una entidad pública de quinto orden por debajo del nivel de país. Este tipo indica una división política inferior. No todos los países poseen estos niveles administrativos.
administrative_area_level_6 indica una entidad pública de sexto orden por debajo del nivel de país. Este tipo indica una división política inferior. No todos los países poseen estos niveles administrativos.
administrative_area_level_7 indica una entidad pública de séptimo orden por debajo del nivel de país. Este tipo indica una división política inferior. No todos los países poseen estos niveles administrativos.
colloquial_area indica un nombre alternativo de uso general para la entidad.
locality indica una entidad política constituida como ciudad o pueblo.
sublocality indica una entidad pública 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 pública. Los números más altos indican un área geográfica más pequeña.
neighborhood indica un área residencial con nombre.
premise indica una ubicación designada, generalmente un edificio o un conjunto de edificios con un nombre común.
subpremise indica una entidad direccionable por debajo del nivel de la premisa, como un departamento, una unidad o una suite.
plus_code indica una referencia de ubicación codificada, derivada de la latitud y la longitud. Los Plus Codes se pueden usar como reemplazo de las direcciones en los lugares donde estas no existen (donde los edificios no están numerados o las calles no tienen nombre). Visita https://plus.codes para obtener más información.
postal_code indica un código postal, tal como se usa para identificar una dirección de correo postal dentro del país.
natural_feature indica un componente natural destacado.
airport indica un aeropuerto.
park indica un parque designado.
point_of_interest indica un lugar de interés designado. Por lo general, estos "lugares de interés" son entidades locales destacadas que no encajan con facilidad en otras categorías, como "Edificio Empire State" o "Torre Eiffel".

Una lista vacía de tipos indica que no hay tipos conocidos para el componente de dirección específico, 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 designado.
parking indica un estacionamiento o una estructura de estacionamiento.
post_box indica una casilla de correo postal específica.
postal_town indica un grupo de áreas geográficas, como locality y sublocality, que se usan para las direcciones de correo postal en algunos países.
room indica una habitación en una 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, es decir, que la dirección se analizó correctamente y mostró al menos un geocódigo.
"ZERO_RESULTS" indica que el geocódigo era correcto, pero no mostró resultados. Esto puede ocurrir si se pasó 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 tiene permitido 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 podría completarse con éxito si realizas un nuevo intento.
"ERROR" indica que se agotó el tiempo de espera de la solicitud o que se produjo un problema al contactar a los servidores de Google. La solicitud podría completarse con éxito si realizas un nuevo intento.

En este ejemplo, se geocodifica una dirección y se coloca un marcador a los valores de latitud y longitud mostrados. 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>

Consulta el ejemplo.

Personalización de viewports

También puedes dar instrucciones al servicio Geocoding para que anteponga ciertos resultados dentro de un viewport determinado (expresado como un cuadro delimitador). Para ello, configura el parámetro bounds dentro del literal de objeto GeocoderRequest para definir los límites de este viewport. Ten en cuenta que la personalización solo antepone los resultados dentro de los límites establecidos. Si existen más resultados relevantes fuera de estos límites, también es posible que se incluyan.

Por ejemplo, un geocódigo de “Winnetka” generalmente muestra 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, cuando se especifica un parámetro bounds que define un cuadro delimitador para el Valle de San Fernando en Los Ángeles, se obtiene como resultado un geocódigo que muestra el vecindario "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"
}

Personalización de códigos regionales

Puedes configurar el servicio Geocoding explícitamente para que muestre resultados personalizados para una región en particular mediante el parámetro region. Este parámetro toma un código de región, que se indica 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" en "co.uk". En algunos casos, la etiqueta region también admite códigos ISO-3166-1, que a veces difieren de los valores de ccTLD (por ejemplo, "GB" para "Gran Bretaña").

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

Solo especifica un país o una región. Los valores múltiples se ignoran y pueden generar errores en la solicitud.
Usa solo subetiquetas regionales 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 todos los dominios en los que la aplicación principal de Google Maps ofrece geocodificación. Ten en cuenta que la personalización solo antepone los resultados correspondientes a un dominio específico. Si hay más resultados relevantes fuera de este dominio, es posible que también se incluyan.

Por ejemplo, un geocódigo de "Toledo" muestra este resultado, ya que el dominio predeterminado para el servicio Geocoding 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 de "Toledo" con el campo region establecido 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 Geocoding para que muestre resultados de direcciones restringidos a un área específica mediante un filtro de componentes. Especifica el filtro en el parámetro componentRestrictions. Los valores de filtros admiten los mismos métodos de corrección ortográfica y coincidencia parcial que otras solicitudes de geocodificación.

El geocodificador muestra solo los resultados que coinciden con todos los filtros de componentes. Esto significa que evalúa las especificaciones del filtro como un operador Y, no como un operador O.

Un filtro de componentes consta de uno o varios de los siguientes elementos:

route establece coincidencias con el nombre largo o corto de una calle.
locality establece coincidencias con los tipos de localidad y sublocalidad.
administrativeArea establece coincidencias con todos los niveles de área administrativa.
postalCode establece coincidencias con los códigos postales y los prefijos de códigos postales.
country establece coincidencias 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 los 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);
  }
});
}

Entrega en resultados de Zero

Para la geocodificación inversa, de forma predeterminada, la promesa se rompe en status=ZERO_RESULTS. Sin embargo, es posible que los campos adicionales a nivel de la respuesta de plus_code y address_descriptor aún se propaguen en este caso. Si se proporciona verdadero para el parámetro fulfillOnZeroResults, no se rompe la promesa y se puede acceder a estos campos adicionales desde la promesa si están presentes.

El siguiente es un ejemplo de este comportamiento para una latitud/longitud en la Antártida. Aunque no haya resultados de la codificación geográfica inversa, podemos imprimir el código plus en la promesa si configuramos 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`);
        });
    }

Descriptores de direcciones

Los descriptores de direcciones incluyen información adicional que ayuda a describir una ubicación con puntos de referencia y áreas. Consulta la demostración de descriptores de direcciones para explorar la función.

Los descriptores de direcciones se pueden habilitar con el parámetro extraComputations. Incluye extra_computations=ADDRESS_DESCRIPTORS en una solicitud de geocodificación, una solicitud de geocodificación inversa o una solicitud de geocodificación de lugares para recibir descriptores de direcciones en tu respuesta.

Ejemplo de geocodificación de lugares

La siguiente consulta contiene la dirección de un lugar en 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);
    }
  });
}

Ejemplo de geocodificación inversa

La siguiente consulta contiene el valor de latitud/longitud de una ubicación en 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`);
        });
    }

Ejemplo de descriptor de dirección

Un ejemplo de address_descriptor es el siguiente:

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

Hay dos arrays en cada objeto address_descriptor: landmarks y areas. El array landmarks contiene hasta 5 resultados clasificados en orden de relevancia, teniendo en cuenta la proximidad a la coordenada solicitada, la prevalencia del lugar de interés y su visibilidad. Cada resultado de punto de referencia contiene los siguientes valores:

place_id es el ID del lugar del resultado de los lugares de interés. Consulta la descripción general de los IDs de lugar.
display_name es el nombre visible del punto de referencia y contiene language_code y text.
straight_line_distance_meters es la distancia punto a punto en metros entre la coordenada de entrada y el resultado de los lugares de interés.
travel_distance_meters es la distancia en metros que se recorre a través de la red de rutas (sin tener en cuenta las restricciones viales) entre la coordenada de entrada y el resultado de los lugares de interés.
spatial_relationship es la relación estimada entre la coordenada de entrada y el resultado de los lugares de interés:

"NEAR" es la relación predeterminada cuando no se aplica ninguna de las siguientes opciones.
"WITHIN" cuando la coordenada de entrada se encuentra dentro de los límites de la estructura asociada con el punto de referencia.
"BESIDE" cuando la coordenada de entrada está directamente adyacente al lugar de interés o al punto de acceso del lugar de interés.
"ACROSS_THE_ROAD" cuando la coordenada de entrada está directamente opuesta al punto de referencia en el otro lado de la ruta.
"DOWN_THE_ROAD" cuando la coordenada de entrada está en la misma ruta que el punto de referencia, pero no "BESIDES" ni "ACROSS_THE_ROAD"
"AROUND_THE_CORNER" cuando la coordenada de entrada está a lo largo de una ruta perpendicular como el punto de referencia (restringido a un solo giro).
"BEHIND" cuando la coordenada de entrada está espacialmente cerca del punto de referencia, pero lejos de su punto de acceso.

types son los tipos de lugares del punto de referencia.

El objeto areas contiene hasta 3 respuestas y se limita a lugares que representan regiones pequeñas, como vecindarios, sublocalidades y grandes complejos. Las áreas que contienen la coordenada solicitada se muestran primero y se ordenan de menor a mayor. Cada resultado de areas contiene los siguientes valores:

place_id es el ID de lugar del resultado de las áreas. Consulta la descripción general de los IDs de lugar.
display_name es el nombre visible del área y contiene language_code y text.
containment es la relación de contención estimada entre la coordenada de entrada y el resultado de las áreas:

"NEAR" es la relación predeterminada cuando no se aplica ninguna de las siguientes opciones.
"WITHIN" cuando la coordenada de entrada está cerca del centro del área.
"OUTSKIRTS" cuando la coordenada de entrada está cerca del borde del área.

Cobertura de descriptores de direcciones

Esta función solo está disponible en países seleccionados.

Esta es una función de versión preliminar y apreciaríamos tus comentarios. Envíanos un correo electrónico a address-descriptors-feedback@google.com.

Geocodificación inversa (búsqueda de direcciones)

El término geocodificación generalmente hace referencia a la conversión de una dirección legible por humanos en una ubicación en un mapa. El proceso inverso, es decir, de convertir una ubicación en el mapa en una dirección legible por humanos, se conoce como geocodificación inversa.

En lugar de proporcionar un elemento address textual, debes proporcionar el valor de latitud y longitud, separado por comas, en el parámetro location.

Nota: Si incluyes el parámetro componentRestrictions en la solicitud, se ignora el parámetro location.

En el siguiente ejemplo, se geocodifica un valor de latitud y longitud, se centra el mapa en la ubicación correspondiente y se abre una ventana de información que incluye 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;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

Ver ejemplo

Prueba la muestra

JSFiddle.net Google Cloud Shell

Ten en cuenta que, en el ejemplo anterior, se mostró el primer resultado seleccionando results[0]. El geocodificador inverso a menudo muestra más de un resultado. Las direcciones geocodificadas no solo representan direcciones postales, sino que permiten hacer referencia a cualquier ubicación geográfica. Por ejemplo, cuando se geocodifica un punto en la ciudad de Chicago, dicha ubicación puede etiquetarse como una dirección, como una ciudad (Chicago), como un estado (Illinois) o como un país (Estados Unidos). Todas las direcciones corresponden al geocodificador. El geocodificador inverso muestra todos estos resultados.

La geocodificación inversa establece coincidencias con entidades políticas (países, provincias, ciudades y vecindarios), direcciones y códigos postales.

A continuación, se muestra 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 muestran en orden de mayor a menor coincidencia. En general, la dirección más exacta es el resultado más prominente, como en este caso. Ten en cuenta que se muestran diferentes tipos de direcciones, desde la dirección más específica hasta entidades políticas menos específicas, como vecindarios, ciudades, condados, estados, etc. Si deseas buscar coincidencias con una dirección más general, te recomendamos que inspecciones el campo results[].types.

Nota: La geocodificación inversa no es una ciencia exacta. El geocodificador intentará hallar la ubicación localizable más cercana dentro de una tolerancia determinada.

Cómo obtener una dirección para un ID de lugar

Proporciona un placeId para encontrar una dirección de un ID de lugar determinado. El ID de lugar es un identificador único que se puede usar con otras APIs 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 IDs de lugar, consulta la descripción general de los IDs 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 lugar, se encuentra la dirección correspondiente y se centra el mapa en esa ubicación. También se genera una ventana de información en la que se muestra la dirección con formato del lugar relevante: