Solicitud
Una solicitud a la API de Geocoding tiene el siguiente formato:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
En el ejemplo anterior, outputFormat puede ser cualquiera de los siguientes valores:
json(recomendado) indica el resultado en notación de objetos de JavaScript (JSON). O bien,xmlindica el resultado en XML.
Se requiere HTTPS.
Algunos parámetros son obligatorios y otros opcionales. Tal como es práctica estándar para las URLs,
los parámetros se separan usando el signo et (&).
En el resto de esta página, se describen la geocodificación y la geocodificación inversa por separado, ya que hay diferentes parámetros disponibles para cada tipo de solicitud.
Parámetros de geocodificación (búsqueda de latitud y longitud)
Parámetros obligatorios en una solicitud de geocodificación:
key: Es la clave de API de tu aplicación. Esta clave identifica tu aplicación para administrar la cuota. Obtén información para obtener una clave.Debes especificar
addressocomponents, o ambos, en una solicitud:address: Indica la dirección o el plus code que deseas geocodificar. Nota: La geocodificación de direcciones no resuelve las coordenadas de latitud y longitud ni otras cadenas no estructuradas que no representen una dirección o un Plus Code. No se admiten las solicitudes que usan esas cadenas y pueden generar respuestas de error o un comportamiento no especificado. Estos son algunos ejemplos de consultas no admitidas:
Especifica las direcciones de acuerdo con el formato que usa el servicio postal nacional del país en cuestión. Se deben evitar los elementos de dirección adicionales, como los nombres de las empresas y los números de unidad, suite o piso. Los elementos de la dirección deben estar delimitados por espacios (que aquí se muestran con formato de escape de URL comoTipo de consulta Ejemplo Coordenadas de latitud y longitud En su lugar, usa la geocodificación inversa. "37.422131,-122.084801" Demasiados conceptos o restricciones, como los nombres de varios lugares, rutas o ciudades en una sola búsqueda "Market Street San Francisco San Jose Airport" Elementos de la dirección postal que no se representan en Google Maps "C/O John Smith 123 Main Street"
"P.O. Box 13 San Francisco"Nombres de empresas, cadenas o categorías combinados con ubicaciones en las que estas entidades no están disponibles "Tesco cerca de Dallas, Texas" Consultas ambiguas con varias interpretaciones "Charger drop-off" Nombres históricos que ya no se usan "Middlesex, Reino Unido" Elementos o intención no geoespaciales "¿Cuántos barcos hay en el puerto de Ventura?" Nombres no oficiales o personalizados "The Jenga"
"The Helter Skelter"%20):address=24%20Sussex%20Drive%20Ottawa%20ON
%2By los espacios en%20para que se puedan usar en la URL):- global code: Es un código de área de 4 caracteres y un código local de 6 caracteres o más (849VCWC8+R9 es
849VCWC8%2BR9). - compound code: Es un código local de 6 caracteres o más con una ubicación explícita (CWC8+R9 Mountain View, CA, EE.UU. es
CWC8%2BR9%20Mountain%20View%20CA%20USA).
- global code: Es un código de área de 4 caracteres y un código local de 6 caracteres o más (849VCWC8+R9 es
components: Es un filtro de componentes con elementos separados por una barra vertical (|). El filtro de componentes también se acepta como un parámetro opcional si se proporciona unaddress. Cada elemento del filtro de componentes consta de un parcomponent:valuey restringe por completo los resultados del geocodificador. Obtén más información sobre el filtrado de componentes a continuación.
Consulta las Preguntas frecuentes para obtener más orientación.
Parámetros opcionales en una solicitud de geocodificación:
bounds: Es el cuadro delimitador del viewport en el que se personalizan resultados de geocódigos de forma más prominente. Este parámetro solo influirá en los resultados del geocodificador, pero no los restringirá por completo. (Para obtener más información, consulta la sección Personalización de resultados en función del viewport a continuación).language: Es el idioma en el que se devolverán los resultados.- Consulta la lista de idiomas admitidos. Google suele actualizar los idiomas admitidos, por lo que es posible que esta lista no sea exhaustiva.
- Si no se proporciona
language, el geocodificador intenta usar el idioma preferido, según se especifica en el encabezadoAccept-Language, o el idioma nativo del dominio desde el que se envía la solicitud. - El geocodificador hace todo lo posible para proporcionar una dirección que sea legible tanto para el usuario como para los residentes locales. Para lograr ese objetivo, devuelve las direcciones en el idioma local, transliteradas a una escritura legible para el usuario si es necesario, respetando el idioma preferido. Todas las demás direcciones se devuelven en el idioma preferido. Todos los componentes de la dirección se devuelven en el mismo idioma, que se elige a partir del primer componente.
- Si no hay un nombre disponible en el idioma preferido, el geocodificador usa la coincidencia más cercana.
- El idioma preferido tiene una pequeña influencia en el conjunto de resultados que la API elige mostrar y en el orden en que se muestran. El geocodificador interpreta las abreviaturas de manera diferente según el idioma, como las abreviaturas de los tipos de calles o los sinónimos que pueden ser válidos en un idioma, pero no en otro. Por ejemplo, utca y tér son sinónimos de calle y plaza, respectivamente, en húngaro.
region: Es el código de región, que se indica como un valor ccTLD ("dominio de nivel superior") de dos caracteres. Este parámetro solo influirá en los resultados del geocodificador, pero no los restringirá por completo. (Para obtener más información, consulta la sección Personalización de resultados en función de la región a continuación). El parámetro también puede afectar los resultados según la ley aplicable.components: Es un filtro de componentes con elementos separados por una barra vertical (|). El filtro de componentes es obligatorio si la solicitud no incluye unaddress. Cada elemento del filtro de componentes consta de un parcomponent:valuey restringe por completo los resultados del geocodificador. Obtén más información sobre el filtrado de componentes a continuación.extra_computations: Usa este parámetro para especificar las siguientes funciones adicionales en la respuesta:ADDRESS_DESCRIPTORS: Consulta descriptores de direcciones para obtener más detalles.BUILDING_AND_ENTRANCES: Consulta Entradas y contornos de edificios para obtener más detalles.
extra_computationsen la solicitud para cada función, por ejemplo:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
Respuestas
Las respuestas de la geocodificación se devuelven en el formato indicado por la marca output
dentro de la solicitud de URL o en formato JSON de forma predeterminada.
En este ejemplo, la API de Geocoding solicita una respuesta en formato json para una consulta sobre la dirección "1600 Amphitheatre Parkway, Mountain View, CA".
En esta solicitud, se muestra cómo usar la marca JSON output:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
En esta solicitud, se muestra cómo usar la marca output de XML:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Selecciona las pestañas que aparecen a continuación para ver las respuestas de ejemplo en formato JSON y XML.
JSON
{ "results": [ { "address_components": [ { "long_name": "1600", "short_name": "1600", "types": [ "street_number" ] }, { "long_name": "Amphitheatre Parkway", "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" ] }, { "long_name": "1351", "short_name": "1351", "types": [ "postal_code_suffix" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4222804, "lng": -122.0843428 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4237349802915, "lng": -122.083183169709 }, "southwest": { "lat": 37.4210370197085, "lng": -122.085881130292 } } }, "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8", "plus_code": { "compound_code": "CWC8+W7 Mountain View, CA", "global_code": "849VCWC8+W7" }, "types": [ "street_address" ] } ], "status": "OK" }
Ten en cuenta que la respuesta JSON contiene dos elementos raíz:
"status"contiene metadatos sobre la solicitud. Consulta los códigos de estado que se indican a continuación."results"contiene un array de información de direcciones geocodificadas y de geometría.
Por lo general, solo se muestra una entrada en el array "results" para las búsquedas de direcciones, aunque el geocodificador puede mostrar varios resultados cuando las búsquedas de direcciones son ambiguas.
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 Parkway</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>Santa Clara County</long_name> <short_name>Santa Clara County</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.4224428</lat> <lng>-122.0842467</lng> </location> <location_type>ROOFTOP</location_type> <viewport> <southwest> <lat>37.4212648</lat> <lng>-122.0856069</lng> </southwest> <northeast> <lat>37.4239628</lat> <lng>-122.0829089</lng> </northeast> </viewport> </geometry> <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id> <plus_code> <global_code>849VCWC8+X8</global_code> <compound_code>CWC8+X8 Mountain View, CA</compound_code> </plus_code> </result> </GeocodeResponse>
Ten en cuenta que la respuesta XML consta de un solo elemento <GeocodeResponse> y dos elementos de nivel superior:
<status>contiene metadatos sobre la solicitud. Consulta los códigos de estado que se indican a continuación.- Cero o más elementos
<result>, cada uno de los cuales contiene un solo conjunto de información de dirección geocodificada y de geometría.
La respuesta XML es considerablemente más larga que la respuesta JSON. Por
ese motivo, te recomendamos que uses json como la marca de salida
preferida, a menos que tu servicio requiera xml por algún motivo.
Además, el procesamiento de árboles XML requiere cierto cuidado para que hagas referencia a los nodos y elementos adecuados. Consulta
Análisis de XML con XPath para conocer algunos patrones de diseño recomendados para el procesamiento de resultados.
- Los resultados XML se unen en un elemento raíz
<GeocodeResponse>. - JSON denota entradas con varios elementos por arrays plurales (
types), mientras que XML las denota con varios elementos singulares (<type>). - Los elementos en blanco se indican a través de arrays vacíos en JSON, pero por la ausencia de cualquier
elemento de ese tipo en XML. Por ejemplo, una respuesta que no genera resultados devolverá un array
resultsvacío en JSON, pero no elementos<result>en XML.
Códigos de estado
El campo "status" del objeto de respuesta de Geocoding contiene el estado de la solicitud y puede incluir información de depuración para ayudarte a identificar el motivo por el que no funciona la geocodificación. El campo "status" puede contener 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 valoraddressinexistente al geocodificador.OVER_DAILY_LIMITindica cualquiera de los siguientes elementos:- Falta la clave de API o no es válida.
- No se habilitó la facturación en tu cuenta.
- Se superó un límite de uso autoimpuesto.
- La forma de pago proporcionada ya no es válida (por ejemplo, venció una tarjeta de crédito).
Consulta las Preguntas frecuentes sobre Maps para obtener información sobre cómo corregir este problema.
"OVER_QUERY_LIMIT"indica que superaste tu cuota."REQUEST_DENIED"indica que se rechazó tu solicitud."INVALID_REQUEST"suele indicar que falta la consulta (address,componentsolatlng)."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.
Mensajes de error
Cuando el geocodificador devuelve un código de estado que no es OK, es posible que haya un campo error_message adicional dentro del objeto de respuesta de Geocoding. Este
campo contiene información más detallada sobre los motivos del código de estado
proporcionado.
Resultados
Cuando el geocodificador devuelve resultados, los coloca dentro de un array results (JSON). Incluso si el geocodificador no devuelve resultados (por ejemplo, si la dirección no existe), devuelve un array results vacío. (Las respuestas XML constan de cero o más elementos <result>).
Un resultado típico contiene los siguientes campos:
- El array
types[]indica el tipo del resultado que se muestra. Este array incluye un conjunto de cero o más 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. Para obtener más información, consulta Tipos de dirección y tipos de componentes de dirección. formatted_addresses 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. El componente de dirección puede tener un array de tipos vacío cuando no hay tipos conocidos para ese componente de dirección. La API puede agregar valores de tipo nuevos según sea necesario. Para obtener más información, consulta Tipos de dirección y tipos de componentes de dirección.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 unlong_namede "Alaska" y unshort_namede "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_componentsvarí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.
Para controlar el array de componentes, debes analizar la respuesta y seleccionar los valores adecuados a través de expresiones. Consulta la guía para analizar una respuesta.
postcode_localities[]es un array que denota hasta 100 localidades incluidas en un código postal. Solo aparece cuando el resultado es un código postal que contiene varias localidades.geometrycontiene la siguiente información:locationcontiene los valores de latitud y longitud geocodificados. Para las búsquedas de direcciones normales, este campo suele ser el más importante.location_typealmacena datos adicionales sobre la ubicación especificada. Actualmente, se admiten los siguientes valores:"ROOFTOP"indica que el resultado que se muestra es un geocódigo preciso para el que tenemos información de ubicación exacta hasta el nivel de dirección."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.
viewportcontiene el viewport recomendado para mostrar el resultado, especificado como dos valores de latitud y longitud que definen las esquinassouthwestynortheastdel cuadro delimitador del viewport. Por lo general, el viewport se usa para enmarcar un resultado cuando se muestra a un usuario.bounds(se muestra de manera opcional) abarca el cuadro delimitador 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 probablemente no se deben mostrar en el viewport).
-
plus_code(consulta Código de ubicación abierto y Plus Codes): Es una referencia de ubicación codificada, derivada de las coordenadas de latitud y longitud, que representa un área: 1/8,000 de un grado por 1/8,000 de un grado (aproximadamente 14 m x 14 m en el Ecuador) o menos. 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). La API no siempre devuelve Plus Codes.Cuando el servicio devuelve un Plus Code, este tiene el formato de un código global y un código compuesto:
global_code: Es un código de área de 4 caracteres y un código local de 6 caracteres o más (849VCWC8+R9).compound_code: Es un código local de 6 caracteres o más con una ubicación explícita (CWC8+R9, Mountain View, CA, EE.UU.). No analices este contenido de forma programática.
-
partial_matchindica 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_ides un identificador único que se puede usar con otras APIs de Google. Por ejemplo, puedes usar elplace_iden una solicitud a la API de 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.
Tipos de dirección y tipos de componentes de dirección
El array types en la respuesta indica el
tipo de dirección. Entre los ejemplos de tipos de direcciones, se incluyen una dirección, un país o una entidad política. El array types en el campo address_component indica el tipo de cada parte de la dirección. Los ejemplos incluyen el número de una calle o el país.
Las direcciones pueden tener múltiples tipos. Los tipos se pueden considerar "etiquetas".
Por ejemplo, muchas ciudades están etiquetadas con los tipos political y
locality.
Los siguientes tipos se admiten y se devuelven en los arrays de tipo de dirección y de tipo de componente de dirección:
| Tipo de dirección | Descripción |
|---|---|
street_address |
Una dirección precisa. |
route |
Una ruta designada (como "US 101"). |
intersection |
Es una intersección principal, generalmente de dos rutas principales. |
political |
Es 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 civil de tercer rango 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 civil de cuarto rango 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 |
Un nombre alternativo de uso general para la entidad. |
locality |
Indica una entidad política constituida como ciudad o pueblo. |
sublocality |
Indica una entidad civil de primer rango 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 |
Es 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 establecimiento, como un departamento, una unidad o una suite. |
plus_code |
Es 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 |
Un componente natural destacado. |
airport |
Un aeropuerto. |
park |
Indica un parque con nombre. |
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.
| Tipo de componente de dirección | Descripción |
|---|---|
floor |
Es el piso de la dirección de un edificio. |
establishment |
Suele ser un lugar que aún no se categorizó. |
landmark |
Es un lugar cercano que se usa como referencia para facilitar la navegación. |
point_of_interest |
Indica un lugar de interés designado. |
parking |
Un estacionamiento o una estructura de estacionamiento. |
post_box |
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 |
Es la habitación de la dirección de un edificio. |
street_number |
Es el número exacto de una calle. |
bus_station, train_station y transit_station |
La ubicación de una parada de autobús, tren o transporte público. |
Personalización de viewports
En una solicitud de geocodificación, puedes dar instrucciones al servicio de Geocoding para que anteponga ciertos resultados dentro de un viewport determinado (expresado como un cuadro delimitador). Para ello,
configura el parámetro bounds en la URL de la solicitud.
El parámetro bounds define las coordenadas de latitud y longitud
de las esquinas sudoeste y noreste de este cuadro delimitador con una barra vertical
(|) para separar las coordenadas.
Por ejemplo, un geocódigo de "Washington" generalmente muestra el estado de Washington, en EE.UU.:
Solicitud:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
Respuesta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
Sin embargo, cuando se agrega un argumento bounds que define un cuadro delimitador alrededor de la parte noreste de EE.UU., se obtiene como resultado un geocódigo que muestra la ciudad de Washington, D.C.:
Solicitud:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
Respuesta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Personalización de regiones
En una solicitud de Geocoding, puedes indicar al servicio Geocoding que devuelva
resultados personalizados para una región en particular con el parámetro
region. Este parámetro toma un argumento ccTLD (dominio de nivel superior con código de país) que especifica la preferencia de 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 ccTLD del Reino Unido es "uk" (.co.uk), mientras que su código ISO 3166-1 es "gb" (técnicamente para la entidad "Reino Unido de Gran Bretaña e Irlanda del Norte").
Los resultados de la geocodificación se pueden personalizar para cada dominio en el que se lance oficialmente la aplicación principal de Google Maps. 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 la API de Geocoding se establece 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.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Una solicitud de Geocoding para "Toledo" con region=es (España) devolverá la ciudad española.
Solicitud:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
Respuesta:
{
"results" : [
{
"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" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Filtrado de componentes
En una respuesta de Geocoding, la API de Geocoding puede devolver
resultados de direcciones restringidos a un área específica. Puedes especificar la restricción
con el filtro components. Un filtro consiste en una lista de pares component:value separados por una barra vertical (|). Los valores de filtros admiten los mismos métodos de corrección ortográfica y coincidencia parcial que otras solicitudes de geocodificación. Si el geocodificador encuentra una coincidencia parcial para un filtro de componentes, la respuesta contendrá un campo partial_match.
Los components que se pueden filtrar incluyen los siguientes:
postal_codecoincide conpostal_codeypostal_code_prefix.countryestablece coincidencias con un nombre de país o con un código de país ISO 3166-1 de dos letras. 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.
Los siguientes components se pueden usar para influir en los resultados, pero no se
aplicarán:
routeestablece coincidencias con el nombre largo o corto de una ruta.localityestablece coincidencias con los tiposlocalityysublocality.administrative_areaestablece coincidencias con todos los niveles deadministrative_area.
Notas sobre el filtrado de componentes:
- No repitas estos filtros de componentes en las solicitudes, o la API devolverá
Invalid_request:country,postal_code,route - Si la solicitud contiene filtros de componentes repetidos, la API evalúa esos filtros como un operador AND, no como un operador OR.
- Los resultados son coherentes con Google Maps, que, en ocasiones, genera respuestas
ZERO_RESULTSinesperadas. Usar Place Autocomplete puede proporcionar mejores resultados en algunos casos de uso. Para obtener más información, consulta estas preguntas frecuentes. - Para cada componente de dirección, especifícalo en el parámetro
addresso en un filtrocomponents, pero no en ambos. Especificar los mismos valores en ambos puede generar unZERO_RESULTS.
Un geocódigo de "High St, Hastings" con components=country:GB devuelve un resultado
en Hastings, Inglaterra, en lugar de Hastings-On-Hudson, EE.UU.
Solicitud:
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
Respuesta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
Una solicitud de geocodificación para la localidad de "Santa Cruz" con components=country:ES devuelve Santa Cruz de Tenerife en las Islas Canarias, España.
Solicitud:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|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" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "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"
}
El filtrado de componentes devuelve una respuesta ZERO_RESULTS solo si proporcionas
filtros que se excluyen 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"
}
Puedes realizar consultas válidas sin el parámetro de dirección con el filtro
components. (Cuando se geocodifica una dirección completa, el parámetro address es obligatorio si
la solicitud contiene los nombres y números de los edificios).
Solicitud:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
Respuesta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}