La geocodificación es el proceso que convierte direcciones ("1600 Amphitheatre Parkway, Mountain View, CA") en coordenadas geográficas (37.423021, -122.083739) que puedes usar para colocar marcadores o posicionar el mapa. Las APIs de Google Maps Platform proporcionan dos enfoques para la geocodificación:
- Geocodificación del cliente, que se ejecuta en el navegador, por lo general, en respuesta a la acción del usuario La API de Maps JavaScript proporciona clases que realizan las solicitudes por ti. Este enfoque se describe en la documentación de la API de Maps JavaScript.
- Geocodificación HTTP del servidor, que permite que tu servidor consulte directamente los servidores de Google para obtener geocódigos. La API de Geocoding es el servicio web que proporciona esta funcionalidad. Por lo general, este servicio se integra en otro código que se ejecuta en el servidor. La geocodificación del servidor se describe en la documentación de la API de Geocoding.
Ejemplos de geocodificación en el cliente y el servidor
A continuación, se incluye un ejemplo de geocodificación del cliente que toma una dirección, la geocodifica, mueve el centro del mapa a esa ubicación y agrega un marcador de mapa allí:
geocoder = new google.maps.Geocoder(); geocoder.geocode({ 'address': address }, function(results, status) { if (status == google.maps.GeocoderStatus.OK) { map.setCenter(results[0].geometry.location); var marker = new google.maps.Marker({ map: map, position: results[0].geometry.location }); } });
Para ver más ejemplos, consulta la documentación de la API de Maps JavaScript.
A continuación, se muestra un ejemplo en el que se usa Python para realizar una solicitud de geocodificación del servidor en la API de Geocoding v4:
import json import urllib.request address = "1600+Amphitheatre+Parkway,+Mountain+View,+CA" key = "my-key-here" url = f"https://geocode.googleapis.com/v4/geocode/address/{address}" headers = {"X-Goog-Api-Key": key} req = urllib.request.Request(url, headers=headers) with urllib.request.urlopen(req) as response: result = json.loads(response.read().decode("utf-8"))
Esto genera un objeto JSON con el siguiente contenido:
{ "results": [ { "place": "places/ChIJiSSC8QK6j4AR98Thup8mqTc", "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc", "location": { "latitude": 37.4224864, "longitude": -122.0855962 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.4211700197085, "longitude": -122.08691558029149 }, "high": { "latitude": 37.4238679802915, "longitude": -122.08421761970851 } }, "bounds": { "low": { "latitude": 37.4221145, "longitude": -122.0860002 }, "high": { "latitude": 37.4228775, "longitude": -122.085133 } }, "formattedAddress": "Google Building 41, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94043-1351", "administrativeArea": "CA", "locality": "Mountain View", "addressLines": [ "1600 Amphitheatre Pkwy" ] }, "addressComponents": [ { "longText": "Google Building 41", "shortText": "Google Building 41", "types": [ "premise" ], "languageCode": "en" }, { "longText": "1600", "shortText": "1600", "types": [ "street_number" ] }, { "longText": "Amphitheatre Parkway", "shortText": "Amphitheatre Pkwy", "types": [ "route" ], "languageCode": "en" }, { "longText": "Mountain View", "shortText": "Mountain View", "types": [ "locality", "political" ], "languageCode": "en" }, { "longText": "Santa Clara County", "shortText": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ], "languageCode": "en" }, { "longText": "California", "shortText": "CA", "types": [ "administrative_area_level_1", "political" ], "languageCode": "en" }, { "longText": "United States", "shortText": "US", "types": [ "country", "political" ], "languageCode": "en" }, { "longText": "94043", "shortText": "94043", "types": [ "postal_code" ] }, { "longText": "1351", "shortText": "1351", "types": [ "postal_code_suffix" ] } ], "types": [ "premise", "street_address" ] } ] }
Para ver más ejemplos, consulta la descripción general de la API de Geocoding v4 y la guía para geocodificar una dirección.
Consideraciones de cuota y costo
Los costos, las cuotas y los límites de frecuencia de la geocodificación impulsan las estrategias que se describen en este documento.
Costo
Los límites de cuota por día (QPD) no se usan para las solicitudes de geocodificación. En cambio, cada solicitud de geocodificación, ya sea del lado del cliente a través del navegador o del lado del servidor a través del servicio web de la API de Geocoding, se factura con un precio por solicitud. Para administrar el costo de uso, considera administrar tus límites de uso y cuotas.
Límites de frecuencia
El servicio de geocodificación tiene un límite de frecuencia de 3,000 QPM (consultas por minuto), que se calcula como la suma de las consultas del cliente y las del servidor.
Cuando ejecutas solicitudes de geocodificación del cliente en intervalos periódicos, como en una app para dispositivos móviles, tus solicitudes pueden mostrar errores si todos tus usuarios realizan solicitudes al mismo tiempo (por ejemplo, todos en el mismo segundo de cada minuto). Para evitar esto, considera una de las siguientes opciones:
- Introduce intervalos aleatorios a tus solicitudes (jitter). Asegúrate de que las solicitudes sean aleatorias en toda tu base de usuarios.
- Si desarrollas para Android, usa una alarma repetitiva inexacta.
- Si desarrollas para Android, selecciona una estrategia de ubicación adecuada.
Almacenamiento en caché
Consulta las políticas de la API de Geocoding sobre el almacenamiento en caché.
Arquitectura del servidor frente a la del cliente en la versión 4
La API de Geocoding v4 (incluidas SearchDestinations, GeocodeAddress, GeocodeLocation y GeocodePlace) está diseñada como una API de servidor a servidor. Llamar a los extremos de la versión 4 desde tu servidor de backend ofrece ventajas fundamentales:
- Inteligencia de llegada hiperlocal: El método
SearchDestinations(POST /v4/geocode/destinations) está disponible exclusivamente con solicitudes de REST o gRPC del servidor y devuelve entradas de edificios, puntos de navegación con ruta, contornos de edificios y puntos de referencia cercanos que no están disponibles en los geocodificadores de navegadores del cliente. - Seguridad de la API mejorada: Las llamadas del servidor protegen tus claves de API y tokens de OAuth de la exposición en los navegadores de los clientes. Consulta Seguridad de APIs.
- Máscaras de campo de respuesta: Los extremos de la versión 4 del servidor admiten máscaras de campo, lo que te permite solicitar solo los campos que tu aplicación requiere para minimizar el tamaño de la carga útil y la latencia.
Cuándo usar la búsqueda en el navegador del cliente
En el caso de las aplicaciones de navegador interactivas que responden a las pulsaciones de teclas en tiempo real, considera combinar la función Place Autocomplete del cliente (para eliminar la ambigüedad de la entrada del usuario y obtener un ID de lugar) con una llamada de backend a SearchDestinations o GeocodePlace para recuperar detalles o coordenadas hiperlocales de forma segura.