Práticas recomendadas da API Isochrones

Suavização e fidelidade

É possível personalizar a aparência e a precisão dos polígonos de saída usando os parâmetros polygon_fidelity e enable_smoothing. Embora essas opções sejam independentes, elas trabalham juntas para determinar a forma final.

  • polygonFidelity (polygon_fidelity): resolução. Controla o tamanho das células da grade espacial usadas para calcular a área acessível.

    • LOW: usa as maiores células de grade (várias centenas de metros de diâmetro). É ideal para cobrir grandes áreas sem lacunas e minimizar a contagem de vértices, resultando em uma forma generalizada que pode superestimar a área acessível ao longo de corredores de estradas estreitas.
    • MEDIUM: precisão e tamanho do payload equilibrados.
    • HIGH: usa as menores células de grade (aproximadamente 100 a 150 metros de diâmetro). Resulta em um ajuste mais preciso à rede viária, com mais vértices, mas pode produzir buracos internos onde a rede viária é esparsa.
    • Padrão (POLYGON_FIDELITY_UNSPECIFIED): se não for especificado, o serviço selecionará a resolução automaticamente com base no meio de transporte e na duração, usando células mais refinadas para durações curtas e para WALK, e células mais amplas para durações longas. Para comparar isócronas em diferentes durações ou modos de viagem, defina polygonFidelity explicitamente para que usem a mesma resolução.

    Os tamanhos das células são aproximados. Isócronas muito grandes podem ser generalizadas ainda mais para manter o tamanho da resposta gerenciável.

  • enableSmoothing (enable_smoothing): a estética. Controla se as bordas escalonadas das células da grade definidas pela fidelidade são arredondadas.
    • false (bruto): retorna o limite alinhado à grade. As bordas aparecem irregulares ou em degraus, refletindo as células da grade. Ideal para precisão analítica, como testes rigorosos de ponto em polígono.
    • true (Suavizado): arredonda os cantos e preserva aproximadamente a área de cada anel. Ideal para exibição visual em mapas. Como o limite não segue mais as células da grade, não o use para testes estritos de ponto em polígono.

Como eles interagem: a fidelidade define o detalhe de referência em que o algoritmo de suavização atua.

  • Alta fidelidade + suavização: produz uma forma detalhada e de aparência orgânica que segue de perto as extremidades da via.
  • Baixa fidelidade + suavização: produz uma forma ampla e generalizada de "mancha".

Tamanho e renderização do payload

Isócronas grandes (especialmente solicitações de longa duração com fidelidade HIGH) podem conter dezenas de milhares de coordenadas, e a resposta JSON descompactada pode ter centenas de kilobytes ou mais.

  • Largura de banda: o tamanho da resposta JSON é significativo para solicitações de duração máxima com alta fidelidade.
  • Renderização: a renderização de polígonos extremamente detalhados afeta o desempenho do cliente. Para reduzir a contagem de vértices e o tamanho do payload, escolha polygonFidelity: MEDIUM ou LOW ou simplifique a geometria no cliente antes de renderizar usando um algoritmo de simplificação de linha, como Douglas-Peucker.

Latência e tempos limite do cliente

A latência de resposta aumenta com o tamanho da rede de estradas percorrida: durações curtas e os modos WALK e BICYCLE são mais rápidos, enquanto as solicitações longas de DRIVE e TWO_WHEELER (especialmente com TRAFFIC_AWARE) levam mais tempo.

  • Tempo limite recomendado do cliente: configure os prazos do cliente HTTP ou gRPC para pelo menos 30 segundos para que as solicitações longas não sejam canceladas antecipadamente por um tempo limite curto do cliente.

Tratamento de erros

Implemente a lógica de repetição com espera exponencial e jitter para respostas de limite de taxa 429 RESOURCE_EXHAUSTED e erros de servidor 5xx. Não tente novamente os erros de cliente 400, 403 ou 404 sem alterar sua solicitação:

  • INVALID_ARGUMENT (400): verifique se travelDuration está entre 1s e 3600s (DRIVE/TWO_WHEELER) ou 7200s (WALK/BICYCLE), se location não foi omitido e não é (0, 0) (ou se place é um ID de lugar válido) e se TRAFFIC_AWARE é usado apenas com DRIVE ou TWO_WHEELER. Um latitude ou longitude omitido é tratado como 0.0. Portanto, omitir apenas um deles geralmente não causa um erro 400 (a menos que o outro valor também seja 0.0). Verifique os dois valores se o isócrono aparecer no lugar errado.
  • PERMISSION_DENIED (403): verifique se a chave de API ou o token OAuth está incluído e se a API Isochrones e o faturamento estão ativados no seu projeto do Google Cloud.
  • NOT_FOUND (404): não foi possível resolver o place para um local ou não foi possível ajustar o ponto de partida a uma via próxima que possa ser usada pelo modo de viagem (em um raio de cerca de 200 metros ou menos para WALK e BICYCLE).
  • RESOURCE_EXHAUSTED (429): seu projeto excedeu a cota de solicitações por minuto (padrão de 300 QPM). Tentar novamente com a espera exponencial.