Referencia rápida de la API de Geocoding

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

API de Geocoding: Errores comunes

  • Problema: Las solicitudes SearchDestinations sin una máscara de campo fallan con un error; a diferencia de GeocodeAddress, GeocodeLocation y GeocodePlace, la máscara de campo es obligatoria. Solución: Configura el encabezado X-Goog-FieldMask o el parámetro $fields en cada solicitud SearchDestinations. Consulta /maps/documentation/geocoding/choose-fields.
  • Problema: La versión 4 de GeocodeAddress no tiene un filtro de componentes estricto (components=country:US de la versión 3). Los parámetros estructurados de address.* se combinan en una dirección y no filtran los resultados. regionCode tampoco tiene un valor predeterminado en la versión 4 (el valor predeterminado de la versión 3 era us). Solución: Filtra results del lado del cliente: haz coincidir regionCode en mayúsculas con postalAddress.regionCode; haz coincidir las áreas administrativas de 2 letras en mayúsculas con postalAddress.administrativeArea y administrative_area_level_n addressComponents (shortText); normaliza la entrada y postalAddress.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: SearchDestinations puede 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: Establece placeFilter.addressability en PRIMARY cuando 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, no address_components), quita status y error_message, y devuelve un solo objeto raíz de GeocodePlace en lugar de un array de results. 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 respuesta buildings.entrances, navigation_points, buildings.building_outlines, grounds): Obsoletos desde el 13 de agosto de 2025. Reemplazo: Método SearchDestinations de 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.