Best practice per l'API Isochrone

Smussamento e fedeltà

Puoi personalizzare l'aspetto e la precisione dei poligoni di output utilizzando i parametri polygon_fidelity e enable_smoothing. Sebbene queste opzioni siano indipendenti, interagiscono per determinare la forma finale.

  • polygonFidelity (polygon_fidelity): risoluzione. Controlla le dimensioni delle celle della griglia spaziale sottostante utilizzate per calcolare l'area raggiungibile.

    • LOW: utilizza le celle della griglia più grandi (diverse centinaia di metri di larghezza). Ideale per coprire grandi aree senza spazi vuoti e ridurre al minimo il numero di vertici, con una forma generalizzata che può sovrastimare l'area raggiungibile lungo corridoi stradali stretti.
    • MEDIUM: precisione e dimensioni del payload bilanciate.
    • HIGH: utilizza le celle della griglia più piccole (circa 100-150 metri di larghezza). Il risultato è un'aderenza più stretta alla rete stradale, con più vertici, ma potrebbe produrre fori interni dove la rete stradale è sparsa.
    • Predefinita (POLYGON_FIDELITY_UNSPECIFIED): se non viene specificata, il servizio seleziona automaticamente la risoluzione in base alla modalità di viaggio e alla durata, utilizzando celle più piccole per durate brevi e per WALK e celle più grandi per durate lunghe. Per confrontare gli isocroni in base a durate o modalità di viaggio diverse, imposta polygonFidelity in modo esplicito in modo che utilizzino la stessa risoluzione.

    Le dimensioni delle celle sono approssimative. Le isocrone molto grandi potrebbero essere ulteriormente generalizzate per mantenere gestibili le dimensioni della risposta.

  • enableSmoothing (enable_smoothing): l'estetica. Controlla se i bordi a gradini delle celle della griglia definiti dalla fedeltà vengono arrotondati.
    • false (Raw): restituisce il confine allineato alla griglia. I bordi appaiono frastagliati o a gradini, riflettendo le celle della griglia. Ideale per l'accuratezza analitica, ad esempio per test point-in-polygon rigorosi.
    • true (Smussato): arrotonda gli angoli preservando approssimativamente l'area di ogni anello. Ideale per la visualizzazione su mappe. Poiché il confine non segue più le celle della griglia, non utilizzarlo per test rigorosi di punti all'interno di un poligono.

Come interagiscono: la fedeltà imposta il dettaglio di base su cui agisce l'algoritmo di smoothing.

  • Alta fedeltà + Smussamento: produce una forma dettagliata e dall'aspetto organico che segue da vicino le estremità delle strade.
  • Bassa fedeltà + Smussatura: produce una forma "blob" ampia e generalizzata.

Dimensioni del payload e rendering

Le isocrone di grandi dimensioni (soprattutto le richieste di lunga durata con fedeltà HIGH) possono contenere decine di migliaia di coordinate e la risposta JSON non compressa può essere di diverse centinaia di kilobyte o più.

  • Larghezza di banda: tieni presente che le dimensioni della risposta JSON sono significative per le richieste di durata massima con alta fedeltà.
  • Rendering: il rendering di poligoni estremamente dettagliati influisce sulle prestazioni del client. Per ridurre il numero di vertici e le dimensioni del payload, scegli polygonFidelity: MEDIUM o LOW oppure semplifica la geometria sul client prima del rendering utilizzando un algoritmo di semplificazione delle linee come Douglas-Peucker.

Latenza e timeout del client

La latenza della risposta aumenta con le dimensioni della rete stradale attraversata: le durate brevi e le modalità WALK e BICYCLE sono le più veloci, mentre le richieste DRIVE e TWO_WHEELER lunghe (soprattutto con TRAFFIC_AWARE) richiedono più tempo.

  • Timeout client consigliato: configura le scadenze del client HTTP o gRPC su almeno 30 secondi in modo che le richieste lunghe non vengano interrotte in anticipo da un timeout client breve.

Gestione degli errori

Implementa la logica di ripetizione con backoff esponenziale e jitter per le risposte di limitazione di frequenza 429 RESOURCE_EXHAUSTED e gli errori del server 5xx. Non riprovare a inviare gli errori client 400, 403 o 404 senza modificare la richiesta:

  • INVALID_ARGUMENT (400): verifica che travelDuration sia compreso tra 1s e 3600s (DRIVE/TWO_WHEELER) o 7200s (WALK/BICYCLE), che location non sia omesso e non sia (0, 0) (o che place sia un ID luogo valido) e che TRAFFIC_AWARE venga utilizzato solo con DRIVE o TWO_WHEELER. Un valore latitude o longitude omesso viene trattato come 0.0, quindi l'omissione di uno solo di questi valori di solito non causa un errore 400 (a meno che anche l'altro valore non sia 0.0). Controlla entrambi i valori se l'isocrona appare nel posto sbagliato.
  • PERMISSION_DENIED (403): verifica che la chiave API o il token OAuth siano inclusi e che l'API Isochrones e la fatturazione siano abilitate nel tuo progetto Google Cloud.
  • NOT_FOUND (404): non è stato possibile risolvere place in una località o non è stato possibile agganciare l'origine a una strada vicina utilizzabile dalla modalità di viaggio (entro circa 200 metri o meno per WALK e BICYCLE).
  • RESOURCE_EXHAUSTED (429): il tuo progetto ha superato la quota di richieste al minuto (valore predefinito 300 QPM). Riprova con un backoff esponenziale.