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.
Combina código postal y país para obtener consultas más rápidas
La geocodificación directa está diseñada para manejar texto libre desordenado, lo que significa que trabaja internamente para averiguar qué tipo de entrada está recibiendo. Si ya sabes que tienes un código postal limpio y un país, hay un camino más directo.
Ir directamente al endpoint de códigos postales
En lugar de montar una cadena de texto libre y enviarla a /v1/forward, envía el código y el país directamente a /v1/postcode.
GET /v1/postcode?code=90210&country=US{
"status": "ok",
"postcode": "90210",
"country_code": "US",
"results": [
{"lat": 34.0901, "lon": -118.4065, "components": {"city": "Beverly Hills", "region": "CA", "country": "US"}}
]
}Por qué es la opción más adecuada
Un par de código postal y país ya es una entrada totalmente estructurada, así que el endpoint no tiene ninguna ambigüedad que resolver, como sí puede ocurrir con una cadena de texto libre que podría coincidir con varios lugares de nombre parecido. Usar el endpoint creado exactamente para esta forma de entrada te da una coincidencia más limpia con menos riesgo de un resultado inesperado.
Un segundo ejemplo: un código postal alfanumérico
La misma llamada funciona igual para un país que usa letras y números combinados en lugar de solo dígitos.
GET /v1/postcode?code=K1A 0B1&country=CAPasar el parámetro country es lo que hace que esto sea fiable, ya que una cadena de código por sí sola no siempre es única entre países, y el parámetro country es lo que indica al endpoint con qué sistema postal debe interpretarla.
Cuándo sigues necesitando la geocodificación directa
Si necesitas una coincidencia concreta a nivel de calle en lugar de la zona general que cubre un código postal, la geocodificación directa con la dirección completa sigue siendo la herramienta adecuada, ya que una consulta de código postal se resuelve en la zona que cubre el código, no en un edificio concreto dentro de ella. Usa /v1/postcode para consultas a nivel de zona, como validar una zona de envío, y /v1/forward cuando necesites precisión a nivel de vivienda.
Un error habitual que debes evitar
No des por hecho que un código postal siempre corresponde a un único punto que representa con precisión cada dirección que contiene. Las coordenadas que devuelve /v1/postcode representan la zona cubierta por el código, que puede ser una sola manzana o, en algunos países, una zona mucho mayor. Tratar ese punto devuelto como si fuera la ubicación exacta del edificio de un cliente concreto, en lugar de un punto representativo de todo el código, introducirá errores en cualquier cosa sensible a la distancia que construyas sobre él.
Combinar ambos en un flujo de trabajo
Un patrón habitual es validar primero el par de código postal y país con /v1/postcode y, una vez superada esa validación, enviar la dirección completa a /v1/forward para obtener coordenadas exactas. Son dos solicitudes por envío, una para cada etapa, en lugar de intentar forzar a un solo endpoint a hacer ambos trabajos.
Un caso límite: un código que no devuelve resultados
Un array de resultados vacío significa que el código no se reconoció para el país indicado, lo cual es una situación distinta de una respuesta de error. Trátalo como cualquier otra entrada no reconocida, pidiendo al cliente que vuelva a revisar lo que introdujo, en lugar de mostrarlo como un error del sistema.
Lo que cuesta
Cada consulta de código postal es una solicitud, el mismo costo que una consulta de geocodificación directa. Elegir el endpoint adecuado para una entrada estructurada no cambia lo que cuesta, cambia lo directamente que llegas a un resultado correcto.
Recurrir al endpoint de códigos postales cuando ya tienes una entrada limpia y estructurada evita la ambigüedad adicional que supone reconstruir una cadena de texto libre solo para volver a descomponerla. Tienes todos los detalles en la documentación de consulta de códigos postales.