Prácticas recomendadas para la API de Isochrones

Suavizado y fidelidad

Puedes personalizar la apariencia y la precisión de los polígonos de salida con los parámetros polygon_fidelity y enable_smoothing. Si bien estas opciones son independientes, funcionan juntas para determinar la forma final.

  • polygonFidelity (polygon_fidelity): Resolución. Controla el tamaño de las celdas de la cuadrícula espacial subyacente que se usan para calcular el área alcanzable.

    • LOW: Usa las celdas de cuadrícula más grandes (varios cientos de metros de ancho). Es ideal para cubrir áreas grandes sin brechas y minimizar el recuento de vértices, lo que genera una forma generalizada que puede sobreestimar el área alcanzable a lo largo de corredores viales estrechos.
    • MEDIUM: Precisión y tamaño de la carga útil equilibrados.
    • HIGH: Usa las celdas de cuadrícula más pequeñas (aproximadamente de 100 a 150 metros de ancho). Genera un ajuste más preciso a la red de rutas, con más vértices, pero puede producir agujeros interiores donde la red de rutas es dispersa.
    • Predeterminada (POLYGON_FIDELITY_UNSPECIFIED): Si no se especifica, el servicio selecciona la resolución automáticamente según el medio de transporte y la duración, con celdas más precisas para duraciones cortas y para WALK, y celdas más generales para duraciones largas. Para comparar isócronas en diferentes duraciones o modos de viaje, establece polygonFidelity de forma explícita para que usen la misma resolución.

    Los tamaños de las celdas son aproximados. Las isócronas muy grandes se pueden generalizar aún más para mantener un tamaño de respuesta manejable.

  • enableSmoothing (enable_smoothing): La estética. Controla si se redondean los bordes escalonados de las celdas de la cuadrícula definidas por la fidelidad.
    • false (sin procesar): Devuelve el límite alineado con la cuadrícula. Los bordes aparecen irregulares o escalonados, lo que refleja las celdas de la cuadrícula. Es ideal para la exactitud analítica, como las pruebas estrictas de punto en polígono.
    • true (Suavizado): Redondea las esquinas y, al mismo tiempo, conserva aproximadamente el área de cada anillo. Es ideal para la visualización en mapas. Debido a que el límite ya no sigue las celdas de la cuadrícula, no lo uses para pruebas estrictas de punto en polígono.

Cómo interactúan: La fidelidad establece el detalle de referencia sobre el que actúa el algoritmo de suavizado.

  • Alta fidelidad y suavizado: Produce una forma detallada y de aspecto orgánico que sigue de cerca los extremos de las rutas.
  • Baja fidelidad + Suavizado: Produce una forma de "mancha" amplia y generalizada.

Tamaño de la carga útil y renderización

Las isócronas grandes (en especial, las solicitudes de larga duración con fidelidad HIGH) pueden contener decenas de miles de coordenadas, y la respuesta JSON sin comprimir puede ser de varios cientos de kilobytes o más.

  • Ancho de banda: Ten en cuenta que el tamaño de la respuesta JSON es significativo para las solicitudes de duración máxima con alta fidelidad.
  • Renderización: La renderización de polígonos extremadamente detallados afecta el rendimiento del cliente. Para reducir el recuento de vértices y el tamaño de la carga útil, elige polygonFidelity: MEDIUM o LOW, o simplifica la geometría en el cliente antes de renderizar con un algoritmo de simplificación de líneas, como Douglas-Peucker.

Latencia y tiempos de espera del cliente

La latencia de respuesta aumenta con el tamaño de la red de rutas que se recorre: las duraciones cortas y los modos WALK y BICYCLE son los más rápidos, mientras que las solicitudes largas de DRIVE y TWO_WHEELER (en especial con TRAFFIC_AWARE) son las que más tardan.

  • Tiempo de espera recomendado del cliente: Configura los plazos del cliente HTTP o gRPC en, al menos, 30 segundos para que las solicitudes largas no se anulen antes de tiempo debido a un tiempo de espera corto del cliente.

Manejo de errores

Implementa la lógica de reintento con retirada exponencial y fluctuación para las respuestas de límite de frecuencia 429 RESOURCE_EXHAUSTED y los errores de servidor 5xx. No vuelvas a intentar los errores de cliente 400, 403 o 404 sin cambiar tu solicitud:

  • INVALID_ARGUMENT (400): Verifica que travelDuration esté entre 1s y 3600s (DRIVE/TWO_WHEELER) o 7200s (WALK/BICYCLE), que location no se omita ni sea (0, 0) (o que place sea un ID de lugar válido) y que TRAFFIC_AWARE solo se use con DRIVE o TWO_WHEELER. Un valor latitude o longitude omitido se trata como 0.0, por lo que omitir solo uno de ellos no suele causar un error 400 (a menos que el otro valor también sea 0.0). Vuelve a verificar ambos valores si la isócrona aparece en el lugar equivocado.
  • PERMISSION_DENIED (403): Verifica que se incluya tu clave de API o token de OAuth, y que la API de Isochrones y la facturación estén habilitadas en tu proyecto de Google Cloud.
  • NOT_FOUND (404): No se pudo resolver el place en una ubicación o no se pudo ajustar el origen a una ruta cercana que se pueda usar con el medio de transporte (en un radio de aproximadamente 200 metros, o menos para WALK y BICYCLE).
  • RESOURCE_EXHAUSTED (429): Tu proyecto superó la cuota de solicitudes por minuto (300 QPM predeterminadas). Vuelve a intentarlo con una retirada exponencial.