Google Maps Geocoding API

Este servicio también está disponible como parte de la Google Maps JavaScript API, o de las bibliotecas de cliente Java y Python.

¿Qué es la geocodificación?

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 disponer marcadores en un mapa o posicionar el mapa.

La geocodificación inversa es el proceso de conversión de coordenadas geográficas en direcciones en lenguaje natural. El servicio de geocodificación inversa Google Maps Geocoding API también te permite buscar la dirección por un id. de sitio determinado.

Google Maps Geocoding API proporciona una forma directa de acceder a esos servicios a través de una solicitud HTTP.

Antes de comenzar

Este documento está orientado a desarrolladores de sitios web y móviles que quieren usar datos de geocodificación dentro de mapas proporcionados por una de las Google Maps API.

Este servicio generalmente está diseñado para geocodificar direcciones estáticas (ya conocidas) para la colocación de contenido de la aplicación en un mapa ; este servicio no se diseñó para responder en tiempo real a las entradas del usuario, por ejemplo. Para la geocodificación dinámica (por ejemplo, dentro de un elemento de la interfaz de usuario), consulta la documentación para el geocodificador de cliente deGoogle Maps JavaScript API o las API de ubicación de los Google Play Services.

La geocodificación es una tarea que consume tiempo y recursos. Siempre que sea posible, realiza una geocodificación previa de las direcciones conocidas (usando la Google Maps Geocoding API que se describe aquí u otro servicio de geocodificación) y guarda tus resultados en un caché temporal de tu propio diseño.

Para usar la Google Maps Geocoding API, necesitas una clave de API.

Obtén una clave Límites de uso

Formato de solicitud de Google Maps Geocoding API

Una solicitud de Google Maps Geocoding API debe respetar la siguiente forma:

https://maps.googleapis.com/maps/api/geocode/output?parameters

donde output puede ser cualquiera de los siguientes valores:

  • json (recomendado) indica el formato de salida en JavaScript Object Notation (JSON).
  • xml indica el formato de salida como XML.

Para acceder a la Google Maps Geocoding API a través de HTTP, usa:

http://maps.googleapis.com/maps/api/geocode/output?parameters

No se recomienda HTTP para aplicaciones que incluyen en las solicitudes datos privados de los usuarios, como la ubicación de un usuario.

Algunos parámetros son obligatorios y otros opcionales. Como es norma en las direcciones URL, los parámetros se separan con el carácter de Y comercial (&).

Los usuarios de Google Maps API for Work deben incluir parámetros client y signature válidos con sus solicitudes de geocodificación. Para obtener más información, consulta servicios web de Google Maps API for Work.

El resto de esta página describe la geocodificación y la geocodificación inversa por separado, ya que hay diferentes parámetros disponibles para cada tipo de solicitud.

Geocodificación (búsqueda de latitud/longitud)

Parámetros obligatorios en una solicitud de geocodificación:

  • address: la dirección que quieres geocodificar, en el formato utilizado por el servicio postal nacional del país correspondiente. Se deben evitar elementos de dirección adicionales, como nombres de empresas y números de unidad, habitación o piso. Consulta las preguntas frecuentes para obtener máas información.
         o
    components: un filtro de componente para el que quieres obtener un geocódigo. Para obtener más información, consulta Filtrado de componentes. El filtro de componentes también se aceptará como un parámetro opcional si se proporciona un parámetro address.
  • key: la clave de API de tu aplicación. Esta clave identifica tu aplicación a los fines de la administración de la cuota. Infórmate acerca de cómo obtener una clave.

Parámetros opcionales en una solicitud de geocodificación:

  • bounds: el cuadro de límite del viewport dentro del que se restringirán los resultados de geocódigos de manera más prominente. Este parámetro solo afectará, pero no restringirá por completo, los resultados del geocodificador. (Para obtener más información, consulta Restricción de viewports a continuación).
  • language: el idioma en el que se devolverán los resultados. Consulta la lista de idiomas de dominio admitidos. Ten en cuenta que, a menudo, actualizamos los idiomas admitidos, por lo que es posible que esta lista no esté completa. Si no se proporciona el parámetro language, siempre que sea posible, el geocodificador intentará usar el lenguaje nativo del dominio desde el que se envía la solicitud.
  • region: especifica el código de región, establecido como un valor ccTLD (“dominio de nivel superior”) de dos caracteres. Este parámetro solo afectará, pero no restringirá por completo, los resultados del geocodificador. (Para obtener más información, consulta Restricción por región a continuación).
  • components: los filtros de componentes, separados por una barra vertical (|). Cada filtro de componentes consiste en un par component:value y restringirá por completo los resultados del geocodificador. Para obtener más información, consulta Filtrado de componentes, a continuación.

Respuestas de geocodificación

Las respuestas de geocodificación se devuelven en el formato indicado por el marcador output en la ruta de acceso de la dirección URL de la solicitud.

En este ejemplo, la Google Maps Geocoding API solicita una respuesta json para una consulta sobre "1600 Amphitheatre Parkway, Mountain View, CA".

Esta solicitud muestra el uso del marcador output de JSON:

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

Esta solicitud muestra el uso del marcador output de XML:

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

Haz clic en las pestañas a continuación para ver las respuestas JSON y XML de ejemplo.

JSON
{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "1600",
               "short_name" : "1600",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Amphitheatre Pkwy",
               "short_name" : "Amphitheatre Pkwy",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Mountain View",
               "short_name" : "Mountain View",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Clara County",
               "short_name" : "Santa Clara County",
               "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" ]
            },
            {
               "long_name" : "94043",
               "short_name" : "94043",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "1600 Amphitheatre Parkway, Mountain View, CA 94043, USA",
         "geometry" : {
            "location" : {
               "lat" : 37.4224764,
               "lng" : -122.0842499
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 37.4238253802915,
                  "lng" : -122.0829009197085
               },
               "southwest" : {
                  "lat" : 37.4211274197085,
                  "lng" : -122.0855988802915
               }
            }
         },
         "place_id" : "ChIJ2eUgeAK6j4ARbn5u_wAGqWA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

Ten en cuenta que una respuesta JSON contiene dos elementos principales:

  • "status" contiene metadatos sobre la solicitud. Consulta los siguientes Códigos de estado.
  • "results" contiene una matriz de información sobre direcciones geocodificadas e información sobre geometría.

Generalmente, para las búsquedas de direcciones solo se devuelve una entrada en la matriz "results", aunque el geocodificador puede devolver varios resultados cuando las consultas de dirección sean ambiguas.

Ten en cuenta que estos resultados generalmente se deben analizar si quieres extraer valores de ellos. El análisis de JSON es relativamente fácil. Consulta Análisis de JSON para obtener información sobre algunos de los patrones de diseño recomendados.

XML
<GeocodeResponse>
 <status>OK</status>
 <result>
  <type>street_address</type>
  <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
  <address_component>
   <long_name>1600</long_name>
   <short_name>1600</short_name>
   <type>street_number</type>
  </address_component>
  <address_component>
   <long_name>Amphitheatre Pkwy</long_name>
   <short_name>Amphitheatre Pkwy</short_name>
   <type>route</type>
  </address_component>
  <address_component>
   <long_name>Mountain View</long_name>
   <short_name>Mountain View</short_name>
   <type>locality</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>San Jose</long_name>
   <short_name>San Jose</short_name>
   <type>administrative_area_level_3</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>Santa Clara</long_name>
   <short_name>Santa Clara</short_name>
   <type>administrative_area_level_2</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>California</long_name>
   <short_name>CA</short_name>
   <type>administrative_area_level_1</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>United States</long_name>
   <short_name>US</short_name>
   <type>country</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>94043</long_name>
   <short_name>94043</short_name>
   <type>postal_code</type>
  </address_component>
  <geometry>
   <location>
    <lat>37.4217550</lat>
    <lng>-122.0846330</lng>
   </location>
   <location_type>ROOFTOP</location_type>
   <viewport>
    <southwest>
     <lat>37.4188514</lat>
     <lng>-122.0874526</lng>
    </southwest>
    <northeast>
     <lat>37.4251466</lat>
     <lng>-122.0811574</lng>
    </northeast>
   </viewport>
  </geometry>
  <place_id>ChIJ2eUgeAK6j4ARbn5u_wAGqWA</place_id>
 </result>
</GeocodeResponse>

Ten en cuenta que una respuesta XML consiste en una <GeocodeResponse> y dos elementos de nivel superior:

  • <status> contiene metadatos sobre la solicitud. Consulta los siguientes Códigos de estado.
  • Cero o más elementos <result>, cada uno con un conjunto de información acerca de direcciones geocodificadas e información sobre geometría.

Ten en cuenta que esta respuesta es considerablemente más extensa que la respuesta JSON. Por esa razón, te recomendamos que uses json como marcador de formato de salida preferido, a menos que tu aplicación requiera xml por algún motivo. Además, el procesamiento de árboles XML requiere de cierto cuidado, ya que debes hacer referencia a los nodos y elementos adecuados. Consulta Análisis de XML con XPath para obtener información sobre algunos de los patrones de diseño recomendados para el procesamiento del formato de salida.

En el resto de esta documentación se usará sintaxis JSON. En la mayoría de los casos, el formato de salida no tiene importancia para los fines de ilustración de conceptos o nombres de campos en la documentación. No obstante, observa las siguientes diferencias leves:

  • Los resultados XML se agrupan en un elemento raíz <GeocodeResponse>.
  • JSON denota entradas con múltiples elementos mediante matrices en plural (types), mientras XML las denota con múltiples elementos en singular (<type>).
  • Los elementos en blanco se indican mediante matrices vacías en JSON, y mediante la ausencia de un elemento como este en XML. Una respuesta que no genera resultados devolverá una matriz results vacía en JSON, pero no devolverá elementos <result> en XML, por ejemplo.

Códigos de estado

El campo "status" en el objeto de la respuesta de geocodificación contiene el estado de la solicitud y podría contener información de depuración para ayudarte a localizar por qué falló la geocodificación. El campo "status" puede contener los siguientes valores:

  • "OK" indica que no ocurrieron errores, que la dirección se analizó correctamente y que se devolvió al menos un geocódigo.
  • ZERO_RESULTS indica que el geocódigo fue exitoso, pero no devolvió resultados. Esto puede ocurrir si se pasa un valor address inexistente al geocodificador.
  • "OVER_QUERY_LIMIT" indica que excediste tu cuota.
  • "REQUEST_DENIED" indica que se rechazó tu solicitud.
  • "INVALID_REQUEST" generalmente indica que falta la consulta (address, components o latlng).
  • "UNKNOWN_ERROR" indica que no se pudo procesar la solicitud por un error en el servidor. La solicitud puede tener éxito si realizas un nuevo intento.

Mensajes de error

Cuando el geocodificador devuelve un código de estado diferente deOK, posiblemente haya un campo error_message en el objeto de respuesta de geocodificación. Este campo contiene información más detallada acerca de los motivos del código de estado proporcionado.

Nota: No se garantiza que este campo aparezca siempre, y su contenido está sujeto a modificaciones.

Resultados

Cuando el geocodificador devuelve resultados, los ubica en una matriz results (JSON). Incluso si el geocodificador no devuelve resultados (como ocurriría si la dirección no existiera), aún devolverá una matriz results vacía. (Las respuestas XML consisten en cero o más elementos <result>).

Un resultado típico está compuesto por los siguientes campos:

  • La matriz types[] indica el tipo de resultado devuelto. Esta matriz contiene un grupo de cero o más etiquetas que identifican el tipo de función devuelto en el resultado. Por ejemplo, para un geocódigo “Chicago”, se devuelve “localidad”, que indica que “Chicago” es una ciudad, y también se devuelve “político”, que indica que se trata de una entidad política.

  • formatted_address es una cadena que contiene la dirección de la ubicación en lenguaje natural. A menudo, esa dirección equivale a la "dirección postal" que suele diferir según el país. (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). Esta dirección generalmente está compuesta por uno o más componentes de dirección. Por ejemplo, la dirección "111 8th Avenue, New York, NY" contiene componentes de dirección independientes para "111" (el número en la calle), "8th Avenue" (la calle), "New York" (la ciudad) y "NY" (el estado de los EE. UU.). Estos componentes de dirección contienen información adicional, como se indica a continuación.

  • address_components[] es una matriz que contiene los componentes de dirección independientes, según lo explicado antes. Cada address_component generalmente contiene:

    • types[] es una matriz que indica el tipo de componente de la dirección.
    • long_name es la descripción textual o el nombre completo del componente de dirección, tal como lo devuelve el geocodificador.
    • short_name es un nombre textual abreviado para el componente de dirección, si estuviera disponible. Por ejemplo, un componente de dirección para el estado de Alaska podría tener un valor long_name "Alaska" y un valor short_name "AK" para el que se usa la abreviatura postal de dos letras.

    Ten en cuenta que address_components[] puede contener más componentes de dirección que los que se indican en formatted_address.

  • postcode_localities[] es una matriz que denota todas las localidades que comprende un código postal. Esto solo se presenta 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. En las búsquedas de direcciones normales, este campo generalmente es el más importante.
    • location_type almacena datos adicionales sobre la ubicación especificada. Se admiten los siguientes valores:

      • "ROOFTOP" indica que el resultado devuelto es un geocódigo exacto para el cual contamos con información de ubicación precisa que puede delimitarse hasta la dirección.
      • "RANGE_INTERPOLATED" indica que el resultado devuelto refleja una aproximación (generalmente en una calle) interpolada entre dos puntos precisos (como intersecciones). Generalmente se devuelven resultados interpolados cuando no se encuentran disponibles geocódigos exactos para una dirección.
      • "GEOMETRIC_CENTER" indica que el resultado devuelto 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 devuelto es aproximado.
    • viewport contiene el viewport recomendado para mostrar el resultado devuelto, especificado como dos valores de latitud y longitud que definen la esquina southwest y northeast del cuadro de límite del viewport. Generalmente, el viewport se usa para enmarcar un resultado cuando se lo muestra al usuario.
    • bounds (devolución opcional) guarda el cuadro de límite que puede contener por completo el resultado devuelto. Ten en cuenta que probablemente estos límites no coincidan con el viewport recomendado. (Por ejemplo, San Francisco incluye los Farallones, que técnicamente son parte de la ciudad, pero no se devolverán en el viewport).
  • partial_match indica que el geocodificador no devolvió una coincidencia exacta para la solicitud original, aunque sí pudo establecer 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 pasaste en la solicitud no existen en la localidad. También se pueden devolver coincidencias parciales cuando una solicitud coincide con dos o más ubicaciones en la misma localidad. Por ejemplo, "21 Henr St, Bristol, UK" devolverá una coincidencia parcial para Henry Street y 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 que se puede usar con otras API de Google. Por ejemplo, puedes usar place_id en una solicitud Google Places API para obtener información detallada de un negocio local, como el número de teléfono, el horario de apertura, reseñas de usuarios, etc. Consulta la información general sobre id. de sitio.

Dado que no se puede garantizar el formato exacto de una respuesta individual a una solicitud de Google Maps Geocoding API, nunca debes asumir que los elementos se encuentran en posiciones absolutas. (Particularmente, la cantidad de address_components en una respuesta de la Geocoding API varía según la dirección solicitada y puede cambiar con el tiempo). En su lugar, debes analizar la respuesta y seleccionar valores adecuados mediante expresiones. Consulta Análisis de respuestas de servicios web para obtener más información.

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

La matriz types[] en el resultado indica el tipo de dirección. Entre los ejemplos de tipos de direcciones se encuentran una dirección, un país o una entidad política. También hay una matriz types[] en address_components[], que indica el tipo de cada parte de la dirección. Los ejemplos incluyen el número de una calle o el país. (A continuación se proporciona una lista completa de tipos). Las direcciones pueden tener múltiples tipos. Los tipos pueden considerarse “etiquetas”. Por ejemplo, muchas ciudades reciben etiquetas con los tipos political y locality.

El geocodificador admite y devuelve los siguientes tipos en las matrices de tipo de dirección y tipo de componente de dirección:

  • street_address indica una dirección exacta.
  • route indica la denominación de una carretera (como "US 101").
  • intersection indica una intersección principal, generalmente de dos calles importantes.
  • 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 es generalmente el tipo de orden más alto que devuelve 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 los estados. No todos los países poseen estos niveles administrativos.
  • 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 los condados. No todos los países poseen 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.
  • colloquial_area indica un nombre alternativo de uso frecuente para la entidad.
  • locality indica una entidad política constituida de una ciudad o un pueblo.
  • ward indica un tipo específico de localidad japonesa para facilitar la distinción entre los múltiples componentes de localidad en una dirección japonesa.
  • 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 determinado.
  • premise indica una ubicación determinada, generalmente un edificio o un conjunto de edificios con un nombre en común.
  • subpremise indica una entidad de primer orden por debajo de una ubicación determinada; generalmente un edificio en particular en un conjunto de edificios con un nombre en comú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 una atracción natural destacada.
  • airport indica un aeropuerto.
  • park indica un parque determinado.
  • point_of_interest indica un punto de interés determinado. Generalmente, estos "PI" son entidades locales destacadas que no pueden incluirse fácilmente en otra categoría, como el edificio "Empire State" o la "Estatua de la libertad".

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 está completa y está sujeta a cambio.

  • floor indica el piso en la dirección de un edificio.
  • establishment generalmente indica un lugar que aún ha sido categorizado.
  • point_of_interest indica un punto de interés determinado.
  • parking indica un área de estacionamiento o una estructura de estacionamiento.
  • post_box indica una casilla de correo específica.
  • postal_town indica un conjunto de áreas geográficas, como locality y sublocality, utilizadas para las direcciones postales en algunos países.
  • room indica una sala en 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 respectivamente.

Restricción de viewports

En una solicitud de geocodificación, puedes indicarle al servicio de geocodificación que anteponga los resultados que se encuentren en un viewport determinado (expresado como un cuadro de límite). Puedes hacerlo en la dirección URL de la solicitud configurando el parámetro bounds. Ten en cuenta que la restricción solo antepone resultados dentro de los límites. Si existen más resultados fuera de estos límites, pueden incluirse.

El parámetro bounds define las coordenadas de latitud/longitud de las esquinas sudoeste y noreste de este cuadro de límite usando un carácter de barra vertical (|) para separar las coordenadas.

Por ejemplo, un geocódigo para “Winnetka” generalmente devuelve este suburbio de Chicago:

Solicitud:

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&key=YOUR_API_KEY

Respuesta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "New Trier",
               "short_name" : "New Trier",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Cook County",
               "short_name" : "Cook County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Illinois",
               "short_name" : "IL",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Winnetka, IL, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            },
            "location" : {
               "lat" : 42.10808340000001,
               "lng" : -87.735895
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            }
         },
         "place_id" : "ChIJW8Va5TnED4gRY91Ng47qy3Q",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Sin embargo, cuando se especifica un parámetro bounds en el que se define un cuadro de límite para el Valle de San Fernando, en Los Ángeles, se obtiene como resultado un geocódigo en el que se devuelve el vecindario llamado “Winnetka” en esa ubicación:

Solicitud:

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&bounds=34.172684,-118.604794|34.236144,-118.500938&key=YOUR_API_KEY

Respuesta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Los Angeles",
               "short_name" : "LA",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Los Angeles County",
               "short_name" : "Los Angeles County",
               "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" ]
            }
         ],
         "formatted_address" : "Winnetka, Los Angeles, CA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            },
            "location" : {
               "lat" : 34.2048586,
               "lng" : -118.5739621
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            }
         },
         "place_id" : "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ",
         "types" : [ "neighborhood", "political" ]
      }
   ],
   "status" : "OK"
}

Restricción por región

En una respuesta de geocodificación, Google Maps Geocoding API devuelve resultados de dirección influenciados por la región (generalmente el condado) desde la que se envía la solicitud. Por ejemplo, las búsquedas de “San Francisco” pueden devolver resultados diferentes si se envían desde un dominio de los Estados Unidos o de uno de España.

Puedes configurar Google Maps Geocoding API para que devuelva resultados restringidos a una región específica usando el parámetro region. Este parámetro toma un argumento ccTLD (dominio de nivel superior de código de país) que especifica la restricción por región. La mayoría de los códigos ccTLD son idénticos a los códigos ISO 3166-1, con algunas excepciones notables. Por ejemplo, el código ccTLD para el Reino Unido es "uk" (.co.uk) mientras que su código ISO 3166-1 es "gb" (técnicamente para la entidad de «Reino Unido de Gran Bretaña e Irlanda del Norte").

Se pueden restringir los resultados de la geocodificación para todos los dominios en los que se ejecute oficialmente la aplicación principal de Google Maps. Ten en cuenta que la restricción solo antepone resultados para un dominio específico. Si hubiera más resultados relevantes fuera de este dominio, podrían incluirse.

Por ejemplo, un geocódigo para “Toledo” devuelve este resultado ya que el dominio predeterminado para la Google Maps Geocoding API está configurado en Estados Unidos. Solicitud:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY

Respuesta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lincoln County",
               "short_name" : "Lincoln County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Oregon",
               "short_name" : "OR",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OR, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            },
            "location" : {
               "lat" : 44.621507,
               "lng" : -123.9384478
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            }
         },
         "place_id" : "ChIJmcjO1AjUwVQRDsRYrfWvzyo",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Tama County",
               "short_name" : "Tama County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Iowa",
               "short_name" : "IA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, IA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            },
            "location" : {
               "lat" : 41.9972134,
               "lng" : -92.5835266
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            }
         },
         "place_id" : "ChIJvwoVNEOE74cR3oQfIk7m6fU",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lewis County",
               "short_name" : "Lewis County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "98591",
               "short_name" : "98591",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Toledo, WA 98591, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            },
            "location" : {
               "lat" : 46.4398305,
               "lng" : -122.846783
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            }
         },
         "place_id" : "ChIJPw9m6cb4k1QRyA5L3wI_dRM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Una solicitud de geocodificación para "Toledo" con region=es (España) devolverá la ciudad española. Solicitud:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

Respuesta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Vega de Toledo",
               "short_name" : "Vega de Toledo",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "TO",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Castile-La Mancha",
               "short_name" : "CM",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, Toledo, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            },
            "location" : {
               "lat" : 39.8628316,
               "lng" : -4.027323099999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            }
         },
         "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Filtrado de componentes

En una respuesta de geocodificación, Google Maps Geocoding API puede devolver resultados de dirección restringidos a un área específica. La restricción se especifica usando el filtro components. Un filtro consiste en una lista de pares component:value separados por una barra vertical (|). Solo se devolverán resultados que coincidan con todos los filtros. Los valores de filtros admiten los mismos métodos de corrección ortográfica y coincidencia parcial que otras solicitudes de geocodificación. Si un resultado de geocodificación es una coincidencia parcial para un filtro de componentes, incluirá un campo partial_match en la respuesta.

Los components que se pueden filtrar incluyen:

  • route establece coincidencias con el nombre largo o corto de una calle.
  • locality establece coincidencias con los tipos locality y sublocality.
  • administrative_area establece coincidencias con todos los niveles de administrative_area.
  • postal_code establece coincidencias con postal_code y postal_code_prefix.
  • country establece coincidencias con el nombre de un país o con un código de país ISO 3166-1 de dos letras.

Nota: Cada componente de dirección solo se puede especificar en el parámetro de dirección o como un filtro de componentes, pero no ambos. Hacerlo podría dar lugar a ZERO_RESULTS.

Un geocódigo para "Santa Cruz" con components=country:ES devolverá Santa Cruz de Tenerife en las Islas Canarias, España. Solicitud:

https://maps.googleapis.com/maps/api/geocode/json?address=santa+cruz&components=country:ES&key=YOUR_API_KEY

Respuesta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Anaga",
               "short_name" : "Anaga",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canarias",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Una consulta que contenga un filtro de componentes solo devolverá los resultados de geocodificación que coincidan con ese filtro. Si no se encuentran coincidencias, el geocodificador devolverá un resultado que coincida con el filtro mismo. Solicitud:

https://maps.googleapis.com/maps/api/geocode/json?address=Torun&components=administrative_area:TX|country:US&key=YOUR_API_KEY

Respuesta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Texas",
               "short_name" : "TX",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Texas, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 36.5007041,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            },
            "location" : {
               "lat" : 31.9685988,
               "lng" : -99.9018131
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 36.5015087,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJSTKCCzZwQIYRPN4IGI8c6xY",
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

El filtrado de componentes devolverá una respuesta ZERO_RESULTS solo si proporcionas filtros que se excluyan entre sí. Solicitud:

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

Respuesta:

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

Al usar el filtro components se puede realizar una consulta sin el parámetro de dirección, pero no puedes especificar un componente sin un valor. Solicitud:

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annegatan|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

Respuesta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annegatan",
               "short_name" : "Annegatan",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Annegatan, Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Annevägen",
               "short_name" : "Annevägen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Vanda",
               "short_name" : "Vanda",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "01420",
               "short_name" : "01420",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annevägen, 01420 Vanda, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.3282738,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32564009999999,
                  "lng" : 25.1076474
               }
            },
            "location" : {
               "lat" : 60.3271069,
               "lng" : 25.1118046
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.3283059302915,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32560796970849,
                  "lng" : 25.1076474
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ3UJCNt4GkkYR8-_a8Dh25kA",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Anneplatsen",
               "short_name" : "Anneplatsen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00100",
               "short_name" : "00100",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Anneplatsen, 00100 Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.1695664,
                  "lng" : 24.9357125
               },
               "southwest" : {
                  "lat" : 60.168997,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1692741,
               "lng" : 24.9348016
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.17063068029151,
                  "lng" : 24.9362052302915
               },
               "southwest" : {
                  "lat" : 60.1679327197085,
                  "lng" : 24.9335072697085
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJeahMqswLkkYR2vQfG1nHI3M",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

Geocodificación inversa (búsqueda de direcciones)

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

Parámetros obligatorios: En una solicitud de geocodificación inversa, debes proporcionar uno de los siguientes parámetros, pero no ambos:

  • Ya sea: latlng: los valores de latitud y longitud que especifican la ubicación para la que quieres obtener la dirección más cercana en lenguaje natural.
  • O bien: place_id: el id. de sitio del sitio para el que quieres obtener la dirección en lenguaje natural. El id. de sitio es un identificador único que puede usarse con otras API de Google. Por ejemplo, puedes usar el placeId devuelto por la Google Maps Roads API para obtener la dirección de un punto ajustado. Para obtener más información sobre los id. de sitio, consulta la información general sobre id. de sitio. El id. de sitio solo se puede especificar si la solicitud incluye una clave de API o un id. de cliente de Google Maps API for Work.

Parámetros opcionales en una solicitud de geocodificación inversa:

Estos son los parámetros opcionales que puedes incluir en una solicitud de geocodificación inversa:

  • key: la clave de API de tu aplicación, obtenida a través de Google API Console. Esta clave identifica tu aplicación a los fines de la administración de la cuota.
  • language: el idioma en el que se devolverán los resultados. Consulta la lista de idiomas de dominio admitidos. Ten en cuenta que, a menudo, actualizamos los idiomas admitidos, por lo que es posible que esta lista no esté completa. Si no se proporciona el parámetro language, siempre que sea posible, el geocodificador intentará usar el lenguaje nativo del dominio desde el que se envía la solicitud.
  • result_type: uno o más tipos de dirección, separados por una barra vertical (|). Ejemplos de tipos de dirección: country, street_address, postal_code. Para acceder a una lista completa de valores permitidos, consulta tipos de dirección en esta página. Al especificar un tipo, se restringirán los resultados a ese tipo. Si se especifican múltiples tipos, la API devolverá todas las direcciones que coincidan con los tipos. Nota: Este parámetro solo está disponible para solicitudes que incluyen una clave de API o un id. de cliente.
  • location_type: uno o máas tipos de ubicación, separados por una barra vertical (|). Al especificar un tipo, se restringirán los resultados a ese tipo. Si se especifican múltiples tipos, la API devolverá todas las direcciones que coincidan con los tipos. Nota: Este parámetro solo está disponible para solicitudes que incluyen una clave de API o un id. de cliente. Se admiten los siguientes valores:
    • "ROOFTOP" restringe los resultados a direcciones para las que contamos con información de ubicación precisa que puede delimitarse hasta la dirección.
    • "RANGE_INTERPOLATED" restringe los resultados a aquellos que reflejan una aproximación (generalmente en una calle) interpolada entre dos puntos precisos (como intersecciones). La devolución de un rango interpolado generalmente indica que no hay geocódigos exactos disponibles para una dirección.
    • "GEOMETRIC_CENTER" restringe los resultados a centros geométricos de una ubicación como una polilínea (por ejemplo, una calle) o un polígono (región).
    • "APPROXIMATE" restringe los resultados a aquellos que se caracterizan como aproximados.

Si están presentes las restricciones result_type y location_type, la API devolverá solo los resultados que coincidan con las restricciones result_type y location_type.

Geocodificación inversa para una latitud/longitud

La siguiente consulta contiene el valor de latitud/longitud para una ubicación en Brooklyn:

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

Nota: Asegúrate de que no haya espacios entre los valores de latitud y longitud cuando se pasen en el parámetro latlng.

La consulta anterior devuelve el siguiente resultado:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional results[] ...

Ten en cuenta que el geocodificador inverso devolvió más de un resultado. Los resultados "formatted_address" no son solo direcciones postales, sino cualquier forma de denominación geográfica de una ubicación. Por ejemplo, al geocodificar un punto en la ciudad de Chicago, el punto geocodificado puede indicarse como una dirección, como la ciudad (Chicago), como el estado (Illinois) o como un país (Estados Unidos). Para el geocodificador, son todas “direcciones”. El geocodificador inverso devuelve cualquiera de estos tipos como resultados válidos.

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

A continuación se muestra la lista completa de los valores formatted_address devueltos por la consulta anterior.

"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA",
"formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA",
"formatted_address" : "Brooklyn, NY 11211, USA",
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
"formatted_address" : "Brooklyn, NY, USA",
"formatted_address" : "New York, NY, USA",
"formatted_address" : "New York, USA",
"formatted_address" : "United States",

En general, las direcciones se devuelven desde la más específica hasta la menos específica; la dirección más exacta es el resultado más prominente, como en este caso. Ten en cuenta que se devuelven diferentes tipos de direcciones: desde la dirección más específica hasta entidades políticas menos específicas, como vecindarios, ciudades, condados, países, estados, etc. Si quieres establecer una coincidencia con un tipo específico de dirección, consulta la sección Restricción de resultados por tipo a continuación.

Nota: La geocodificación inversa es un cálculo aproximado. El geocodificador intentará hallar la ubicación localizable más cercana dentro de una tolerancia determinada. Si no se encuentran coincidencias, el geocodificador no devolverá resultados.

Geocodificación inversa para un id. de sitio

La siguiente consulta contiene el id. de sitio para una ubicación en Brooklyn:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJd8BlQ2BZwokRAFUEcm_qrcA&key=YOUR_API_KEY

La consulta anterior devuelve el siguiente resultado:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Ave",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality_level_1", "sublocality", "political" ]
            },
            {
               "long_name" : "Kings County",
               "short_name" : "Kings County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

Geocodificación inversa restringida por tipo

El siguiente ejemplo restringe las direcciones devueltas a aquellas con el tipo de ubicación ROOFTOP y un tipo de dirección street_address.

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

Nota: Esas restricciones solo son válidas para la geocodificación inversa.

Respuestas de geocodificación inversa

El formato de la respuesta de geocodificación inversa es el mismo que el de la respuesta de geocodificación. Consulta Respuestas de geocodificación. A continuación se indican los códigos de estado posibles en una respuesta de geocodificación inversa.

Códigos de estado para la geocodificación inversa

El campo "status" en el objeto de la respuesta de geocodificación contiene el estado de la solicitud y podría contener información de depuración para ayudarte a localizar por qué falló la geocodificación inversa. El campo "status" puede contener los siguientes valores:

  • OK indica que no se produjeron errores y que se devolvió, al menos, una dirección.
  • ZERO_RESULTS indica que la geocodificación inversa fue exitosa, pero no devolvió resultados. Esto puede ocurrir si se pasa al geocodificador un valor latlng en una ubicación remota.
  • "OVER_QUERY_LIMIT" indica que excediste tu cuota.
  • "REQUEST_DENIED" indica que se rechazó la solicitud. Posiblemente porque la solicitud incluye un parámetro result_type o location_type, pero no incluye una clave de API o un id. de cliente.
  • "INVALID_REQUEST" generalmente indica una de las siguientes opciones:
    • Falta la solicitud (address, components o latlng).
    • Se proporcionó un result_type o un location_type no válido.
  • "UNKNOWN_ERROR" indica que no se pudo procesar la solicitud por un error en el servidor. La solicitud puede tener éxito si realizas un nuevo intento.

El parámetro sensor

Antes, la Google Maps API requería que incluyeras el parámetro sensor para indicar si tu aplicación usaba un sensor para determinar la ubicación del usuario. El uso de este parámetro ya no es obligatorio.

Enviar comentarios sobre…

Google Maps Geocoding API
Google Maps Geocoding API
¿Necesitas ayuda? Visita nuestra página de asistencia.