Tratte lunghe e molti punti

Molti TMS e sistemi di pianificazione calcolano già da soli il percorso (ad es. con Azure Maps, Google o TomTom) e poi necessitano solo del pedaggio per esattamente quel percorso. A tal fine le coordinate pianificate vengono inviate come punti all'API TollCalc.

Invio dei punti

POST /api/calculate accetta origin, destination e, opzionalmente, via (punti intermedi). Ogni punto è un indirizzo oppure una coordinata nel formato "lat;lon".

curl -X POST https://app.tollcalc.eu/api/calculate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "origin": "48.1374;11.5755",
    "destination": "52.5200;13.4050",
    "via": ["49.0134;12.1016", "50.1109;8.6821"],
    "vehicle": { "weight": 40, "axles": 5, "emission_class": "euro6", "co2_class": "class_1" }
  }'

Limiti e downsampling lato server

Il motore di routing elabora un numero limitato di punti per richiesta (attualmente 50 in totale, cioè partenza + destinazione + 48 via). TollCalc lo gestisce in modo intelligente:

• Indirizzi (da geocodificare prima): al massimo 48 via. Più indirizzi → HTTP 400.
• Coordinate ("lat;lon"): puoi inviarne di più. TollCalc riduce la catena lato server fino al limite (downsampling). Partenza e destinazione vengono sempre mantenute e la forma del percorso è prioritizzata tramite una preselezione Douglas-Peucker. Nessun tratto viene tagliato.

Importante: Il downsampling si applica solo se tutti i punti sono coordinate ("lat;lon"). Non appena è presente un indirizzo, vale ancora il limite di 48 via.

Controllo dello scostamento (assicurazione qualità)

Poiché una catena ridotta potrebbe teoricamente alterare il percorso, TollCalc verifica automaticamente la qualità: il percorso calcolato viene confrontato con i tuoi punti originali e lo scostamento massimo viene valutato rispetto alla lunghezza del percorso.

• ≤ 2 % → risposta normale; lo scostamento è nel campo geometry_deviation_km.
• > 2 % → HTTP 400 con error e un warning esplicativo.

Esempio di richiesta rifiutata:

{
  "error": "Downsampling-Abweichung zu groß",
  "warning": "Die aus den Stützpunkten berechnete Route weicht zu stark von der Eingabe ab: max. 67.87 km bzw. 2.14 % der Strecke (erlaubt 2 %). Bitte dichtere oder mehr Koordinaten im Format \"lat;lon\" senden."
}

(Il messaggio dell'API è attualmente in tedesco.)

In caso di downsampling riuscito la risposta contiene inoltre:

Perché routing con punti invece del map matching?

Si potrebbe agganciare una polilinea inviata alla rete stradale tramite map matching, invece di calcolare noi il percorso. TollCalc non lo fa deliberatamente, per un motivo semplice: il pedaggio dipende esattamente dal percorso effettuato.

Il pedaggio varia in base al tratto autostradale specifico, al gestore, a gallerie e pedaggi speciali, al sistema (aperto/chiuso) e al Paese. Un'uscita diversa o una strada parallela produce già un pedaggio errato. Il percorso deve quindi essere corretto al 100 %, non "all'incirca".

Il risultato del map matching dipende però fortemente dalla qualità dell'input:

• rumore GPS, frequenza di campionamento e proiezione dei punti inviati,
• lacune dovute a gallerie, traghetti o perdita di segnale,
• polilinee "semplificate" o levigate provenienti da sistemi di terzi.

Dall'esterno non possiamo sapere se la geometria inviata è davvero il percorso effettuato o una versione semplificata/alterata. Secondo il principio garbage in, garbage out indicheremmo un pedaggio per un percorso che il cliente non ha mai fatto, senza che nessuno se ne accorga.

Da qui l'approccio deliberato:

• I punti inviati sono punti vincolanti, non semplici "suggerimenti". Il motore ne ricava un percorso garantito come percorribile che attraversa ogni punto nell'ordine corretto.
• Il risultato è riproducibile e lo scostamento dai tuoi punti originali è misurabile e viene indicato.
• L'assicurazione qualità (downsampling + controllo dello scostamento) è a carico nostro, non del cliente. Il cliente non deve fornire un percorso al 100 % né eseguire il map matching: invia il percorso pianificato e noi ci occupiamo del percorso corretto e idoneo al pedaggio.

Il compromesso è deliberato: meglio un rifiuto trasparente (HTTP 400 con motivazione) quando i punti inviati non danno un percorso inequivocabile, che un pedaggio silenziosamente errato. Quando il nostro map matching sarà dimostrabilmente affidabile, lo rivaluteremo; fino ad allora il routing con punti resta la scelta affidabile.

Quando diventa difficile

Il downsampling è molto affidabile per i normali viaggi a lunga percorrenza. Diventa più difficile con:

• Viaggi molto lunghi su più giorni: più lungo è il percorso, maggiore è la distanza tra i punti dopo il downsampling.
• Giri di distribuzione con molte piccole fermate e anelli.
• Tratti in traghetto o di carico (grandi lacune nella traccia GPS): il percorso stradale può allora scostarsi notevolmente.
• Valori anomali GPS (fix scarso, galleria): un singolo punto impreciso può far salire lo scostamento.
• Percorsi volutamente senza pedaggio: se il motore passa per un'altra strada, cambia anche il pedaggio.

Buone pratiche per le integrazioni TMS

1. Un viaggio per richiesta: non inviare lo storico delle posizioni di più giorni.
2. Coordinate invece di indirizzi quando hai molti punti.
3. Campionamento sufficientemente denso: circa 1 punto per chilometro è sufficiente.
4. Pulisci il GPS: rimuovi i fix imprecisi (gpsFix=false, accuracy elevata).
5. Tratti in traghetto/carico come richieste separate.
6. Registra/monitora geometry_deviation_km per tenere d'occhio la qualità dei dati.

Valutazione onesta

TollCalc calcola il pedaggio del percorso effettuato dal motore di routing. Con catene di coordinate dense la corrispondenza è molto alta (in pratica di solito sotto l'1 %), ma, a differenza del map matching, non è una garanzia 1:1. Il controllo dello scostamento rende trasparente questa incertezza.

→ Calcola il pedaggio ora