Controla el uso de tu clave antes de alcanzar un límite
Vigilar las cabeceras de cuota sobre la marcha te indica cuándo te acercas a un límite, mucho antes de que se rechace realmente una solicitud.
Divide un campo de dirección de texto libre en componentes estructurados
Un único campo de dirección de texto libre es fácil de recoger y difícil de manejar después, sobre todo cuando necesitas filtrar por ciudad o agrupar por región. La geocodificación directa hace el análisis por ti como efecto secundario de resolver la dirección en coordenadas.
Envía el texto libre
GET /v1/forward?q=1600 Pennsylvania Avenue, Washington, DC 20500&limit=1{
"status": "ok",
"query": "1600 Pennsylvania Avenue, Washington, DC 20500",
"results": [
{
"formatted": "1600 Pennsylvania Avenue NW, Washington, DC 20500",
"lat": 38.8977,
"lon": -77.0365,
"type": "address",
"precision": "house",
"confidence": 0.97,
"place_id": "def456",
"components": {"house_number": "1600", "street": "Pennsylvania Avenue NW", "city": "Washington", "region": "DC", "postcode": "20500", "country": "US"}
}
]
}Guarda los componentes por separado
Una vez que tengas el objeto components, guarda cada campo en su propia columna de la base de datos en lugar de conservar solo la cadena original de texto libre. Así podrás filtrar los registros de clientes por ciudad o región, generar informes regionales precisos y validar que un código postal y una ciudad corresponden realmente entre sí, algo que no resulta práctico con una sola cadena sin estructura.
Un segundo ejemplo: una dirección con otro formato
La estructura de las direcciones no es igual en todas partes. Una dirección del Reino Unido puede resolverse con un condado en lugar de una región al estilo de Estados Unidos, y un componente como house_number puede no aparecer en absoluto en el caso de un edificio con nombre propio. Enviar el mismo tipo de solicitud funciona sea cual sea el país, pero las claves de componentes que recibes pueden variar, así que diseña tu esquema de almacenamiento para tolerar que falte un componente, en lugar de suponer que todos los países rellenan siempre exactamente el mismo conjunto.
Un error habitual que debes evitar
No incrustes en el código la suposición de que todos los resultados contendrán house_number, street, city, region y postcode, para luego tratar cualquier dirección a la que le falte uno de ellos como un error de análisis. Una dirección perfectamente válida, sobre todo fuera de una cuadrícula urbana con números de portal, puede devolverse legítimamente con algunos campos vacíos. Construir una validación estricta en torno a un conjunto completo de componentes hará que se rechacen entradas reales de clientes que el endpoint analizó correctamente.
Conserva también el texto original
Guarda la entrada original de texto libre junto con los componentes analizados en lugar de descartarla. Si un componente llega incompleto o un cliente necesita corregir algo más adelante, tener a mano el texto original facilita volver a analizarlo o corregirlo manualmente.
Gestiona los análisis parciales
No todas las direcciones se resuelven con todos los componentes rellenados. Una dirección rural puede llegar sin house_number, y una localidad pequeña puede llegar sin un valor de región propio. Trata los campos de componentes que faltan como vacíos legítimos y no como un fallo de análisis, y recurre a la cadena formateada para mostrarla cuando no esté presente un componente concreto que querías.
Gestiona más de una coincidencia plausible
Si subes limit por encima de 1, obtienes varios resultados candidatos ordenados según lo bien que cada uno coincide con el texto libre, lo que resulta útil cuando quieres mostrar al cliente una lista breve para elegir en lugar de quedarte en silencio con la primera coincidencia. Es un término medio razonable entre el análisis totalmente automático y un formulario de entrada completamente manual, sobre todo para las direcciones que tu umbral de confianza marcaría de otro modo como dudosas.
Lo que cuesta
Analizar un campo de texto libre de esta forma cuesta una solicitud por dirección, igual que cualquier otra consulta de geocodificación directa. Un proceso de relleno que limpie una tabla existente de direcciones en texto libre puede recorrer toda la tabla como una solicitud masiva, con una solicitud por fila.
Convertir texto libre en campos estructurados es un efecto secundario natural de geocodificar una dirección, no un paso adicional. La documentación de geocodificación directa enumera todos los componentes que puede devolver el endpoint.