Solicitud
Una solicitud a la API de Geocoding 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). oxml
indica el formato de salida en XML.
Se requiere HTTPS.
Algunos parámetros son obligatorios y otros opcionales. Como es norma en las URLs,
se separan con el carácter et (&
).
En el resto de esta página, se describe la geocodificación geocodificación inversa por separado porque hay disponibles parámetros diferentes 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:
address
: Indica la dirección o el Plus Code. que quieres geocodificar. Especifica las direcciones según el formato utilizado por el servicio nacional de correos del país en cuestión. Adicional elementos de dirección, como nombres de empresas y números de unidad, habitación o piso y se deben evitar las prácticas recomendadas. Los elementos de dirección deben estar delimitados por espacios (se muestra aquí como URL con caracteres de escape a%20
): Aplica formato a los Plus Codes como se muestra aquí (los signos más tienen el formato de escape de URLaddress=24%20Sussex%20Drive%20Ottawa%20ON
%2B
y los espacios tienen el formato de escape de URL a%20
):- Un código global es un código de área de 4 caracteres y de 6 caracteres o más
código local (849VCWC8+R9 es
849VCWC8%2BR9
). - Un código compuesto es un código local de 6 caracteres o más con el
ubicación explícita (CWC8+R9 Mountain View, CA, EE.UU. es
CWC8%2BR9%20Mountain%20View%20CA%20USA
).
--OR--
components
: Es un filtro de componentes con elementos. separadas por una canalización (|
). También se acepta el filtro de componentes como parámetro opcional si se proporciona unaddress
. Cada elemento del filtro de componentes consta de uncomponent:value
y restringe por completo los resultados del geocodificador. Obtén más información sobre filtrado de componentes a continuación.- Un código global es un código de área de 4 caracteres y de 6 caracteres o más
código local (849VCWC8+R9 es
key
: Es la clave de API de tu aplicación. Esta clave identifica tu aplicación para la administración de cuotas. Aprende a hacer lo siguiente: obtener una clave.
Consulta las Preguntas frecuentes para orientación adicional.
Parámetros opcionales en una solicitud de Geocoding:
bounds
: Es el cuadro de límite del viewport. dentro de los cuales sesgará los resultados de geocódigo de manera más prominente. Este parámetro solo influyen, no restringen por completo, los resultados del geocodificador. (Para obtener más para obtener más información, consulta Personalización de viewports a continuación).language
: Es el idioma en el que se devolver resultados.- Consulta la lista de sitios web idiomas. Google actualiza con frecuencia los idiomas admitidos, así que puede no ser exhaustiva.
- Si no se proporciona
language
, el geocodificador intenta usar el idioma de preferencia que se especifica en el encabezadoAccept-Language
o el idioma nativo del el dominio desde el que se envía la solicitud. - El geocodificador se encarga de proporcionar una dirección legible tanto para el usuario como para los locales. Para lograr ese objetivo, devuelve direcciones en el idioma local, transliteradas al de secuencia de comandos legible por el usuario si es necesario, respetando la idioma. Todas las demás direcciones se devuelven en la forma idioma. Los componentes de la dirección se devuelven en el mismo idioma. que se elige del primer componente.
- Si un nombre no está disponible en el idioma preferido, el geocodificador usa la coincidencia más cercana.
- El idioma preferido influye poco en el conjunto de resultados que que la API elige devolver y el orden en el que se muestran. El geocodificador interpreta las abreviaturas de manera diferente según como las abreviaturas para los tipos de calle, 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 cuadrada, respectivamente. en húngaro.
region
: Es el código de región, especificado como ccTLD. ("dominio de nivel superior") de dos caracteres. Este parámetro solo no restringen por completo los resultados del geocodificador. (Para obtener más para obtener más información, consulta Personalización de la región a continuación). El también puede afectar los resultados según la ley aplicable.components
: Es un filtro de componentes con elementos. separadas por una canalización (|
). El filtro de componentes Es obligatorio si la solicitud no incluye unaddress
. Cada elemento del filtro de componentes consta de uncomponent:value
y restringe por completo los resultados del geocodificador. Obtén más información sobre filtrado de componentes a continuación.extra_computations
: Usa este parámetro para especificar la las siguientes funciones adicionales en la respuesta:ADDRESS_DESCRIPTORS
— Ver descriptores de dirección para obtener más información.BUILDING_AND_ENTRANCES
— Ver entradas y esquemas de los edificios para obtener más detalles.
extra_computations
en la solicitud de cada función. por ejemplo:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
Respuestas
Las respuestas de Geocoding 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 json
respuesta para una consulta sobre la dirección "1600 Amphitheatre Parkway, Mountain View,
“CA”.
En esta solicitud, se muestra el uso de la marca output
JSON:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
En esta solicitud, se muestra el uso de 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 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" ] }, { "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 una respuesta JSON contiene dos elementos principales:
"status"
contiene metadatos sobre la solicitud. Consulta Consulta los códigos de estado que aparecen a continuación."results"
contiene un array de información sobre direcciones geocodificadas. información geométrica.
Por lo general, solo se muestra una entrada en el array "results"
para
búsquedas de direcciones, aunque el geocodificador puede devolver varios resultados cuando la dirección
las consultas 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
<GeocodeResponse>
y dos elementos de nivel superior:
<status>
contiene metadatos sobre la solicitud. Consulta Consulta los códigos de estado que aparecen a continuación.- Cero o más elementos
<result>
, cada uno con un único conjunto de información sobre geometría y direcciones geocodificadas.
La respuesta XML es considerablemente más larga que la respuesta JSON. Para
por ese motivo, te recomendamos que uses json
como la fuente
salida, a menos que tu servicio requiera xml
por algún motivo.
Además, el procesamiento de árboles XML requiere cierto cuidado, de modo que puedas hacer 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 mediante arrays en plural (
types
), mientras que XML los denota mediante varios elementos singulares (<type>
). - Los elementos en blanco se indican mediante arrays vacíos en JSON, pero ante la ausencia de
elemento en XML. Una respuesta que no genera resultados mostrará un mensaje
Array
results
en JSON, pero no elementos<result>
en XML. por ejemplo.
Códigos de estado
El campo "status"
del objeto de la respuesta de Geocoding contiene el estado.
de la solicitud y puede contener información de depuración para ayudarte a localizar por qué se aplica
no funciona. 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 valoraddress
inexistente al geocodificador.OVER_DAILY_LIMIT
indica alguna de las siguientes opciones:- 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, una la tarjeta de crédito ha caducado).
Consulta las Preguntas frecuentes de Maps para obtener información 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 consulta (address
,components
olatlng
)."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 distinto de OK
, puede haber un código
Campo error_message
en el objeto de respuesta de Geocoding. Este campo contiene más
información detallada sobre los motivos del código de estado proporcionado.
Resultados
Cuando el geocodificador muestra resultados, los ubica en un results
(JSON)
. Incluso si el geocodificador no devuelve resultados (por ejemplo, si la dirección no existe), sigue
muestra un array results
vacío. (Las respuestas XML consisten en cero o más
<result>
elements.)
Un resultado típico contiene los siguientes campos:
- El array
types[]
indica el tipo de lo que se muestra resultado. Este array contiene un conjunto de cero o más etiquetas que identifican el tipo de atributo mostrado en el resultado. Por ejemplo, un geocódigo de “Chicago” devoluciones "localidad" lo que indica que “Chicago” es una ciudad, y también devuelve "política" lo que indica que es una entidad política. Los componentes pueden tener un tipo vacío cuando no existen tipos conocidos para ese componente de dirección. La API podría agregar nuevos valores de tipo según sea necesario. Para obtener más información, consulta Tipos de direcciones y componentes de las direcciones. formatted_address
es una cadena que contiene el elemento dirección IP 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 el valor componentes correspondientes 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_name
de "Alaska" y unshort_name
de "AK" con la abreviatura postal de 2 letras.
Ten en cuenta lo siguiente acerca del array
address_components[]
:- El array de componentes de dirección puede incluir más componentes que
formatted_address
. - El array no necesariamente incluye todas las entidades políticas que contienen una dirección, además de las incluidas en
formatted_address
. Para obtener datos sobre todas las entidades políticas que contienen una dirección específica, debes usar la geocodificación inversa, y pasar la latitud y la longitud de la dirección como parámetro a la solicitud. - No se garantiza que el formato de la respuesta permanezca igual entre las distintas solicitudes. En particular, la cantidad de
address_components
varía según la dirección solicitada y puede cambiar con el tiempo para la misma dirección. Un componente puede cambiar de posición en el array. El tipo de componente puede cambiar. Es posible que falte un componente en particular en una respuesta posterior.
Para manejar el array de componentes, debes analizar la respuesta. y seleccionar valores apropiados a través de expresiones. Consulta la guía sobre analizar una respuesta.
postcode_localities[]
es un array que denota hasta 100 localidades. contenidos en un código postal. Solo se presenta cuando el resultado es un que contiene varias localidades.geometry
contiene la siguiente información:location
contiene los valores de latitud y longitud geocodificados. Para normales búsqueda de direcciones, este campo suele ser el más importante.location_type
almacena datos adicionales sobre la ubicación especificada. El se admiten actualmente los siguientes valores:"ROOFTOP"
indica que el resultado que se muestra es un geocódigo preciso para que contamos con información de ubicación precisa que puede desplegarse hasta la precisión de la dirección."RANGE_INTERPOLATED"
indica que el resultado devuelto refleje un aproximación (generalmente en una carretera) interpolada entre dos puntos precisos (como intersecciones). Generalmente, se devuelven resultados interpolados cuando no se encuentran geocódigos exactos disponibles para una calle. web."GEOMETRIC_CENTER"
indica que el resultado que se devuelve 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 el resultado devuelto es aproximado.
viewport
contiene el viewport recomendado para mostrar el resultado devuelto, especificado como dos valores de latitud y longitud que definensouthwest
y Esquinanortheast
del cuadro de límite del viewport. Por lo general, el viewport se usa para enmarcar un resultado cuando se lo muestra a un usuario.bounds
(se muestra de forma opcional) almacena el cuadro de límite. que puede contener por completo el resultado devuelto. Ten en cuenta que estos límites podrían no coincidir con viewport recomendado. (Por ejemplo, San Francisco incluye el Farallones, que son técnicamente parte de la ciudad, pero probablemente no deberían mostrarse en el viewport).
-
plus_code
(consulta Abrir código de ubicación y Plus Codes) es una entidad de codificación referencia de ubicación, derivada de las coordenadas de latitud y longitud, que representa un área: 1/8000 de grado por 1/8000 de grado (alrededor de 14 m x 14 m en el ecuador) o menos. Los Plus Codes pueden reemplazarse de direcciones en lugares donde las direcciones no existen (donde los edificios no están están numeradas o las calles no tienen nombre). La API no siempre muestra Plus Codes.Cuando el servicio devuelve un Plus Code, el código 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_match
indica que el geocodificador no mostró una concordancia exacta para la solicitud original, aunque sí encontró una coincidencia parcial para la dirección solicitada. Te recomendamos que examines la solicitud original para comprobar que no haya errores ortográficos y que la dirección no esté incompleta.Las coincidencias parciales generalmente ocurren cuando las direcciones que se pasan en la solicitud no existen en la localidad. También se pueden mostrar coincidencias parciales cuando una solicitud concuerda con dos o más ubicaciones en la misma localidad. Por ejemplo, "Hillpar St, Bristol, UK" mostrará una coincidencia parcial tanto para Henry Street como para Henrietta Street. Ten en cuenta que si una solicitud incluye una dirección con un componente que contiene errores ortográficos, el servicio de geocodificación puede sugerir una dirección alternativa. Las sugerencias propuestas de esta manera también se marcarán como una coincidencia parcial.
place_id
es un que se puede usar con otras APIs de Google. Por ejemplo, puedes usa elplace_id
en un a la API de Places para detalles de una empresa local, como número de teléfono, horario de atención, usuario opiniones y mucho más. Consulta el ID de lugar. descripción general.
Tipos de direcciones y tipos de componentes de las direcciones
El array types[]
en el resultado indica la
tipo de dirección. Algunos ejemplos de tipos de dirección incluyen una dirección, una
país o una entidad política. También hay un array types[]
en
el address_components[]
, que indica el tipo de cada parte de la
web. Los ejemplos incluyen el número de una calle o el país. (A continuación, hay una lista completa de
types.) Las direcciones pueden tener múltiples tipos. Los tipos se pueden considerar "etiquetas".
Por ejemplo, muchas ciudades están etiquetadas con el political
y el
locality
.
El geocodificador admite y devuelve los siguientes tipos en las tipo de dirección y tipo de componente de dirección:
street_address
indica una dirección precisa.route
indica una ruta designada (como "US 101").intersection
indica una intersección principal, generalmente de dos rutas principales.political
indica una entidad política. Generalmente, este tipo indica un polígono de alguna Administración pública.country
: Indica la entidad política nacional y, por lo general, es el tipo de orden más alto que muestra el geocodificador.administrative_area_level_1
indica una entidad pública de primer orden por debajo del nivel de país. En Estados Unidos, estos niveles administrativos son los estados. No todos los países poseen estos niveles administrativos. En la mayoría de los casos, los nombres cortos de administrative_area_level_1 coincidirán considerablemente con las subdivisiones de ISO 3166-2 y otras listas conocidas; sin embargo, no podemos garantizarlo debido a que nuestros resultados de geocodificación se basan en diferentes indicadores y datos de ubicación.administrative_area_level_2
indica una entidad pública de segundo orden por debajo del nivel de país. En Estados Unidos, estos niveles administrativos son los condados. No todos los países poseen estos niveles administrativos.administrative_area_level_3
indica una entidad pública de tercer orden por debajo del nivel de país. Este tipo indica una división política inferior. No todos los países poseen estos niveles administrativos.administrative_area_level_4
indica una entidad pública de cuarto orden por debajo del nivel de país. Este tipo indica una división política inferior. No todos los países poseen estos niveles administrativos.administrative_area_level_5
indica una entidad pública de quinto orden por debajo del nivel de país. Este tipo indica una división política inferior. No todos los países poseen estos niveles administrativos.administrative_area_level_6
indica una entidad pública de sexto orden por debajo del nivel de país. Este tipo indica una división política inferior. No todos los países poseen estos niveles administrativos.administrative_area_level_7
indica una entidad pública de séptimo orden por debajo del nivel de país. Este tipo indica una división política inferior. No todos los países poseen estos niveles administrativos.colloquial_area
indica un nombre alternativo de uso general para la entidad.locality
indica una entidad política constituida como ciudad o pueblo.sublocality
indica una entidad pública de primer orden por debajo de una localidad. Algunas ubicaciones pueden recibir uno de los tipos adicionalessublocality_level_1
asublocality_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 vecindario designado.premise
indica una ubicación designada, generalmente un edificio o un conjunto de edificios con un nombre común.subpremise
indica una entidad de primer orden por debajo de una ubicación designada, generalmente, un edificio único dentro de un conjunto de edificios con un nombre común.plus_code
indica una referencia de ubicación codificada, derivada de la latitud y la longitud. Los Plus Codes se pueden usar como reemplazo de las direcciones en los lugares donde estas no existen (donde los edificios no están numerados o las calles no tienen nombre). Visita https://plus.codes para obtener más información.postal_code
indica un código postal, tal como se usa para identificar una dirección de correo postal dentro del país.natural_feature
indica un componente natural destacado.airport
indica un aeropuerto.park
indica un parque designado.point_of_interest
indica un lugar de interés designado. Por lo general, estos "lugares de interés" son entidades locales destacadas que no encajan con facilidad en otras categorías, como "Edificio Empire State" o "Torre Eiffel".
Una lista vacía de tipos indica que no hay tipos conocidos para el componente de dirección específico, por ejemplo, Lieu-dit en Francia.
Además de lo anterior, los componentes de dirección pueden incluir los tipos que se indican aquí. Esta lista es no es exhaustiva y está sujeta a cambios.
floor
indica el piso de la dirección de un edificio.establishment
suele indicar un lugar que aún no se categorizó.landmark
indica un lugar cercano que se usa como referencia para facilitar la navegación.point_of_interest
indica un lugar de interés designado.parking
indica un estacionamiento o una estructura de estacionamiento.post_box
indica una casilla de correo postal específica.postal_town
indica un grupo de áreas geográficas, comolocality
ysublocality
, que se usan para las direcciones de correo postal en algunos países.room
indica una habitación en una dirección de un edificio.street_number
indica el número exacto de una calle.bus_station
,train_station
ytransit_station
indican la ubicación de una parada de autobús, tren o transporte público.
Personalización de viewports
En una solicitud de Geocoding, puedes indicarle al servicio de Geocoding que prefiera
resultados dentro de un viewport determinado (expresado como un cuadro delimitador). Tú lo haces
dentro de la URL de la solicitud estableciendo el parámetro bounds
El parámetro bounds
define las coordenadas de latitud y longitud.
de las esquinas suroeste y noreste de este cuadro de límite con una canalización
(|
) para separar las coordenadas.
Por ejemplo, un geocódigo de "Washington" generalmente devuelve el estado de EE.UU. de Washington:
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, agregar un argumento bounds
que defina un cuadro delimitador alrededor
la parte noreste de los EE.UU. resulta en que este geocódigo devuelve 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 geocodificación, puedes indicarle al servicio de geocodificación que devuelva
resultados sesgados a una región en particular mediante region
parámetro. Este parámetro toma un ccTLD (código de país de nivel superior).
dominio) que especifica el sesgo regional. La mayoría de los códigos ccTLD son idénticos a
códigos ISO 3166-1, con algunas excepciones notables. Por ejemplo, Estados Unidos
El ccTLD del Reino es "uk" (.co.uk
), mientras que el código ISO 3166-1 es "gb"
(técnicamente para la entidad de "Reino Unido de Gran Bretaña y
Irlanda del Norte").
Los resultados de la geocodificación pueden personalizarse para cada dominio en el que se encuentre Se lanza oficialmente la aplicación de Google Maps. Ten en cuenta que la personalización solo prefiere los resultados de un dominio específico. Si hay resultados más relevantes fuera de este dominio, es posible que se incluyan.
Por ejemplo, un geocódigo de "Toledo" devuelve este resultado, ya que el valor de 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 mostrar la dirección
resultados restringidos a un área específica. Puedes especificar la restricción con
el filtro components
. Un filtro consiste en una lista de
Pares de component:value
separados por una barra vertical (|
).
Los valores de filtro admiten los mismos métodos de corrección ortográfica y parcial
que coinciden con otras solicitudes de Geocoding. Si el geocodificador encuentra una coincidencia parcial con un
filtro de componentes, la respuesta contendrá un campo partial_match
.
Entre los components
que se pueden filtrar, se incluyen los siguientes:
postal_code
coincide conpostal_code
ypostal_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.
El siguiente elemento components
se puede usar para influir en los resultados, pero no se usará
aplicación forzosa:
route
coincide con el nombre largo o corto de una ruta.locality
enfrenta alocality
ysublocality
.administrative_area
coincide con todos losadministrative_area
niveles.
Notas sobre el filtrado de componentes:
- No repitas estos filtros de componentes en las 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 filtra como AND, no como OR.
- Los resultados son coherentes con los de Google Maps, que a veces da lugar a
respuestas
ZERO_RESULTS
inesperadas. Cómo usar Place Autocomplete puede proporcionar mejores resultados en algunos casos de uso. Para obtener más información, consulta este Preguntas frecuentes. - Para cada componente de la dirección, puedes especificarlo en el archivo
address
. o en un filtrocomponents
, pero no ambos. Especificando los mismos valores en ambos pueden generarZERO_RESULTS
.
un geocódigo para "High St, Hastings" con components=country:GB
devuelve un resultado en Hastings, Inglaterra, y no 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
regresa 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 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"
}
Puedes hacer consultas válidas sin el parámetro de dirección con el
components
. (Cuando se geocodifica una dirección completa,
el parámetro address
es obligatorio si la solicitud contiene el
los nombres y el número 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"
}