La API de Geocoding es un servicio web que convierte direcciones en coordenadas y en IDs de lugar, y viceversa. Su método SearchDestinations de la versión 4 también devuelve detalles del destino, como entradas de edificios, puntos de navegación, contornos de edificios y terrenos, y puntos de referencia cercanos.
API de Geocoding: Datos clave
- Producto: API de Geocoding
- Categoría: Lugares
- Plataforma: Servicio web (REST)
- Se ejecuta en: Servidor (código de backend)
- Etapa de lanzamiento: GA
- Ciclo de vida: Activo
- Descripción general: Descripción general de la API de Geocoding
API de Geocoding: Cuándo usarla
Usa la API de Geocoding en los siguientes casos:
- Necesitas convertir una dirección en coordenadas de latitud y longitud, y un ID de lugar en tu servidor de backend.
- Necesitas una dirección visible o un área administrativa (ciudad, código postal) para las coordenadas GPS o un ID de lugar conocido.
- Necesitas entradas de edificios, puntos de navegación con rutas o contornos de edificios o terrenos para dirigir a los conductores o mensajeros a un destino.
- Necesitas resolver un destino dentro de un complejo grande (aeropuerto, centro comercial, campus) en subdestinos o puntos de referencia cercanos.
No uses la API de Geocoding en los siguientes casos:
- Necesitas geocodificación de JavaScript del navegador del cliente; llamar a la versión 4 con una clave de API expuesta es un riesgo de seguridad. En su lugar, usa la API de Maps JavaScript.
- Necesitas calcular una ruta o la hora estimada de llegada al destino geocodificado. En su lugar, usa la API de Routes.
- Necesitas indicaciones paso a paso para llegar a un token de punto de navegación en una app para Android. En su lugar, usa el SDK de Navigation para Android.
- Necesitas indicaciones paso a paso para llegar a un token de punto de navegación en una app para iOS. En su lugar, usa el SDK de Navigation para iOS.
API de Geocoding: Configuración
- Servicio que se habilitará:
geocoding-backend.googleapis.com - Autenticación: Clave de API, OAuth 2.0, cuenta de servicio
- Comienza a usar la API de Geocoding: Configura la API de Geocoding
- Referencia: Referencia de la API de Geocoding
- Precios: Uso y facturación de la API de Geocoding
- Políticas: Políticas de la API de Geocoding
- Notas de la versión: Notas de la versión de la API de Geocoding
API de Geocoding: productos relacionados
- Se suele usar con: API de Routes, SDK de Navigation para Android y SDK de Navigation para iOS
API de Geocoding: Errores comunes
- Problema: Las solicitudes
SearchDestinationssin una máscara de campo fallan con un error; a diferencia deGeocodeAddress,GeocodeLocationyGeocodePlace, la máscara de campo es obligatoria. Solución: Configura el encabezadoX-Goog-FieldMasko el parámetro$fieldsen cada solicitudSearchDestinations. Consulta /maps/documentation/geocoding/choose-fields. - Problema: La versión 4 de
GeocodeAddressno tiene un filtro de componentes estricto (components=country:USde la versión 3). Los parámetros estructurados deaddress.*se combinan en una dirección y no filtran los resultados.regionCodetampoco tiene un valor predeterminado en la versión 4 (el valor predeterminado de la versión 3 eraus). Solución: Filtraresultsdel lado del cliente: haz coincidirregionCodeen mayúsculas conpostalAddress.regionCode; haz coincidir las áreas administrativas de 2 letras en mayúsculas conpostalAddress.administrativeAreayadministrative_area_level_naddressComponents(shortText); normaliza la entrada ypostalAddress.postalCode(quita los espacios y guiones, y aplica las reglas de la región). Consulta /maps/documentation/geocoding/geocoding-v4-migrate. - Problema: Llamar a la API de Geocoding v4 directamente desde el código JavaScript del navegador expone la clave de API; las restricciones de URLs de referencia de HTTP se pueden omitir falsificando el encabezado
Referer. Solución: Llama a la versión 4 desde tu propio backend con una clave protegida o usa el servicio de Geocoding de la API de Maps JavaScript (backend de la versión 3) para las necesidades del cliente. Consulta /maps/documentation/geocoding/geocoding-v4-migrate. - Problema:
SearchDestinationspuede devolver resultados que no tienen una dirección principal precisa, a diferencia de la versión 3 y los otros métodos de la versión 4. Solución: EstableceplaceFilter.addressabilityenPRIMARYcuando solo necesites resultados con direcciones principales precisas. Consulta /maps/documentation/geocoding/geocoding-v4-migrate. - Problema: El código escrito para la API de Geocoding v3 falla en las respuestas de REST de la v4, ya que esta versión usa nombres de campo en lowerCamelCase (
addressComponents, noaddress_components), quitastatusyerror_message, y devuelve un solo objeto raíz deGeocodePlaceen lugar de un array deresults. Corrección: Verifica los códigos de estado HTTP y los cuerpos de error en las llamadas de REST de la versión 4, lee los campos en lowerCamelCase (addressComponents,postalAddress) y ten en cuenta que las respuestas de gRPC siguen usando minúsculas con guiones bajos. Consulta /maps/documentation/geocoding/geocoding-v4-migrate.
API de Geocoding: Funciones heredadas y obsoletas
- Datos hiperlocales de la versión 3 de la API de Geocoding (
extra_computations:BUILDING_AND_ENTRANCES,NAVIGATION_POINTS,GROUNDS; campos de respuestabuildings.entrances,navigation_points,buildings.building_outlines,grounds): Obsoletos desde el 13 de agosto de 2025. Reemplazo: MétodoSearchDestinationsde la API de Geocoding v4 (POST /v4/geocode/destinations). Consulta la guía de migración.
Qué puedes hacer con la API de Geocoding
Consulta las guías vinculadas a continuación para cada tarea o compara los productos en el Explorador de capacidades.
- Devolver las coordenadas de latitud y longitud de una dirección (geocodificación)
- Devolver la dirección de un conjunto de coordenadas de latitud y longitud (geocodificación inversa)
- Restringir una solicitud de geocodificación para que devuelva resultados dentro de un viewport específico Nota: En la versión 4 de la API de Geocoding, locationBias sesga los resultados hacia el viewport especificado en lugar de restringirlos de forma estricta.
- Restringe una solicitud de geocodificación o geocodificación inversa para que solo devuelva resultados dentro de una región, un país o un código postal específicos. Nota: En la API de Geocoding v4, regionCode sesga los resultados hacia una región CLDR especificada en lugar de restringirlos estrictamente. Para el filtrado de componentes heredado de la versión 3 por país o código postal, consulta https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding#ComponentFiltering.
- Restringe una solicitud de geocodificación inversa para que solo devuelva resultados de los tipos de direcciones especificados. Nota: En la versión 4 de la API de Geocoding, el parámetro types filtra los resultados de geocodificación inversa que se devuelven por tipo de dirección después de la búsqueda, en lugar de restringir la búsqueda subyacente.
- Muestra información sobre la proximidad a puntos de referencia o áreas para una dirección.
- Devuelve información sobre la proximidad a puntos de referencia o áreas para un conjunto de coordenadas de latitud y longitud.
- Muestra información sobre la proximidad a puntos de referencia o áreas para un identificador de lugar de Google.
- Devuelve la dirección de un identificador de lugar de Google.
- Devuelve las coordenadas de latitud y longitud del contorno de un edificio para una dirección.
- Devuelve las coordenadas de latitud y longitud del contorno de un edificio para un conjunto de coordenadas de latitud y longitud.
- Devuelve las coordenadas de latitud y longitud del contorno de un edificio para un identificador de Google Place.
- Devuelve las coordenadas de latitud y longitud de la entrada de un edificio para una dirección.
- Devolver las coordenadas de latitud y longitud de la entrada de un edificio para un conjunto de coordenadas de latitud y longitud
- Devolver las coordenadas de latitud y longitud de la entrada de un edificio para un identificador de Google Place