Solicitud
Una solicitud de Geocoding API debe respetar la siguiente forma:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
donde outputFormat puede ser cualquiera de los siguientes valores:
json(recomendado) indica el formato de salida en JavaScript Object Notation (JSON).xmlindica el resultado en XML.
Se requiere HTTPS para las solicitudes que usan una clave de API.
Algunos parámetros son obligatorios y otros opcionales. Como es norma en las URL, los parámetros se separan con el carácter de Y comercial (&).
En el resto de esta página, se describe la codificación geográfica y la codificación geográfica inversa por separado, ya que hay diferentes parámetros disponibles para cada tipo de solicitud.
Parámetros de geocodificación (búsqueda de latitud/longitud)
Parámetros obligatorios en una solicitud de geocodificación:
address: Es la dirección o el código plus que deseas geocodificar. Especifica las direcciones de acuerdo con 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 unidades, pisos o unidades. Los elementos de dirección deben estar delimitados por espacios (que se muestran aquí con escape de URL a%20):address=24%20Sussex%20Drive%20Ottawa%20ON
- 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). - El código compuesto 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).
--OR--
components: Filtro de componentes con elementos separados por una barra vertical (|). El filtro de componentes también se acepta como parámetro opcional si se proporciona un address.
Cada elemento del filtro de componentes consta de un par component:value y restringe por completo los resultados del geocodificador. Obtén más información sobre el filtrado de componentes a continuación.
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. Obtén información sobre cómo obtener una clave.
Consulta las Preguntas frecuentes para obtener orientación adicional.
Parámetros opcionales en una solicitud de geocodificación:
bounds: Es el cuadro de límite del viewport dentro del que se restringirán los resultados de geocódigos de manera más destacada. Este parámetro solo afectará, pero no restringirá por completo, los resultados del geocodificador. (Para obtener más información, consulta la Personalización de viewports a continuación).language: el idioma en el que se muestran los resultados.- Consulta la lista de idiomas admitidos. Google suele actualizar los idiomas admitidos, por lo que es posible que esta lista no sea completa.
- Si no se proporciona el
language, el geocodificador intenta usar el idioma preferido especificado en el encabezadoAccept-Languageo el idioma nativo del dominio desde el que se envió la solicitud. - El geocodificador hace todo lo posible para proporcionar una dirección legible tanto para los usuarios como para los usuarios locales. Para lograr ese objetivo, muestra las direcciones en el idioma local, transliteradas en una secuencia de comandos que el usuario puede leer, si es necesario, y observan el idioma preferido. Todas las demás direcciones se muestran en el idioma preferido. Todos los componentes de dirección se muestran en el mismo idioma, que se selecciona desde el primer componente.
- Si un nombre no está disponible en el idioma preferido, el geocodificador usa la coincidencia más cercana.
- El lenguaje preferido tiene una pequeña influencia en el conjunto de resultados que la API elige mostrar y el orden en el que se muestran. El geocodificador interpreta las abreviaturas de manera diferente según el idioma, como las abreviaturas para 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 cuadrado", respectivamente, en húngaro.
region: Es el código de región, especificado 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). 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 canalización (|). 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.
Respuestas
Las respuestas de geocodificación se muestran 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 json para una consulta en el ID de lugar "ChIJeRpOeF67j4AR9ydy_PIzPuM". Este ID de lugar corresponde al edificio ubicado en 1600 Amphitheatre Parkway, Mountain View, CA.
Esta solicitud muestra cómo usar la marca output de JSON:
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
En esta solicitud, se muestra cómo usar la marca XML output:
https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
Selecciona las pestañas a continuación para ver las respuestas JSON y XML de muestra.
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"
]
}
],
"formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
"geometry": {
"location": {
"lat": 37.4224428,
"lng": -122.0842467
},
"location_type": "ROOFTOP",
"viewport": {
"northeast": {
"lat": 37.4239627802915,
"lng": -122.0829089197085
},
"southwest": {
"lat": 37.4212648197085,
"lng": -122.0856068802915
}
}
},
"place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
"plus_code": {
"compound_code": "CWC8+X8 Mountain View, CA",
"global_code": "849VCWC8+X8"
},
"types": [
"street_address"
]
}
],
"status": "OK"
}
Ten en cuenta que una respuesta JSON contiene dos elementos principales:
"status"contiene metadatos sobre la solicitud. Consulta Códigos de estado a continuación."results"contiene un array de información de direcciones geocodificadas e información sobre geometría.
Por lo general, solo se muestra una entrada en el array de "results" para las búsquedas de direcciones,aunque el geocodificador puede mostrar varios resultados cuando las consultas de dirección sean 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 una sola <GeocodeResponse> y dos elementos de nivel superior:
<status>contiene metadatos sobre la solicitud. Consulta Códigos de estado a continuación.- Cero o más elementos
<result>, cada uno con un solo conjunto de información sobre dirección geográfica y geometría.
La respuesta XML es considerablemente más larga que la respuesta JSON. Por esa razón, te recomendamos que uses json como la marca de resultado preferida, a menos que tu servicio 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
Cómo analizar XML con XPath para obtener información sobre algunos de los patrones de diseño recomendados para el procesamiento del resultado.
- Los resultados XML se unen con un elemento raíz
<GeocodeResponse>. - JSON denota entradas con varios elementos mediante arreglos de plural (
types), mientras que XML las denota mediante varios elementos en singular (<type>). - Los elementos en blanco se indican mediante arreglos vacíos en JSON, pero mediante la ausencia de un elemento como este en XML. Una respuesta que no genera resultados mostrará un arreglo
resultsvacío en JSON, pero no mostrará elementos<result>en XML, por ejemplo.
Códigos de estado
El campo "status" dentro del objeto de respuesta de Geocoding contiene el estado de la solicitud y puede contener información de depuración para ayudarte a identificar por qué 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 código geográfico."ZERO_RESULTS"indica que el código geográfico era correcto, pero no mostró resultados. Esto puede ocurrir si se pasó un valoraddressinexistente al geocodificador.OVER_DAILY_LIMITindica lo siguiente:- Falta la clave de API o no es válida.
- No se habilitó la facturación en tu cuenta.
- Se excedió el límite de uso autoimpuesto.
- La forma de pago proporcionada ya no es válida (por ejemplo, si venció una tarjeta de crédito).
Consulta las Preguntas frecuentes sobre Maps para obtener información sobre cómo solucionar 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 búsqueda (address,componentsolatlng)."UNKNOWN_ERROR": Indica que no se pudo procesar la solicitud debido a un error del servidor. La solicitud puede ser exitosa si realizas un nuevo intento.
Mensajes de error
Cuando el geocodificador muestra un código de estado distinto de OK, es posible que haya un campo error_message adicional en el objeto de respuesta de Geocoding. Este campo contiene información más detallada sobre los motivos que subyacen al código de estado dado.
Resultados
Cuando el geocodificador muestra resultados, los ubica en un arreglo results (JSON). Incluso si el geocodificador no muestra resultados (por ejemplo, si la dirección no existe), muestra un arreglo results vacío. (Las respuestas XML consisten en cero o más elementos <result>).
Un resultado típico contiene los siguientes campos:
- El arreglo
types[]indica el tipo de resultado que se muestra. Este arreglo contiene un conjunto de cero o más etiquetas que identifican el tipo de función que se muestra en el resultado. Por ejemplo, un geocódigo “Chicago” muestra “localidad”, que indica que “Chicago” es una ciudad, y también muestra “político”, que indica que es una entidad política. Los componentes pueden tener un arreglo de tipos vacíos cuando no hay tipos conocidos para ese componente de dirección. La API puede agregar nuevos valores de tipo según sea necesario. Para obtener más información, consulta los tipos de dirección y los componentes de la dirección. formatted_addresses una string que contiene la dirección de esta ubicación en lenguaje natural.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 de forma 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 aplicables a esta dirección.Por lo general, cada componente de la dirección incluye los siguientes campos:
types[]: Es un array que indica el tipo de componente de la dirección. Consulta la lista de tipos admitidos.long_name: Es la descripción textual completa o el nombre del componente de la dirección que muestra el geocodificador.short_name: Es un nombre textual abreviado para el componente de la dirección, si está disponible. Por ejemplo, un componente de dirección para el estado de Alaska puede tener 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 arreglo de componentes, debes analizar la respuesta y seleccionar los valores adecuados mediante expresiones. Consulta la guía para analizar una respuesta.
postcode_localities[]: Es un array que denota todas las localidades que contiene un código postal. Solo está presente cuando el resultado es un código postal que contiene varias localidades.geometrycontiene la siguiente información:location: Contiene 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 la ubicación precisa hasta la precisión de la 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). Por lo general, los resultados interpolados se muestran cuando los geocódigos exactos no están disponibles para una dirección."GEOMETRIC_CENTER"indica que el resultado que se muestra es el centro geométrico de un resultado como una polilínea (por ejemplo, una calle) o un polígono (región)."APPROXIMATE"indica que el resultado que se muestra es aproximado.
viewportcontiene el viewport recomendado para mostrar el resultado que se muestra, especificado como dos valores de latitud y longitud que definen las esquinassouthwestynortheastdel cuadro de límite del viewport. Por lo general, el viewport se usa para enmarcar un resultado cuando se lo muestra al usuario.bounds(opcional) muestra el cuadro de límite que puede contener por completo el resultado mostrado. Ten en cuenta que es posible que estos límites no coincidan con el viewport recomendado. (Por ejemplo, San Francisco incluye las islas Farallón, que técnicamente son parte de la ciudad, pero es probable que no se muestren en el viewport).
-
plus_code(consulta Código de ubicación abierto y Más códigos) es una referencia de ubicación codificada, derivada de coordenadas de latitud y longitud, que representa un área: 1/8000 de un grado por 1/8000 de 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 muestra los códigos plus.Cuando el servicio muestra un código plus, tiene el formato de un código global y un código compuesto:
global_codees un código de área de 4 caracteres y un código local de 6 caracteres o más (849VCWC8+R9).compound_codees 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 o que la dirección no esté incompleta.Las coincidencias parciales generalmente ocurren cuando las direcciones no existen en la localidad que pasas en la solicitud. También se pueden obtener coincidencias parciales cuando una solicitud coincide 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 un error ortográfico en un componente de la dirección, 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 API de Google. Por ejemplo, puedes usarplace_iden una solicitud de 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 de los IDs de lugar.
Tipos de dirección y componentes de dirección
El arreglo types[] en el resultado 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. También hay un array 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 muestra una lista completa de los tipos. Las direcciones pueden tener múltiples tipos. Los tipos se pueden considerar "etiquetas".
Por ejemplo, muchas ciudades tienen la etiqueta political y locality.
El geocodificador admite y muestra los siguientes tipos en las matrices de tipos de dirección y de tipo de componente de dirección:
street_address: Indica una dirección precisa.route: Indica una ruta con nombre (como "US 101").intersection: Indica una intersección principal, generalmente de dos rutas principales.political: Indica una entidad política. 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 rango más alto que muestra el geocodificador.administrative_area_level_1: Indica una entidad civil de primer rango 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 están basados en diferentes indicadores y datos de ubicación.administrative_area_level_2: Indica una entidad civil de segundo rango 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 civil 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 civil inferior. No todos los países poseen estos niveles administrativos.administrative_area_level_5: Indica una entidad civil de quinto rango por debajo del nivel de país. Este tipo indica una división civil inferior. No todos los países poseen estos niveles administrativos.administrative_area_level_6: Indica una entidad civil de sexto rango por debajo del nivel de país. Este tipo indica una división civil inferior. No todos los países poseen estos niveles administrativos.administrative_area_level_7: Indica una entidad civil de séptimo rango 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 general para la entidad.locality: Indica una entidad política integrada en una ciudad o un 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_1asublocality_level_5. Cada nivel de sublocalidad es una entidad civil. Los números más altos indican áreas geográficas más pequeñas.neighborhood: Indica un área residencial con nombre.premise: Indica una ubicación determinada, generalmente un edificio o un conjunto de edificios con un nombre común.subpremise: Indica una entidad de primer rango por debajo de una ubicación determinada, generalmente, un edificio único dentro de un conjunto de edificios con un nombre común.plus_code: Indica una referencia de una ubicación codificada, derivada de las coordenadas de latitud y 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). Consulta https://plus.codes para obtener más información.postal_code: Indica un código postal, tal como se usa en las direcciones postales dentro del país.natural_feature: Indica una formación natural destacada.airport: Indica un aeropuerto.park: Indica un parque determinado.point_of_interest: Indica un lugar de interés determinado. Por lo general, estos "lugares de interés" son entidades locales destacadas que no concuerdan fácilmente con 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 anteriormente, los componentes de dirección pueden incluir los tipos enumerados aquí. Esta lista no es exhaustiva y está sujeta a cambios.
floor: Indica el piso de la dirección de un edificio.establishment: Suele indicar un lugar que aún no se categorizó.landmark: Indica un lugar cercano que se usa como referencia para facilitar la navegación.point_of_interest: Indica un lugar de interés determinado.parking: Indica un estacionamiento o una estructura de estacionamiento.post_box: Indica una casilla de correo postal específica.postal_town: Indica un grupo de áreas geográficas, comolocalityysublocality, que se usan para las direcciones de correo postal en algunos países.room: Indica una sala en una dirección de un edificio.street_number: Indica el número exacto de una calle.bus_station,train_stationytransit_station: Indican 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 indicarle al servicio de geocodificación que prefiera los resultados dentro de un viewport determinado (expresado como un cuadro de límite). Para ello, debes configurar la configuración del 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 de límite mediante un carácter de barra vertical (|) para separar las coordenadas.
Por ejemplo, un geocódigo para “Washington” generalmente devuelve 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 de límite en la parte noreste de EE.UU., este geocódigo 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"
}
Restricción de regiones
En una solicitud de geocodificación, puedes indicarle al servicio de geocodificación que muestre resultados restringidos a una región en particular mediante el parámetro region. Este parámetro toma un argumento ccTLD (dominio de nivel superior de código de país) que especifica el sesgo 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 de "Reino Unido de Gran Bretaña e Irlanda del Norte").
Se pueden restringir los resultados de la geocodificación para cada dominio en el que se inicie oficialmente la aplicación principal de Google Maps. Ten en cuenta que la personalización solo da preferencia a los resultados correspondientes a un dominio específico. Si hubiera más resultados relevantes fuera de este dominio, podrían incluirse.
Por ejemplo, un geocódigo para “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 geocodificación para "Toledo" con region=es (España) mostrará la ciudad de España.
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 mostrar 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 filtro admiten los mismos métodos de corrección ortográfica y coincidencia parcial que otras solicitudes de Geocoding. Si el geocodificador encuentra una coincidencia parcial para un filtro de componente, la respuesta contendrá un campo partial_match.
Entre los components que se pueden filtrar, se incluyen los siguientes:
postal_codecoincide conpostal_codeypostal_code_prefix.country: Establece 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 países, y el filtrado funciona mejor cuando se usa el código ISO correspondiente del país.
Se puede usar la siguiente components para influir en los resultados, pero no se aplicarán de manera forzosa:
routecoincide con el nombre largo o corto de una ruta.localitycoincide con los tiposlocalityysublocality.administrative_areacoincide con todos los niveles deadministrative_area.
Notas sobre el filtrado de componentes:
- No repitas estos filtros de componentes en solicitudes; de lo contrario, la API mostrará
Invalid_request:country,postal_code,route - Si la solicitud contiene filtros de componentes repetidos, la API evalúa esos filtros como AND, no como OR.
- Los resultados son coherentes con Google Maps, que a veces produce respuestas
ZERO_RESULTSinesperadas. El uso de Place Autocomplete puede proporcionar mejores resultados en algunos casos prácticos. 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 ambos. Especificar los mismos valores en ambos puede dar como resultadoZERO_RESULTS.
Un geocódigo para “High St, Hastings” con components=country:GB muestra un resultado en Hastings, Inglaterra, en lugar de en 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 geocódigo para la localidad de "Santa Cruz" con components=country:ES muestra 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 muestra una respuesta ZERO_RESULTS solo si proporcionas filtros que se excluyen mutuamente.
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 mediante el filtro components. (Cuando se realiza la geocodificación de una dirección completa, se requiere el parámetro address si la solicitud contiene los nombres y la cantidad de 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"
}