API di ottimizzazione dei percorsi (REST + SOAP) – Guida per sviluppatori

Cosa puoi sviluppare con l’API di ottimizzazione dei percorsi TrackRoad#

L’API consente l’ottimizzazione dei percorsi per casi d’uso aziendali comuni:

• Sistemi di pianificazione delle consegne (courier, pacchi, grocery)
• Pianificazione dei servizi sul campo (tecnici, riparazioni, installazioni)
• Dispatch di flotte con più veicoli e più fermate
• Workflow di geocodifica e routing turn-by-turn
• Modalità Dispatch avanzate per diverse strategie di routing

Il motore di routing supporta vincoli come:

• Finestre temporali (vincoli di arrivo e partenza)
• Limiti di capacità (peso / volume)
• Bilanciamento di tempo e distanza tra i veicoli
• Più punti di partenza e arrivo per veicolo
• Fermate di pausa e tempo di servizio per fermata

REST vs SOAP#

API REST (JSON/XML)

REST è leggero e comune per integrazioni web e mobile. TrackRoad supporta chiamate REST con payload JSON o XML.

API SOAP

SOAP è comune nei sistemi enterprise e supporta riferimenti di servizio fortemente tipizzati in .NET. È utile se vuoi usare classi compilate come DispatchSpecification, Vehicle e Location.

Autenticazione (TrackServiceKey)#

TrackRoad utilizza una chiave API stabile chiamata TrackServiceKey. Non si comporta come una classica session ID a scadenza. Vedi autenticazione API per i dettagli completi.

• REST: invia la tua chiave nell’header HTTP: X-API-Key: YOUR_TRACKSERVICEKEY
• SOAP: invia la tua chiave in SessionIDHeader come SessionID

API Dispatch (chiamata principale di ottimizzazione)#

L’ottimizzazione dei percorsi viene eseguita con Dispatch. Dispatch prende veicoli più fermate e restituisce percorsi ottimizzati per veicolo.

Riferimento completo: API Dispatch

Endpoint SOAP WSDL

http://trackservice.trackroad.com/trackservice.asmx?wsdl

Input tipici di Dispatch

• Veicoli (ognuno con posizione di partenza e arrivo)
• Fermate (località)
• DispatchMode (Auto, EqualStop, SingleRegion, MultipleRegion, Optima, ecc.)
• MinimumOptimization (precisione)

Finestre temporali e modalità Optima#

TrackRoad supporta le finestre temporali tramite vincoli di arrivo e partenza alle fermate. Per ottenere i migliori risultati, TrackRoad consiglia di usare DispatchMode Optima con le finestre temporali.

Variabili chiave

• CanArriveEarly
• TimeConstraintArrival
• TimeConstraintDeparture

Se il tuo linguaggio non può passare valori datetime nulli, usa 0001-01-01T00:00:00. TrackRoad tratta le date minori o uguali al 1° gennaio 2012 come nulle.

Per saperne di più: Ottimizzazione dei percorsi con finestre temporali

Comprendere i risultati di Dispatch#

Dispatch restituisce percorsi ottimizzati per veicolo. Ogni risultato include fermate ordinate con metadati come:

• Sequenza delle fermate
• MatchCode e qualità del match dell’indirizzo
• Latitudine e Longitudine
• Tempo e distanza fino alla fermata successiva

Consigli su prestazioni e scalabilità

• Raggruppa le fermate quando possibile invece di ottimizzare un percorso alla volta
• Fornisci tempi di servizio e finestre temporali accurati per ottenere risultati realistici
• Usa la modalità Optima per pianificazioni con vincoli
• Aumenta MinimumOptimization per una qualità migliore con insiemi più grandi di fermate
• Usa il dispatch multi-veicolo per il routing di flotta invece di richieste separate

Esempio REST JSON (X-API-Key → Dispatch)#

Questo esempio mostra il flusso REST consigliato usando X-API-Key (TrackServiceKey).

Passo 1 — Imposta gli header di autenticazione

Headers:
X-API-Key: YOUR_TRACKSERVICEKEY
Content-Type: application/json

Passo 2 — Dispatch (ottimizza i percorsi)

Dispatch prende veicoli più fermate e restituisce percorsi ottimizzati. Questo esempio usa un veicolo e più fermate.

POST https://trackservice.trackroad.com/rest/dispatch
Headers:
X-API-Key: YOUR_TRACKSERVICEKEY
Content-Type: application/json

{
  "DispatchMode": "Optima",
  "DistanceUnit": "Mile",
  "MinimumOptimization": 1,
  "Vehicles": [
    {
      "Name": "Vehicle 1",
      "StartLocation": { "Name": "Depot", "Address": "350 5th Ave, New York, NY" },
      "FinishLocation": { "Name": "Depot", "Address": "350 5th Ave, New York, NY" },
      "TimeIn": "2025-12-25T08:00:00",
      "TimeOut": "2025-12-25T18:00:00",
      "CapacityWeight": 1000,
      "CapacityVolume": 100
    }
  ],
  "Stops": [
    {
      "Name": "Stop 1",
      "Address": "405 Lexington Ave, New York, NY",
      "ServiceTimeMinutes": 10,
      "TimeWindowStart": "2025-12-25T09:00:00",
      "TimeWindowEnd": "2025-12-25T11:00:00",
      "Weight": 120,
      "Volume": 12
    },
    {
      "Name": "Stop 2",
      "Address": "11 Wall St, New York, NY",
      "ServiceTimeMinutes": 8,
      "TimeWindowStart": "2025-12-25T10:00:00",
      "TimeWindowEnd": "2025-12-25T14:00:00",
      "Weight": 60,
      "Volume": 6
    },
    {
      "Name": "Stop 3",
      "Address": "200 Central Park West, New York, NY",
      "ServiceTimeMinutes": 12,
      "Weight": 80,
      "Volume": 8
    }
  ]
}

Suggerimento: Per le finestre temporali, usa DispatchMode = Optima. Se la tua integrazione non può inviare valori null, usa una data di default come 0001-01-01T00:00:00 per rappresentare “null”.

Esempio curl

curl -X POST "https://trackservice.trackroad.com/rest/dispatch" \
  -H "X-API-Key: YOUR_TRACKSERVICEKEY" \
  -H "Content-Type: application/json" \
  -d @dispatch-request.json

Login e Logout legacy sono disponibili per retrocompatibilità. Per la maggior parte delle integrazioni, usa X-API-Key (TrackServiceKey) in ogni richiesta.

Esempio SOAP C# (SessionIDHeader → Dispatch)

L’autenticazione SOAP di TrackRoad usa SessionIDHeader.SessionID = TrackServiceKey. Vedi autenticazione per i dettagli completi.

Endpoint SOAP WSDL

http://trackservice.trackroad.com/trackservice.asmx?wsdl

Esempio SOAP C# passo per passo

using System;
using System.Collections.Generic;
using TrackServiceRef; // your generated SOAP reference namespace

public class TrackRoadSoapExample
{
    public static void OptimizeRoutesWithSoap()
    {
        var client = new TrackServiceSoapClient();

        // TrackRoad SOAP uses TrackServiceKey as SessionID.
        string sessionId = "YOUR_TRACKSERVICEKEY";

        // Vehicles
        var vehicle = new Vehicle
        {
            Name = "Vehicle 1",
            StartLocation = new Location { Name = "Depot", Address = "350 5th Ave, New York, NY" },
            FinishLocation = new Location { Name = "Depot", Address = "350 5th Ave, New York, NY" },
            TimeIn = new DateTime(2025, 12, 25, 8, 0, 0),
            TimeOut = new DateTime(2025, 12, 25, 18, 0, 0),
            CapacityWeight = 1000,
            CapacityVolume = 100
        };

        // Stops
        var stops = new List<Location>
        {
            new Location
            {
                Name = "Stop 1",
                Address = "405 Lexington Ave, New York, NY",
                ServiceTime = 10,
                TimeConstraintArrival = new DateTime(2025, 12, 25, 9, 0, 0),
                TimeConstraintDeparture = new DateTime(2025, 12, 25, 11, 0, 0),
                CanArriveEarly = true,
                Weight = 120,
                Volume = 12
            },
            new Location
            {
                Name = "Stop 2",
                Address = "11 Wall St, New York, NY",
                ServiceTime = 8,
                TimeConstraintArrival = new DateTime(2025, 12, 25, 10, 0, 0),
                TimeConstraintDeparture = new DateTime(2025, 12, 25, 14, 0, 0),
                CanArriveEarly = true,
                Weight = 60,
                Volume = 6
            },
            new Location
            {
                Name = "Stop 3",
                Address = "200 Central Park West, New York, NY",
                ServiceTime = 12,
                Weight = 80,
                Volume = 8
            }
        };

        // Dispatch spec
        var spec = new DispatchSpecification
        {
            DispatchMode = DispatchMode.Optima,
            DistanceUnit = DistanceUnit.Mile,
            MinimumOptimization = 1,
            CurrentTime = DateTime.MinValue
        };

        // Dispatch
        var dispatchResult = client.Dispatch(sessionId, spec, new[] { vehicle }, stops.ToArray());

        if (!dispatchResult.Success)
            throw new Exception("Dispatch failed: " + dispatchResult.Message);

        foreach (var route in dispatchResult.Routes)
        {
            Console.WriteLine($"Vehicle: {route.VehicleName}");
            Console.WriteLine($"Distance: {route.Distance}");
            Console.WriteLine($"Duration: {route.Duration}");

            foreach (var stop in route.Stops)
                Console.WriteLine($"  {stop.Sequence}. {stop.Name}  ETA: {stop.ETA}");
        }
    }
}

Note

• Usa la modalità Optima per finestre temporali e pianificazioni.
• Fornisci gli orari di lavoro del driver (TimeIn, TimeOut) per un routing realistico.
• Se non puoi fornire valori datetime nulli, usa DateTime.MinValue o una regola data nulla.

Risoluzione dei problemi: errori API comuni e come correggerli#

L’ottimizzazione dei percorsi è un problema basato su vincoli. Se fornisci indirizzi non validi o vincoli impossibili, come finestre temporali troppo rigide, veicoli insufficienti o limiti di capacità superati, il motore Dispatch può restituire errori o produrre percorsi incompleti.

1) “Dispatch failed” o Success = false

• Indirizzi delle fermate non validi o incompleti
• Finestre temporali impossibili
• Orari di lavoro del veicolo troppo brevi
• Veicoli insufficienti per servire tutte le fermate
• Vincoli di capacità superati

2) Alcune fermate mancano nei percorsi

Cause comuni:

• Finestre temporali troppo rigide
• Orari di lavoro troppo rigidi
• Capacità superata
• Il tempo di servizio spinge il programma oltre i limiti di fattibilità

3) Corrispondenze indirizzo non valide o di bassa qualità (problemi MatchCode)

• Fornisci indirizzi completi (via, città, CAP, paese)
• Se hai già le coordinate, invia Latitude e Longitude
• Valida le fermate con geocodifica prima del Dispatch quando necessario

4) Le finestre temporali non sono fattibili

• Usa DispatchMode Optima
• Amplia le finestre temporali
• Consenti l’arrivo anticipato (CanArriveEarly = true) quando appropriato
• Aggiungi veicoli o aumenta gli orari di lavoro dei veicoli

5) Veicoli insufficienti o routing di flotta incompleto

• Aggiungi più veicoli
• Aumenta la capacità (peso e volume)
• Aumenta gli orari di lavoro
• Usa DispatchMode MinimumVehicles se il tuo obiettivo è minimizzare il numero di veicoli necessari

6) L’API restituisce “key invalid” (autenticazione)

L’autenticazione TrackRoad usa una chiave API stabile chiamata TrackServiceKey. “Key invalid” di solito significa che la chiave manca, è errata o è stata inviata nel posto sbagliato.

• REST: invia X-API-Key: TrackServiceKey
• SOAP: invia SessionIDHeader.SessionID = TrackServiceKey
• Vedi autenticazione API per i dettagli esatti.