La geocodificación convierte una dirección en una ubicación en un mapa. Cuando geocodificas una dirección, la respuesta contiene lo siguiente:
- ID del lugar de la ubicación
- Las coordenadas de latitud y longitud de la ubicación
- El Plus Code de la ubicación
- Los detalles de la dirección expandidos
Solicitud de geocódigo
Una solicitud de geocódigo es una solicitud HTTP GET. Puedes especificar la dirección como una cadena no estructurada:
https://geocode.googleapis.com/v4/geocode/address/ADDRESS_STRING
O como un conjunto estructurado de componentes de dirección representados por parámetros de consulta:
https://geocode.googleapis.com/v4/geocode/address?STRUCTURED_ADDRESS
Por lo general, usas el formato estructurado cuando procesas componentes de dirección capturados en un formulario HTML.
Pasa todos los demás parámetros como parámetros de URL o, para parámetros como la clave de API y la máscara de campo, en encabezados como parte de la solicitud GET.
Cómo pasar una cadena de dirección no estructurada
Una dirección no estructurada es una dirección con formato de cadena o un Plus Code. La geocodificación de direcciones no resuelve las coordenadas de latitud y longitud, ni otras cadenas no estructuradas que no representan 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. Algunos ejemplos de consultas no admitidas son los siguientes:
| Tipo 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 consulta | "Market Street San Francisco San Jose Airport" |
| Elementos de dirección postal no representados 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 near Dallas, Texas" |
| Consultas ambiguas con varias interpretaciones | "Charger drop-off" |
| Nombres históricos que ya no están en uso | "Middlesex United Kingdom" |
| Elementos o intents no geoespaciales | "How many boats are in Ventura Harbor?" |
| Nombres no oficiales o de vanidad |
"The Jenga" "The Helter Skelter" |
Por ejemplo, en el siguiente ejemplo, se pasa la cadena de dirección codificada como URL "1600 Amphitheatre Parkway, Mountain View, CA":
https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY
Observa que el carácter "+" de la URL se convierte en un espacio.
También puedes realizar la solicitud con un comando curl:
curl -H "X-Goog-Api-Key: API_KEY" \ "https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
Las direcciones pueden contener muchos tipos de caracteres especiales. Por ejemplo, "/" como en "7/1 King St, Concord West". Codifica la URL "/" como %2F:
https://geocode.googleapis.com/v4/geocode/address/7%2F1+King+St,+Concord+West?key=API_KEY
Otro ejemplo común es el carácter "#", como en "9500 W Bryn Mawr Ave #650, Rosemont". Codifica la URL "#" como %2FE:
https://geocode.googleapis.com/v4/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY
En el siguiente ejemplo, se especifica una cadena de dirección no estructurada como el Plus Code 849VCWC8+R4. Asegúrate de codificar la URL del carácter "+" como %2B:
https://geocode.googleapis.com/v4/geocode/address/849VCWC8%2BR4?key=API_KEY
Cómo pasar una dirección estructurada
Para especificar una dirección estructurada, usa el parámetro de consulta address, de tipo
PostalAddress.
El objeto PostalAddress te permite especificar algunos o todos los componentes de la dirección en la solicitud como parámetros de consulta individuales.
Por ejemplo, para especificar solo el código postal de la dirección, usa PostalAddress.postalCode:
https://geocode.googleapis.com/v4/geocode/address?address.postalCode=01062&key=API_KEY
Para especificar varios componentes de dirección, como los componentes de dirección capturados en un formulario HTML, usa varios parámetros de consulta:
https://geocode.googleapis.com/v4/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View &address.administrativeArea=CA &key=API_KEY
Cómo usar OAuth para realizar una solicitud
La API de Geocoding v4 admite OAuth 2.0 para la autenticación. Para usar OAuth con la API de Geocoding, el token de OAuth debe tener asignado el permiso correcto. La API de Geocoding admite los siguientes permisos para usar con la geocodificación directa:
https://www.googleapis.com/auth/maps-platform.geocode: Se usa con todos los métodos de la API de Geocoding.https://www.googleapis.com/auth/maps-platform.geocode.address: Se usa solo conGeocodeAddresspara la geocodificación directa.
Además, puedes usar el permiso general https://www.googleapis.com/auth/cloud-platform para todos los métodos de la API de Geocoding. Ese permiso es útil durante el desarrollo, pero no en la producción, ya que es un permiso general que permite el acceso a todos los métodos.
Para obtener más información y ejemplos, consulta Cómo usar OAuth.
Respuesta de geocódigo
La geocodificación muestra un
GeocodeAddressResponse
objeto que contiene el results array de
GeocodeResult
objetos. Cada objeto GeocodeResult representa un solo lugar.
El objeto JSON completo tiene el siguiente formato:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE", "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE", "location": { "latitude": 37.422010799999995, "longitude": -122.08474779999999 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.420656719708511, "longitude": -122.08547523029148 }, "high": { "latitude": 37.4233546802915, "longitude": -122.0827772697085 } }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94043", "administrativeArea": "CA", "locality": "Mountain View", "addressLines": [ "1600 Amphitheatre Pkwy" ] }, "addressComponents": [ { "longText": "1600", "shortText": "1600", "types": [ "street_number" ] }, { "longText": "Amphitheatre Parkway", "shortText": "Amphitheatre Pkwy", "types": [ "route" ], "languageCode": "en" }, ... ], "types": [ "street_address" ], "plusCode": { "globalCode": "849VCWC8+R4", "compoundCode": "CWC8+R4 Mountain View, CA, USA" } } ] }
Parámetros obligatorios
address: Es 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 representan una dirección o un Plus Code. Consulta Cómo pasar una cadena de dirección no estructurada para obtener más detalles y ejemplos de consultas no admitidas. Especifica las direcciones de acuerdo con el formato utilizado por el servicio nacional de correos 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, apartamento o piso. Los elementos de la dirección deben estar delimitados por espacios codificados como URL en%20. Por ejemplo, pasa la dirección "24 Sussex Drive Ottawa ON" de la siguiente manera:24%20Sussex%20Drive%20Ottawa%20ON
%2By los espacios se codifican como URL en%20:- Un código global se compone de un código de área de 4 caracteres y un código local de 6 caracteres o más. Por ejemplo, codifica "849VCWC8+R9" como
849VCWC8%2BR9. - Un código compuesto se compone de un código local de 6 caracteres o más con una
ubicación explícita. Por ejemplo, codifica "CWC8+R9 Mountain View, CA, USA"
como
CWC8%2BR9%20Mountain%20View%20CA%20USA.
- Un código global se compone de un código de área de 4 caracteres y un código local de 6 caracteres o más. Por ejemplo, codifica "849VCWC8+R9" como
Parámetros opcionales
locationBias
Especifica un área para buscar como un
Viewport. Esta ubicación sirve como una personalización, lo que significa que se pueden mostrar resultados alrededor de la ubicación especificada, incluidos los resultados cercanos, pero fuera del área.Especifica la región como un Viewport rectangular. Un rectángulo es un viewport de latitud y longitud, representado como dos puntos bajos y altos diagonalmente opuestos. El punto bajo marca la esquina suroeste del rectángulo, y el punto alto representa la esquina noreste del rectángulo.
Un viewport se considera una región cerrada, lo que significa que incluye su límite. Los límites de latitud deben estar entre -90 y 90 grados inclusive, y los límites de longitud deben estar entre -180 y 180 grados inclusive:
- Si
low=high, el viewport consta de ese punto único. - Si
low.longitude>high.longitude, el rango de longitud se invierte (el viewport cruza la línea de longitud de 180 grados). - Si
low.longitude= -180 grados yhigh.longitude= 180 grados, el viewport incluye todas las longitudes. - Si
low.longitude= 180 grados yhigh.longitude= -180 grados, el rango de longitud está vacío. - Si
low.latitude>high.latitude, el rango de latitud está vacío.
Se deben propagar los valores bajo y alto, y el cuadro representado no puede estar vacío. Un viewport vacío genera un error.
Por ejemplo, esta cadena de consulta define un viewport que abarca por completo la ciudad de Nueva York:
?locationBias.rectangle.low.latitude=40.477398
&locationBias.rectangle.low.longitude=-74.259087 &locationBias.rectangle.high.latitude=40.91618 &locationBias.rectangle.high.longitude=-73.70018 - Si
languageCode
Es el idioma en el que se muestran los resultados.
- Consulta la lista de idiomas disponibles. Google actualiza con frecuencia los idiomas admitidos, por lo que es posible que esta lista no sea completa.
-
Si no se proporciona
languageCode, la API usaende forma predeterminada. Si especificas un código de idioma no válido, la API muestra unINVALID_ARGUMENTerror. - La API hace todo lo posible para proporcionar una dirección que sea legible para el usuario y los habitantes locales. Para lograr ese objetivo, muestra direcciones en el idioma local, transliteradas a una secuencia de comandos legible por el usuario si es necesario, respetando el idioma preferido. Todas las demás direcciones se muestran en el idioma preferido. Todos los componentes de la dirección se muestran en el mismo idioma, que se elige del primer componente.
- Si un nombre no está disponible en el idioma preferido, la API 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 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.
regionCode
El código de región como un valor de código CLDR de dos caracteres. No hay un valor predeterminado. La mayoría de los códigos CLDR son idénticos a los códigos ISO 3166-1.
Cuando se geocodifica una dirección, geocodificación directa, este parámetro puede influir en los resultados del servicio para la región especificada, pero no los restringe por completo. Cuando se geocodifica una ubicación o un lugar, geocodificación inversa o geocodificación de lugares, este parámetro se puede usar para dar formato a la dirección. En todos los casos, este parámetro puede afectar los resultados según la ley aplicable.
-
FieldMask
Crea una máscara de campo de respuesta para especificar los campos que se deben mostrar en la respuesta. Pasa la máscara de campo de respuesta al método con el parámetro de URL
$fieldsofields, o con el encabezado HTTPX-Goog-FieldMask. Por ejemplo, la siguiente solicitud solo mostrará el campoplaceIDde la respuesta.curl -X GET -H 'Content-Type: application/json' \ -H 'X-Goog-FieldMask: results.placeId' \ -H "X-Goog-Api-Key: API_KEY" \ https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
{ "results": [ { "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc" } ] }
Consulta Cómo elegir los campos que se mostrarán para obtener más detalles.
Personalización de la ubicación
Usa el parámetro locationBias para indicarle al servicio Geocoding que anteponga ciertos resultados dentro de un viewport determinado (expresado como un cuadro delimitador).
El parámetro locationBias define las coordenadas de latitud y longitud de las esquinas suroeste y noreste de este cuadro delimitador.
Por ejemplo, una solicitud de geocódigo para la dirección "Washington" puede mostrar resultados para Washington, D.C. y para el estado de Washington en EE.UU.:
https://geocode.googleapis.com/v4/geocode/address/Washington?key=API_KEY
La respuesta está en el siguiente formato:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI", "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI", "location": { "latitude": 38.9071923, "longitude": -77.0368707 }, "granularity": "APPROXIMATE", "viewport": { "low": { "latitude": 38.7916449, "longitude": -77.119759 }, "high": { "latitude": 38.9958641, "longitude": -76.909393 } }, "bounds": { "low": { "latitude": 38.7916449, "longitude": -77.119759 }, "high": { "latitude": 38.9958641, "longitude": -76.909393 } }, "formattedAddress": "Washington, DC, USA", "addressComponents": [ { "longText": "Washington", "shortText": "Washington", "types": [ "locality", "political" ], "languageCode": "en" }, ... ], "types": [ "locality", "political" ] }, { "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ", "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ", "location": { "latitude": 47.7510741, "longitude": -120.7401386 }, "granularity": "APPROXIMATE", "viewport": { "low": { "latitude": 45.543541, "longitude": -124.84897389999999 }, "high": { "latitude": 49.0024945, "longitude": -116.91607109999998 } }, "bounds": { "low": { "latitude": 45.543541, "longitude": -124.84897389999999 }, "high": { "latitude": 49.0024442, "longitude": -116.91607109999998 } }, "formattedAddress": "Washington, USA", "addressComponents": [ { "longText": "Washington", "shortText": "WA", "types": [ "administrative_area_level_1", "political" ], "languageCode": "en" }, ... ], "types": [ "administrative_area_level_1", "political" ] } ] }
Sin embargo, cuando se agrega un parámetro locationBias que define un cuadro delimitador alrededor de la parte noreste de EE.UU., se obtiene como resultado un geocódigo que muestra solo la ciudad de Washington, D.C.:
https://geocode.googleapis.com/v4/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72 &locationBias.rectangle.high.latitude=43.39 &locationBias.rectangle.high.longitude=-65.90 &key=API_KEY
Personalización de la región
En una solicitud de geocodificación, puedes indicarle al servicio Geocoding que muestre resultados personalizados para una región en particular con el parámetro regionCode. Este parámetro toma un
valor de código CLDR de dos caracteres que especifica la personalización de la región. La mayoría de los códigos CLDR son idénticos a los códigos ISO 3166-1.
No hay un valor predeterminado para regionCode. Por ejemplo, un geocódigo de "Toledo" muestra resultados para EE.UU. y España:
https://geocode.googleapis.com/v4/geocode/address/Toledo?key=API_KEY
Respuesta:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw", "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw", "location": { "latitude": 41.652805199999996, "longitude": -83.5378674 }, "granularity": "APPROXIMATE", "viewport": { "low": { "latitude": 41.579513, "longitude": -83.6944089 }, "high": { "latitude": 41.733036, "longitude": -83.4493851 } }, "bounds": { "low": { "latitude": 41.579513, "longitude": -83.6944089 }, "high": { "latitude": 41.733036, "longitude": -83.4493851 } }, "formattedAddress": "Toledo, OH, USA", "addressComponents": [ { "longText": "Toledo", "shortText": "Toledo", "types": [ "locality", "political" ], "languageCode": "en" }, ... ], "types": [ "locality", "political" ] }, { "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM", "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM", "location": { "latitude": 39.8628296, "longitude": -4.0273067 }, "granularity": "APPROXIMATE", "viewport": { "low": { "latitude": 39.8116682, "longitude": -4.179933 }, "high": { "latitude": 39.9251319, "longitude": -3.8148935 } }, "bounds": { "low": { "latitude": 39.8116682, "longitude": -4.179933 }, "high": { "latitude": 39.9251319, "longitude": -3.8148935 } }, "formattedAddress": "Toledo, España", "addressComponents": [ { "longText": "Toledo", "shortText": "Toledo", "types": [ "administrative_area_level_4", "political" ], "languageCode": "es" }, ... ], "types": [ "administrative_area_level_4", "political" ] }, ... ] }
Una solicitud de geocodificación para "Toledo" con regionCode=es (España) solo muestra resultados de España:
https://geocode.googleapis.com/v4/geocode/address/Toledo?regionCode=es&key=API_KEY