La geocodificación es el proceso que convierte direcciones (como la dirección de una calle) en coordenadas geográficas (latitud y longitud) que puedes usar para colocar marcadores en un mapa o posicionar el mapa. El objetivo de este documento es aclarar las consideraciones que debes tener en cuenta para la geocodificación de direcciones. Describe cuándo es óptimo usar la API de Geocoding y cuándo es beneficioso usar el servicio de Place Autocomplete de la API de Places.
En general, usa la API de Geocoding cuando realices la geocodificación de direcciones completas (por ejemplo, "48 Pirrama Rd, Pyrmont, NSW, Australia"). Usa el servicio Place Autocomplete de la API de Places cuando codifiques direcciones ambiguas (incompletas) o para aplicaciones sensibles a la latencia, como cuando respondas a entradas del usuario.
Casos de uso y recomendaciones de API
| Casos de uso y recomendaciones de API | |
|---|---|
| Responde en tiempo real a la entrada del usuario (incluye direcciones ambiguas, incompletas, con formato incorrecto o mal escritas que ingresó un usuario) | Usa el servicio de autocompletado de sitios de la API de Places para obtener un ID de lugar y, luego, la API de Geocoding a fin de geocodificar el ID de lugar en un valor latlng. |
| Procesamiento automático de sistemas completos y sin ambigüedades en los sistemas postales (por ejemplo, “48 Pirrama Rd, Pyrmont, NSW, Australia”) | Usa el servicio web de la API de Geocoding. |
| Sistemas automatizados que procesan consultas ambiguas (por ejemplo, direcciones incompletas, con formato incorrecto o errores de ortografía) | Los sistemas automatizados recomendados usan el servicio web de la API de Geocoding. Sin embargo, los sistemas automatizados con un alto porcentaje de consultas ambiguas, incompletas o mal escritas que se derivan de las entradas del usuario pueden beneficiarse si agregas un widget interactivo de Place Autocomplete para permitir que los usuarios seleccionen un resultado y eviten escribir mal una dirección. |
| Problemas de latencia cuando se usa la API de Directions o de Distance Matrix con orígenes, destinos o puntos de referencia especificados como strings de dirección | Reduce la latencia de codificación geográfica mediante el servicio Place Autocomplete de la API de Places para obtener los ID de lugar. Luego, pasa estos ID a la API de Directions o de Distance Matrix. |
Responder a entradas del usuario
Las aplicaciones que responden en tiempo real a la entrada del usuario tienen dos consideraciones importantes que afectan la elección de la API:
- Por lo general, la entrada del usuario implica ingresar una dirección de manera progresiva (como "123 Main Street"), por lo que resulta beneficioso poder geocodificar direcciones incompletas y ambiguas, ya que permite que el usuario obtenga un resultado más rápido.
- Las aplicaciones que responden a entradas del usuario son muy sensibles a la latencia.
Estas dos consideraciones hacen que el servicio Place Autocomplete en la API de Places sea ideal para el caso práctico de responder a las entradas del usuario. Place Autocomplete está diseñado para mostrar varias opciones posibles y permitir que un usuario elija una de ellas. La API de Places puede restringirse para que solo busque geocódigos o direcciones y excluya empresas. Además, la función de búsqueda de autocompletado se puede restringir para mostrar resultados específicos de una ubicación. La API de Places muestra un ID de lugar que se puede pasar como una ubicación completamente inequívoca al servicio web de la API de Geocoding, que luego muestra los detalles de la dirección completa y geocodifica la dirección en un valor latlng. Los ID de lugar también se pueden pasar a otras API, como la API de Directions y de Distance Matrix (ver a continuación).
La geocodificación de direcciones en la API de Geocoding tiene una latencia mucho más alta y también produce resultados menos precisos para consultas incompletas o ambiguas, por lo que no se recomienda para las aplicaciones que tienen que responder en tiempo real a las entradas del usuario.
Obtén más información sobre el servicio de Place Autocomplete para Android, iOS, JavaScript y la API de Places.
Sistemas automatizados
Sistemas automatizados de procesamiento de direcciones postales completas e inequívocas: El servicio web de la API de Geocoding controla mejor las consultas inequívocas, como las strings de direcciones postales completas (por ejemplo, "48 Pirrama Rd, Pyrmont, NSW, Australia"). El backend de geocodificación de direcciones proporciona una mayor cobertura de direcciones a nivel global y está optimizado para obtener resultados de alta calidad con este tipo de consultas completas e inequívocas.
Procesamiento automatizado del sistema para consultas ambiguas: Las consultas ambiguas son aquellas que contienen direcciones con formato erróneo, direcciones incompletas o errores de ortografía. Para los sistemas automatizados, te recomendamos usar el servicio web de la API de Geocoding. Sin embargo, la API de Geocoding no está diseñada para manejar consultas ambiguas y puede producir resultados menos precisos o nulos en respuesta a consultas ambiguas. Si tu sistema automatizado procesa una alta tasa de consultas ambiguas derivadas de la entrada del usuario, puedes beneficiarte de agregar un elemento interactivo a tu app con el servicio Place Autocomplete de la API de Places, ya que está diseñado para mostrar varias opciones posibles y permitir que el usuario elija una de ellas. La API de Places muestra un ID de lugar que se puede pasar como una ubicación completamente inequívoca al servicio web de la API de Geocoding, que luego muestra los detalles completos de la dirección y geocodifica la dirección en un valor latlng. Obtén más información sobre el servicio de Place Autocomplete para Android, iOS, JavaScript y la API de Places.
Cómo reducir la latencia de las API de Directions y Distance Matrix
Cuando los orígenes, destinos o puntos de referencia se especifican como strings de direcciones, la API de Directions y la API de Distance Matrix utilizan el mismo backend que la API de Geocoding para realizar la geocodificación de estas direcciones antes de calcular las indicaciones. Esto aumenta la latencia de manera significativa en comparación con la especificación de las mismas ubicaciones que los latlng o los ID de lugar.
Si tu aplicación usa la API de Directions o Distance Matrix en una situación sensible a la latencia, como responder a entradas del usuario, y tus orígenes, destinos o puntos de referencia se especifican inicialmente como strings de direcciones, te recomendamos minimizar la latencia usando el servicio de autocompletado de sitios de la API de Places para convertir strings de direcciones en ID de sitios. Luego, pasa los ID de lugar a la API de Directions o de Distance Matrix. Obtén más información sobre el servicio de Place Autocomplete para Android, iOS, JavaScript y la API de Places. También puedes consultar un ejemplo de JavaScript con autocompletado de sitios y direcciones.
Conclusión
Según tu caso práctico, cuando codificas direcciones geográficas, usar la API de Geocoding o usar el servicio de Place Autocomplete en combinación con la API de Geocoding te permite crear aplicaciones que ofrecen a los usuarios resultados de codificación geográfica precisos y una latencia reducida.
Gestionar errores y reintentos
Si recibes respuestas de UNKNOWN_ERROR, se deben a errores transitorios y se resuelven mejor si vuelves a intentarlo después de un retraso breve. Te recomendamos usar las bibliotecas cliente de los servicios web de Google Maps Platform, que incluyen la lógica de reintento y admiten la autenticación del plan Premium de Google Maps Platform.
El cliente Java, el cliente de Python, el cliente de Go y el cliente de Node.js para los servicios de Google Maps son bibliotecas cliente compatibles con la comunidad, disponibles para descargar y contribuciones en GitHub, donde también encontrarás instrucciones de instalación y código de muestra.
Si recibes un código de estado OVER_QUERY_LIMIT como respuesta, significa que superaste los límites de uso para la API. Te recomendamos probar estas estrategias de optimización de uso.