API Dispatch (Ottimizzazione Percorsi)

Q: Come si autentica Dispatch in REST e SOAP?

REST usa il tuo TrackServiceKey nell'header X-API-Key. SOAP usa lo stesso TrackServiceKey in SessionIDHeader come SessionID.

Q: Per gli stop servono LatLong o Address?

LatLong è preferibile. Se LatLong non è fornito, Address è obbligatorio affinché TrackRoad possa geocodificare lo stop.

Usa Dispatch per ottimizzare percorsi su più veicoli e molti stop. Dispatch restituisce un percorso ordinato per veicolo con tempi, distanza e assegnazioni per delivery routing, field service, corrieri e pianificazione flotte.

Dispatch assegna gli stop su più veicoli e restituisce percorsi ottimizzati con ordine delle fermate, ETA, distanza e durata per ogni veicolo.

Ti serve il contratto completo?

Usa Swagger per i modelli REST e il WSDL per i dettagli di integrazione SOAP.

Apri Swagger UI Apri SOAP WSDL Panoramica Riferimento API

Indice dei contenuti

Cosa fa Dispatch
Modalità Optima, Time Window e TimeWindowDepot
Pickup e consegne multiple
Endpoint e URL di base
Autenticazione
Schema della richiesta
Schema della risposta
Errori comuni
Best practice
Endpoint correlati
FAQ

Cosa fa Dispatch#

Dispatch risolve un problema di instradamento multiveicolo. Assegna gli stop ai veicoli e ordina ogni percorso usando vincoli come finestre temporali, capacità, priorità e posizioni di partenza o arrivo.

LatLong è preferibile. Ogni stop dovrebbe includere LatLong quando possibile. Se LatLong non è fornito, devi indicare Address affinché il servizio possa geocodificare lo stop.

Il metodo Dispatch accetta un elenco di veicoli e un elenco di location di stop. Ogni veicolo può includere una posizione di partenza e una posizione finale facoltativa. Ogni location può contenere nome, campi indirizzo, latitudine e longitudine.

Se latitudine e longitudine sono presenti, TrackRoad le usa direttamente. In caso contrario, il servizio geocodifica l'indirizzo per ottenere le coordinate.

Dispatch restituisce elementi veicolo. Ogni elemento veicolo contiene il percorso assegnato come elenco ordinato di stop, ottimizzato in base a posizione, capacità, tempi e altri fattori di routing.

Quando è disponibile un solo veicolo, Dispatch esegue solo l'ottimizzazione del percorso. Le modalità di dispatch contano soprattutto quando sono disponibili più veicoli.

Se non sai quale modalità di dispatch usare, inizia con Auto. Per un'ottimizzazione a veicolo singolo altamente accurata, usa Optima.

Modalità Optima, Time Window e TimeWindowDepot#

In alcuni linguaggi potrebbe non essere possibile passare un datetime nullo. In tal caso, usa 0001-01-01T00:00:00. Le date precedenti alla soglia del sistema vengono trattate come valori null.

Per risultati migliori, usa DispatchMode Optima.

Tre variabili influenzano il comportamento del dispatch con finestre temporali:

CanArriveEarly
TimeConstraintArrival
TimeConstraintDeparture

Opzione 1: CanArriveEarly = true

Quando CanArriveEarly è true, la finestra temporale inizia all'inizio della giornata. Se TimeConstraintArrival è null, lo stop può essere visitato in qualsiasi momento del giorno. Se TimeConstraintArrival è impostato, definisce l'ultimo orario di arrivo accettabile. L'orario di partenza viene ignorato.

Opzione 2: CanArriveEarly = false

Quando CanArriveEarly è false, arrivo e partenza definiscono la finestra temporale consentita. Se l'arrivo è impostato e la partenza è null, lo stop viene trattato come un appuntamento preciso. Se entrambi sono impostati, TrackRoad cerca di visitare lo stop entro quell'intervallo.

Opzione 3: Due finestre temporali

Puoi anche specificare una seconda finestra temporale usando TimeConstraintArrival2 e TimeConstraintDeparture2. È utile quando uno stop può essere visitato solo in due periodi distinti, ad esempio con restrizioni di consegna nel centro città. TimeWindowDepot segue la stessa logica ma presume che i veicoli partano e terminino da un deposito comune.

Le pause possono essere modellate con LocationType = Break. Le catene di pickup e consegna multiple supportano una sola finestra temporale di consegna a livello di consegna e quel vincolo temporale figlio non può essere più restrittivo del vincolo padre.

Pickup e consegne multiple#

Dispatch supporta il chaining di pickup e consegne. È utile per operazioni di corriere e workflow in cui uno stop deve essere visitato prima di un altro.

Usa Midway per il primo stop di una catena e Delivery per specificare la location successiva correlata. Usa DeliveryNonStop per determinare se la consegna collegata deve avvenire immediatamente o può avvenire più tardi nello stesso percorso.

Ad esempio, se un pacco viene ritirato alla location B e consegnato alla location M, TrackRoad preserva la relazione richiesta tra ritiro e consegna continuando a ottimizzare il percorso rispetto agli stop rimanenti.

DeliveryNonStop = true

Quando DeliveryNonStop è true, lo stop di consegna collegato deve essere visitato immediatamente dopo lo stop di pickup.

DeliveryNonStop = false

Quando DeliveryNonStop è false, la consegna collegata deve comunque avvenire dopo il pickup, ma non necessariamente subito.

Puoi concatenare più consegne, come B → M → N, impostando Delivery e KeepSameOrder su ogni stop collegato.

Per i lavori di andata e ritorno, definisci ritiro, consegna e ritorno come una catena. Una raccomandazione comune è DeliveryNonStop = false e KeepSameOrder = true per un'ottimizzazione più flessibile mantenendo l'ordine di business.

Esempio TrackRoad API di stop andata e ritorno — Esempio: stop di andata e ritorno.

Esempio TrackRoad API di percorso andata e ritorno — Esempio: percorso di andata e ritorno.

Endpoint e URL di base#

REST

Voce	Valore
URL di base	https://trackservice.trackroad.com
Endpoint	`POST /rest/dispatch`
URL completo	https://trackservice.trackroad.com/rest/dispatch
Content-Type	`application/json`

SOAP

Voce	Valore
Endpoint	https://trackservice.trackroad.com/TrackService.asmx
WSDL	https://trackservice.trackroad.com/TrackService.asmx?WSDL
Metodo	`Dispatch`
SOAPAction	http://trackservice.trackroad.com/Dispatch

SOAP usa gli stessi modelli DispatchSpecification e DispatchResult. La differenza principale è l'envelope SOAP e l'autenticazione basata su header.

Autenticazione#

Autenticazione REST (X-API-Key)

Includi il tuo TrackServiceKey nell'header X-API-Key in ogni richiesta. Genera la chiave nel tuo account TrackRoad su Autenticazione API .

curl -X POST "https://trackservice.trackroad.com/rest/dispatch" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_TRACKSERVICEKEY" \
  -d '{ "RoutingService": 0, "DistanceUnit": 0, "RouteOptimize": 0, "Vehicles": [], "Locations": [] }'

using System.Net.Http;
using System.Text;

var url = "https://trackservice.trackroad.com/rest/dispatch";
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-API-Key", "YOUR_TRACKSERVICEKEY");

var json = @"{
  ""RoutingService"": 0,
  ""DistanceUnit"": 0,
  ""RouteOptimize"": 0,
  ""Vehicles"": [],
  ""Locations"": []
}";
using var content = new StringContent(json, Encoding.UTF8, "application/json");

var resp = await http.PostAsync(url, content);
Console.WriteLine(await resp.Content.ReadAsStringAsync());

const url = "https://trackservice.trackroad.com/rest/dispatch";

const res = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_TRACKSERVICEKEY"
  },
  body: JSON.stringify({
    RoutingService: 0,
    DistanceUnit: 0,
    RouteOptimize: 0,
    Vehicles: [],
    Locations: []
  })
});

console.log(await res.text());

import okhttp3.*;

public class Main {
  public static void main(String[] args) throws Exception {
    OkHttpClient client = new OkHttpClient();

    String json = "{"
      + "\"RoutingService\":0,"
      + "\"DistanceUnit\":0,"
      + "\"RouteOptimize\":0,"
      + "\"Vehicles\":[],"
      + "\"Locations\":[]"
      + "}";

    RequestBody body = RequestBody.create(json, MediaType.parse("application/json"));

    Request request = new Request.Builder()
      .url("https://trackservice.trackroad.com/rest/dispatch")
      .post(body)
      .addHeader("Content-Type", "application/json")
      .addHeader("X-API-Key", "YOUR_TRACKSERVICEKEY")
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

import requests

url = "https://trackservice.trackroad.com/rest/dispatch"
headers = {
  "Content-Type": "application/json",
  "X-API-Key": "YOUR_TRACKSERVICEKEY"
}
payload = {
  "RoutingService": 0,
  "DistanceUnit": 0,
  "RouteOptimize": 0,
  "Vehicles": [],
  "Locations": []
}

r = requests.post(url, headers=headers, json=payload)
print(r.text)

<?php
$url = "https://trackservice.trackroad.com/rest/dispatch";

$payload = json_encode([
  "RoutingService" => 0,
  "DistanceUnit" => 0,
  "RouteOptimize" => 0,
  "Vehicles" => [],
  "Locations" => []
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: YOUR_TRACKSERVICEKEY"
  ],
  CURLOPT_POSTFIELDS => $payload
]);

echo curl_exec($ch);
curl_close($ch);

require "net/http"
require "json"

uri = URI("https://trackservice.trackroad.com/rest/dispatch")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

req = Net::HTTP::Post.new(uri)
req["Content-Type"] = "application/json"
req["X-API-Key"] = "YOUR_TRACKSERVICEKEY"
req.body = {
  RoutingService: 0,
  DistanceUnit: 0,
  RouteOptimize: 0,
  Vehicles: [],
  Locations: []
}.to_json

res = http.request(req)
puts res.body

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  url := "https://trackservice.trackroad.com/rest/dispatch"
  jsonBody := []byte(`{"RoutingService":0,"DistanceUnit":0,"RouteOptimize":0,"Vehicles":[],"Locations":[]}`)

  req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonBody))
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("X-API-Key", "YOUR_TRACKSERVICEKEY")

  resp, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer resp.Body.Close()

  b, _ := io.ReadAll(resp.Body)
  fmt.Println(string(b))
}

import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse

fun main() {
  val url = "https://trackservice.trackroad.com/rest/dispatch"
  val json = """{"RoutingService":0,"DistanceUnit":0,"RouteOptimize":0,"Vehicles":[],"Locations":[]}"""

  val client = HttpClient.newHttpClient()
  val req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Content-Type", "application/json")
    .header("X-API-Key", "YOUR_TRACKSERVICEKEY")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build()

  val resp = client.send(req, HttpResponse.BodyHandlers.ofString())
  println(resp.body())
}

#include <stdio.h>
#include <curl/curl.h>

int main(void) {
  CURL *curl = curl_easy_init();
  if(!curl) return 1;

  const char *url = "https://trackservice.trackroad.com/rest/dispatch";
  const char *json = "{\"RoutingService\":0,\"DistanceUnit\":0,\"RouteOptimize\":0,\"Vehicles\":[],\"Locations\":[]}";

  struct curl_slist *headers = NULL;
  headers = curl_slist_append(headers, "Content-Type: application/json");
  headers = curl_slist_append(headers, "X-API-Key: YOUR_TRACKSERVICEKEY");

  curl_easy_setopt(curl, CURLOPT_URL, url);
  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json);

  CURLcode res = curl_easy_perform(curl);

  curl_slist_free_all(headers);
  curl_easy_cleanup(curl);

  return (res == CURLE_OK) ? 0 : 1;
}

#include <curl/curl.h>
#include <string>

int main() {
  CURL* curl = curl_easy_init();
  if(!curl) return 1;

  std::string url = "https://trackservice.trackroad.com/rest/dispatch";
  std::string json = R"({"RoutingService":0,"DistanceUnit":0,"RouteOptimize":0,"Vehicles":[],"Locations":[]})";

  struct curl_slist* headers = NULL;
  headers = curl_slist_append(headers, "Content-Type: application/json");
  headers = curl_slist_append(headers, "X-API-Key: YOUR_TRACKSERVICEKEY");

  curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json.c_str());

  CURLcode res = curl_easy_perform(curl);

  curl_slist_free_all(headers);
  curl_easy_cleanup(curl);

  return (res == CURLE_OK) ? 0 : 1;
}

#import <Foundation/Foundation.h>

int main() {
  @autoreleasepool {
    NSURL *url = [NSURL URLWithString:@"https://trackservice.trackroad.com/rest/dispatch"];
    NSMutableURLRequest *req = [NSMutableURLRequest requestWithURL:url];
    [req setHTTPMethod:@"POST"];
    [req setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
    [req setValue:@"YOUR_TRACKSERVICEKEY" forHTTPHeaderField:@"X-API-Key"];

    NSDictionary *payload = @{
      @"RoutingService": @0,
      @"DistanceUnit": @0,
      @"RouteOptimize": @0,
      @"Vehicles": @[],
      @"Locations": @[]
    };

    NSData *body = [NSJSONSerialization dataWithJSONObject:payload options:0 error:nil];
    [req setHTTPBody:body];

    NSURLSessionDataTask *task =
      [[NSURLSession sharedSession] dataTaskWithRequest:req
      completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
        if (error) { NSLog(@"%@", error); return; }
        NSString *text = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
        NSLog(@"%@", text);
      }];

    [task resume];
    [[NSRunLoop currentRunLoop] run];
  }
  return 0;
}

import Foundation

let url = URL(string: "https://trackservice.trackroad.com/rest/dispatch")!
var req = URLRequest(url: url)
req.httpMethod = "POST"
req.setValue("application/json", forHTTPHeaderField: "Content-Type")
req.setValue("YOUR_TRACKSERVICEKEY", forHTTPHeaderField: "X-API-Key")

let payload: [String: Any] = [
  "RoutingService": 0,
  "DistanceUnit": 0,
  "RouteOptimize": 0,
  "Vehicles": [],
  "Locations": []
]
req.httpBody = try! JSONSerialization.data(withJSONObject: payload)

let task = URLSession.shared.dataTask(with: req) { data, _, error in
  if let error = error { print(error); return }
  print(String(data: data ?? Data(), encoding: .utf8) ?? "")
}
task.resume()
RunLoop.main.run()

Conserva le chiavi API lato server. Non incorporare chiavi in codice browser o client mobile.

Autenticazione SOAP (SessionIDHeader)

Per le richieste SOAP, invia il tuo TrackServiceKey in SessionIDHeader come SessionID. Login e Logout legacy non sono necessari quando usi l'autenticazione TrackServiceKey.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <SessionIDHeader xmlns="http://trackservice.trackroad.com/">
      <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
    </SessionIDHeader>
  </soap:Header>
  <soap:Body>
    <Dispatch xmlns="http://trackservice.trackroad.com/">
      <specification>
        <RoutingService>0</RoutingService>
        <DistanceUnit>0</DistanceUnit>
        <RouteOptimize>0</RouteOptimize>
        <Vehicles />
        <Locations />
      </specification>
    </Dispatch>
  </soap:Body>
</soap:Envelope>

/*
  1) Add Service Reference to:
     https://trackservice.trackroad.com/TrackService.asmx?WSDL

  2) Set SessionIDHeader.SessionID = YOUR_TRACKSERVICEKEY
     then call Dispatch(spec).
*/

var client = new TrackService.TrackServiceSoapClient();
var header = new TrackService.SessionIDHeader { SessionID = "YOUR_TRACKSERVICEKEY" };

var spec = new TrackService.DispatchSpecification
{
    RoutingService = TrackService.RoutingService.NetRoad,
    DistanceUnit = TrackService.DistanceUnit.Mile,
    RouteOptimize = TrackService.RouteOptimize.MinimizeTime,
    Vehicles = new TrackService.Vehicle[] { },
    Locations = new TrackService.Location[] { }
};

var result = client.Dispatch(header, spec);

Namespace e prefissi SOAP possono variare in base al tooling. Un client generato da WSDL è di solito l'opzione più semplice.

Schema della richiesta#

Il body della richiesta è un singolo oggetto: DispatchSpecification. Come minimo, fornisci veicoli e location.

DispatchSpecification

Proprietà	Tipo	Obbligatorio	Descrizione
`RoutingService`	int (enum)	No	Motore di routing. 0 = NetRoad, 1 = TrackRoad, 2 = Bing. Consigliato: 0 = NetRoad.
`IsNeedMatchCode`	bool	No	Se true, include i codici di qualità del geocoding dove rilevanti.
`CurrentTime`	string (date-time)	No	Riferimento temporale corrente usato per i vincoli di tempo in formato ISO 8601.
`DispatchMode`	int (enum)	No	Strategia di ottimizzazione. Per i suggerimenti sulle modalità, vedi Modalità Dispatch.
`MinimumOptimization`	int	No	Soglia di intensità dell'ottimizzazione. Intervallo tipico: da 1 a 10.
`DistanceUnit`	int (enum)	No	0 = Miglio, 1 = Chilometro.
`RouteOptimize`	int (enum)	No	0 = MinimizeTime, 1 = MinimizeDistance. Consigliato: 0 = MinimizeTime.
`Vehicles`	Vehicle[]	No	Veicoli disponibili per il dispatch.
`Locations`	Location[]	Sì	Stop da assegnare e ordinare.

DispatchMode

Proprietà	Tipo	Valore	Descrizione
`Auto`	int	0	Seleziona automaticamente una strategia di dispatch adatta. Miglior punto di partenza predefinito.
`EqualStop`	int	1	Cerca di distribuire un numero uguale di stop tra i veicoli.
`SingleRegion`	int	2	Utile quando i veicoli sono geograficamente dispersi ma servono stop in aree simili.
`MultipleRegion`	int	3	Utile per veicoli che operano in città diverse o regioni lontane e per il dispatch sul campo in tempo reale.
`EqualHour`	int	4	Cerca di dividere il lavoro in percorsi con durata totale simile.
`EqualDistance`	int	5	Cerca di dividere il lavoro in percorsi con distanza totale simile.
`TimeWindow`	int	6	Dà priorità agli appuntamenti e alle finestre di consegna. L'ottimizzazione può essere ridotta per rispettare i vincoli temporali.
`TimeWindowDepot`	int	7	Modalità con finestre temporali che presume un deposito centrale condiviso dai veicoli.
`Optima`	int	8	Modalità ad alta precisione per un singolo veicolo, con o senza finestre temporali.
`BalanceLocation`	int	9	Bilancia il numero di stop assegnati tra più autisti.
`BalanceTime`	int	10	Bilancia il tempo di percorso tra più autisti.
`MinimumVehicles`	int	11	Seleziona il numero minimo di veicoli necessario per servire tutti gli stop, tenendo conto dei fattori di routing.

Vehicle

Proprietà	Tipo	Obbligatorio	Descrizione
`Name`	string	Consigliato	Identificatore del veicolo visualizzato nei risultati.
`Email`	string	No	Contatto facoltativo del conducente o del veicolo.
`Group`	string	No	Campo facoltativo di raggruppamento come team, deposito o regione.
`Speed`	int	No	Override facoltativo della velocità. Se impostato a 0, viene usata la velocità stradale predefinita.
`MaxStops`	int	No	Numero massimo di stop per percorso del veicolo.
`MaxWeight`	double	No	Capacità massima di peso del veicolo.
`MaxSkids`	int	No	Capacità massima di skid del veicolo.
`MaxVolume`	double	No	Capacità massima di volume del veicolo.
`MaxMinutes`	int	No	Durata massima del percorso del veicolo.
`FuelCost`	double	No	Parametro di costo facoltativo usato da alcune modalità di ottimizzazione.
`OnTheRoad`	bool	No	Se true, un percorso multi-giornaliero può continuare dalla posizione finale del giorno precedente invece di tornare al punto di partenza originale.
`Tin`	string (date-time)	No	Timestamp di disponibilità iniziale del veicolo.
`Tout`	string (date-time)	No	Timestamp di disponibilità finale del veicolo.
`StartLocation`	Location	No	Deposito o posizione iniziale facoltativa del veicolo.
`FinishLocation`	Location	No	Deposito o posizione finale facoltativa del veicolo.
`Roles`	string	No	Stringa di ruolo facoltativa che può essere confrontata con le condizioni degli stop.
`TransportType`	int (enum)	No	Modalità di trasporto come auto, camion, autobus, moto, pedone, scooter o bicicletta.
`ExcludeTolls`	bool	No	Specifica se le strade a pedaggio devono essere evitate.
`ExcludeHighways`	bool	No	Specifica se le autostrade devono essere evitate.
`UseTruckRoute`	bool	No	Specifica se i percorsi per camion devono essere preferiti o consentiti.
`Width`	float	No	Larghezza del veicolo in metri.
`Height`	float	No	Altezza del veicolo in metri.
`Length`	float	No	Lunghezza del veicolo in metri.
`AxleLoad`	float	No	Carico per asse del veicolo in tonnellate metriche.
`AxleCount`	int	No	Numero di assi.

Esempio TrackRoad API della funzione OnTheRoad del veicolo — Esempio: comportamento del percorso giornaliero con OnTheRoad attivo rispetto a disattivo.

Location

Ogni location dovrebbe includere LatLong quando possibile. Se le coordinate mancano, è obbligatorio Address affinché TrackRoad possa geocodificare lo stop.

Proprietà	Tipo	Obbligatorio	Descrizione
`MatchCode`	int (enum)	No	Codice di qualità della geocodifica.
`Name`	string	No	Etichetta dello stop mostrata nei risultati.
`Delivery`	string	No	Nome della location di consegna collegata o etichetta cliente.
`DeliveryNonStop`	bool	No	Determina se la consegna collegata deve avvenire immediatamente dopo lo stop corrente.
`KeepSameOrder`	bool	No	Se true, preserva l'ordine relativo definito nella richiesta.
`Vehicle`	string	No	Pre-assegnazione facoltativa a un veicolo specifico tramite nome.
`Description`	string	No	Note o descrizione facoltative.
`Phone`	string	No	Numero di telefono di contatto facoltativo.
`LatLong`	LatLong	Condizionale	Input coordinate preferito. Obbligatorio se Address non è fornito.
`Address`	Address	Condizionale	Input indirizzo usato per la geocodifica quando LatLong non è fornito.
`Priority`	int	No	Indicazione di priorità per l'ottimizzazione.
`Wait`	int	No	Tempo di servizio o attesa allo stop.
`Volume`	double	No	Domanda di volume consumata dalla capacità del veicolo.
`Weight`	double	No	Domanda di peso consumata dalla capacità del veicolo.
`Skids`	int	No	Domanda di skid consumata dalla capacità del veicolo.
`TimeConstraintArrival`	string (date-time)	No	Valore di arrivo della finestra temporale primaria.
`TimeConstraintDeparture`	string (date-time)	No	Valore di partenza della finestra temporale primaria.
`TimeConstraintArrival2`	string (date-time)	No	Valore di arrivo della seconda finestra temporale facoltativa.
`TimeConstraintDeparture2`	string (date-time)	No	Valore di partenza della seconda finestra temporale facoltativa.
`LocationType`	int (enum)	No	0 = Midway, 1 = Start, 2 = Finish, 3 = Delivery, 4 = MidwayDrop, 5 = Break.
`CanArriveEarly`	bool	No	Se false, non è consentito arrivare prima della finestra temporale prevista.
`Conditions`	string	No	Condizione facoltativa di business rule o matching di ruolo.

LatLong

Proprietà	Tipo	Obbligatorio	Descrizione
`Latitude`	double	Sì	Latitudine in gradi (da -90 a 90).
`Longitude`	double	Sì	Longitudine in gradi (da -180 a 180).

Address

Proprietà	Tipo	Obbligatorio	Descrizione
`Street`	string	Consigliato	Indirizzo stradale.
`City`	string	Consigliato	Città.
`State`	string	No	Stato o regione.
`PostalCode`	string	No	CAP o codice postale.
`Country`	string	Consigliato	Paese.

Schema della risposta#

Una risposta riuscita restituisce DispatchResult contenente elementi di percorso per veicolo ed eventuali errori o avvisi.

DispatchResult

Proprietà	Tipo	Descrizione
`Items`	VehicleItem[]	Elementi di risultato per veicolo contenenti il percorso assegnato.
`Errors`	Error[]	Errori o avvisi facoltativi.
`Status`	int (enum)	Stato dell'operazione: 0 = None, 1 = Success, 2 = Failed, 3 = SuccessWithErrors.

VehicleItem

Proprietà	Tipo	Descrizione
`Vehicle`	Vehicle	Il veicolo associato a questo percorso.
`Locations`	Location[]	Location ordinate assegnate a quel veicolo.

Error

Proprietà	Tipo	Descrizione
`Message`	string	Messaggio di errore o avviso leggibile dall'utente.

Esempi#

I blocchi di codice di esempio per richiesta e risposta possono restare invariati e non richiedono localizzazione.

REST: Minimal request example (recommended pattern)#

{
  "RoutingService": 0,
  "DistanceUnit": 0,
  "RouteOptimize": 0,
  "DispatchMode": 0,
  "Vehicles": [
    {
      "Name": "Truck 1",
      "StartLocation": { "LatLong": { "Latitude": 37.7946, "Longitude": -122.3950 }, "LocationType": 1 },
      "FinishLocation": { "LatLong": { "Latitude": 37.7946, "Longitude": -122.3950 }, "LocationType": 2 }
    }
  ],
  "Locations": [
    { "Name": "Stop A", "LatLong": { "Latitude": 37.7897, "Longitude": -122.4011 }, "LocationType": 0 },
    { "Name": "Stop B", "LatLong": { "Latitude": 37.7810, "Longitude": -122.4110 }, "LocationType": 0 }
  ]
}

REST request examples (multiple languages)#

curl -X POST "https://trackservice.trackroad.com/rest/dispatch" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_TRACKSERVICEKEY" \
  -d '{
    "RoutingService": 0,
    "DistanceUnit": 0,
    "RouteOptimize": 0,
    "DispatchMode": 0,
    "Vehicles": [
      {
        "Name": "Truck 1",
        "StartLocation": { "LatLong": { "Latitude": 37.7946, "Longitude": -122.3950 }, "LocationType": 1 },
        "FinishLocation": { "LatLong": { "Latitude": 37.7946, "Longitude": -122.3950 }, "LocationType": 2 }
      }
    ],
    "Locations": [
      { "Name": "Stop A", "LatLong": { "Latitude": 37.7897, "Longitude": -122.4011 }, "LocationType": 0 },
      { "Name": "Stop B", "LatLong": { "Latitude": 37.7810, "Longitude": -122.4110 }, "LocationType": 0 }
    ]
  }'

using System.Net.Http;
using System.Text;

var url = "https://trackservice.trackroad.com/rest/dispatch";
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-API-Key", "YOUR_TRACKSERVICEKEY");

var json = @"{
  ""RoutingService"": 0,
  ""DistanceUnit"": 0,
  ""RouteOptimize"": 0,
  ""DispatchMode"": 0,
  ""Vehicles"": [
    {
      ""Name"": ""Truck 1"",
      ""StartLocation"": { ""LatLong"": { ""Latitude"": 37.7946, ""Longitude"": -122.3950 }, ""LocationType"": 1 },
      ""FinishLocation"": { ""LatLong"": { ""Latitude"": 37.7946, ""Longitude"": -122.3950 }, ""LocationType"": 2 }
    }
  ],
  ""Locations"": [
    { ""Name"": ""Stop A"", ""LatLong"": { ""Latitude"": 37.7897, ""Longitude"": -122.4011 }, ""LocationType"": 0 },
    { ""Name"": ""Stop B"", ""LatLong"": { ""Latitude"": 37.7810, ""Longitude"": -122.4110 }, ""LocationType"": 0 }
  ]
}";
using var content = new StringContent(json, Encoding.UTF8, "application/json");

var resp = await http.PostAsync(url, content);
Console.WriteLine(await resp.Content.ReadAsStringAsync());

const url = "https://trackservice.trackroad.com/rest/dispatch";

const payload = {
  RoutingService: 0,
  DistanceUnit: 0,
  RouteOptimize: 0,
  DispatchMode: 0,
  Vehicles: [
    {
      Name: "Truck 1",
      StartLocation: { LatLong: { Latitude: 37.7946, Longitude: -122.3950 }, LocationType: 1 },
      FinishLocation: { LatLong: { Latitude: 37.7946, Longitude: -122.3950 }, LocationType: 2 }
    }
  ],
  Locations: [
    { Name: "Stop A", LatLong: { Latitude: 37.7897, Longitude: -122.4011 }, LocationType: 0 },
    { Name: "Stop B", LatLong: { Latitude: 37.7810, Longitude: -122.4110 }, LocationType: 0 }
  ]
};

const res = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_TRACKSERVICEKEY"
  },
  body: JSON.stringify(payload)
});

console.log(await res.text());

import okhttp3.*;

public class Main {
  public static void main(String[] args) throws Exception {
    OkHttpClient client = new OkHttpClient();

    String json = "{"
      + "\"RoutingService\":0,"
      + "\"DistanceUnit\":0,"
      + "\"RouteOptimize\":0,"
      + "\"DispatchMode\":0,"
      + "\"Vehicles\":[{"
        + "\"Name\":\"Truck 1\","
        + "\"StartLocation\":{\"LatLong\":{\"Latitude\":37.7946,\"Longitude\":-122.3950},\"LocationType\":1},"
        + "\"FinishLocation\":{\"LatLong\":{\"Latitude\":37.7946,\"Longitude\":-122.3950},\"LocationType\":2}"
      + "}],"
      + "\"Locations\":[{"
        + "\"Name\":\"Stop A\","
        + "\"LatLong\":{\"Latitude\":37.7897,\"Longitude\":-122.4011},"
        + "\"LocationType\":0"
      + "},{"
        + "\"Name\":\"Stop B\","
        + "\"LatLong\":{\"Latitude\":37.7810,\"Longitude\":-122.4110},"
        + "\"LocationType\":0"
      + "}]"
      + "}";

    RequestBody body = RequestBody.create(json, MediaType.parse("application/json"));

    Request request = new Request.Builder()
      .url("https://trackservice.trackroad.com/rest/dispatch")
      .post(body)
      .addHeader("Content-Type", "application/json")
      .addHeader("X-API-Key", "YOUR_TRACKSERVICEKEY")
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

import requests

url = "https://trackservice.trackroad.com/rest/dispatch"
headers = {
  "Content-Type": "application/json",
  "X-API-Key": "YOUR_TRACKSERVICEKEY"
}

payload = {
  "RoutingService": 0,
  "DistanceUnit": 0,
  "RouteOptimize": 0,
  "DispatchMode": 0,
  "Vehicles": [
    {
      "Name": "Truck 1",
      "StartLocation": { "LatLong": { "Latitude": 37.7946, "Longitude": -122.3950 }, "LocationType": 1 },
      "FinishLocation": { "LatLong": { "Latitude": 37.7946, "Longitude": -122.3950 }, "LocationType": 2 }
    }
  ],
  "Locations": [
    { "Name": "Stop A", "LatLong": { "Latitude": 37.7897, "Longitude": -122.4011 }, "LocationType": 0 },
    { "Name": "Stop B", "LatLong": { "Latitude": 37.7810, "Longitude": -122.4110 }, "LocationType": 0 }
  ]
}

r = requests.post(url, headers=headers, json=payload)
print(r.text)

<?php
$url = "https://trackservice.trackroad.com/rest/dispatch";

$payload = json_encode([
  "RoutingService" => 0,
  "DistanceUnit" => 0,
  "RouteOptimize" => 0,
  "DispatchMode" => 0,
  "Vehicles" => [[
    "Name" => "Truck 1",
    "StartLocation" => [ "LatLong" => [ "Latitude" => 37.7946, "Longitude" => -122.3950 ], "LocationType" => 1 ],
    "FinishLocation" => [ "LatLong" => [ "Latitude" => 37.7946, "Longitude" => -122.3950 ], "LocationType" => 2 ]
  ]],
  "Locations" => [
    [ "Name" => "Stop A", "LatLong" => [ "Latitude" => 37.7897, "Longitude" => -122.4011 ], "LocationType" => 0 ],
    [ "Name" => "Stop B", "LatLong" => [ "Latitude" => 37.7810, "Longitude" => -122.4110 ], "LocationType" => 0 ]
  ]
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: YOUR_TRACKSERVICEKEY"
  ],
  CURLOPT_POSTFIELDS => $payload
]);

echo curl_exec($ch);
curl_close($ch);

require "net/http"
require "json"

uri = URI("https://trackservice.trackroad.com/rest/dispatch")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

payload = {
  RoutingService: 0,
  DistanceUnit: 0,
  RouteOptimize: 0,
  DispatchMode: 0,
  Vehicles: [
    {
      Name: "Truck 1",
      StartLocation: { LatLong: { Latitude: 37.7946, Longitude: -122.3950 }, LocationType: 1 },
      FinishLocation: { LatLong: { Latitude: 37.7946, Longitude: -122.3950 }, LocationType: 2 }
    }
  ],
  Locations: [
    { Name: "Stop A", LatLong: { Latitude: 37.7897, Longitude: -122.4011 }, LocationType: 0 },
    { Name: "Stop B", LatLong: { Latitude: 37.7810, Longitude: -122.4110 }, LocationType: 0 }
  ]
}

req = Net::HTTP::Post.new(uri)
req["Content-Type"] = "application/json"
req["X-API-Key"] = "YOUR_TRACKSERVICEKEY"
req.body = payload.to_json

res = http.request(req)
puts res.body

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  url := "https://trackservice.trackroad.com/rest/dispatch"
  jsonBody := []byte(`{
    "RoutingService": 0,
    "DistanceUnit": 0,
    "RouteOptimize": 0,
    "DispatchMode": 0,
    "Vehicles": [
      {
        "Name": "Truck 1",
        "StartLocation": { "LatLong": { "Latitude": 37.7946, "Longitude": -122.3950 }, "LocationType": 1 },
        "FinishLocation": { "LatLong": { "Latitude": 37.7946, "Longitude": -122.3950 }, "LocationType": 2 }
      }
    ],
    "Locations": [
      { "Name": "Stop A", "LatLong": { "Latitude": 37.7897, "Longitude": -122.4011 }, "LocationType": 0 },
      { "Name": "Stop B", "LatLong": { "Latitude": 37.7810, "Longitude": -122.4110 }, "LocationType": 0 }
    ]
  }`)

  req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonBody))
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("X-API-Key", "YOUR_TRACKSERVICEKEY")

  resp, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer resp.Body.Close()

  b, _ := io.ReadAll(resp.Body)
  fmt.Println(string(b))
}

import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse

fun main() {
  val url = "https://trackservice.trackroad.com/rest/dispatch"
  val json = """
    {
      "RoutingService": 0,
      "DistanceUnit": 0,
      "RouteOptimize": 0,
      "DispatchMode": 0,
      "Vehicles": [
        {
          "Name": "Truck 1",
          "StartLocation": { "LatLong": { "Latitude": 37.7946, "Longitude": -122.3950 }, "LocationType": 1 },
          "FinishLocation": { "LatLong": { "Latitude": 37.7946, "Longitude": -122.3950 }, "LocationType": 2 }
        }
      ],
      "Locations": [
        { "Name": "Stop A", "LatLong": { "Latitude": 37.7897, "Longitude": -122.4011 }, "LocationType": 0 },
        { "Name": "Stop B", "LatLong": { "Latitude": 37.7810, "Longitude": -122.4110 }, "LocationType": 0 }
      ]
    }
  """.trimIndent()

  val client = HttpClient.newHttpClient()
  val req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Content-Type", "application/json")
    .header("X-API-Key", "YOUR_TRACKSERVICEKEY")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build()

  val resp = client.send(req, HttpResponse.BodyHandlers.ofString())
  println(resp.body())
}

#include <stdio.h>
#include <curl/curl.h>

int main(void) {
  CURL *curl = curl_easy_init();
  if(!curl) return 1;

  const char *url = "https://trackservice.trackroad.com/rest/dispatch";
  const char *json =
    "{"
    "\"RoutingService\":0,"
    "\"DistanceUnit\":0,"
    "\"RouteOptimize\":0,"
    "\"DispatchMode\":0,"
    "\"Vehicles\":[{"
      "\"Name\":\"Truck 1\","
      "\"StartLocation\":{\"LatLong\":{\"Latitude\":37.7946,\"Longitude\":-122.3950},\"LocationType\":1},"
      "\"FinishLocation\":{\"LatLong\":{\"Latitude\":37.7946,\"Longitude\":-122.3950},\"LocationType\":2}"
    "}],"
    "\"Locations\":[{"
      "\"Name\":\"Stop A\","
      "\"LatLong\":{\"Latitude\":37.7897,\"Longitude\":-122.4011},"
      "\"LocationType\":0"
    "},{"
      "\"Name\":\"Stop B\","
      "\"LatLong\":{\"Latitude\":37.7810,\"Longitude\":-122.4110},"
      "\"LocationType\":0"
    "}]"
    "}";

  struct curl_slist *headers = NULL;
  headers = curl_slist_append(headers, "Content-Type: application/json");
  headers = curl_slist_append(headers, "X-API-Key: YOUR_TRACKSERVICEKEY");

  curl_easy_setopt(curl, CURLOPT_URL, url);
  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json);

  CURLcode res = curl_easy_perform(curl);

  curl_slist_free_all(headers);
  curl_easy_cleanup(curl);

  return (res == CURLE_OK) ? 0 : 1;
}

#include <curl/curl.h>
#include <string>

int main() {
  CURL* curl = curl_easy_init();
  if(!curl) return 1;

  std::string url = "https://trackservice.trackroad.com/rest/dispatch";
  std::string json =
    "{"
    "\"RoutingService\":0,"
    "\"DistanceUnit\":0,"
    "\"RouteOptimize\":0,"
    "\"DispatchMode\":0,"
    "\"Vehicles\":[{"
      "\"Name\":\"Truck 1\","
      "\"StartLocation\":{\"LatLong\":{\"Latitude\":37.7946,\"Longitude\":-122.3950},\"LocationType\":1},"
      "\"FinishLocation\":{\"LatLong\":{\"Latitude\":37.7946,\"Longitude\":-122.3950},\"LocationType\":2}"
    "}],"
    "\"Locations\":[{"
      "\"Name\":\"Stop A\","
      "\"LatLong\":{\"Latitude\":37.7897,\"Longitude\":-122.4011},"
      "\"LocationType\":0"
    "},{"
      "\"Name\":\"Stop B\","
      "\"LatLong\":{\"Latitude\":37.7810,\"Longitude\":-122.4110},"
      "\"LocationType\":0"
    "}]"
    "}";

  struct curl_slist* headers = NULL;
  headers = curl_slist_append(headers, "Content-Type: application/json");
  headers = curl_slist_append(headers, "X-API-Key: YOUR_TRACKSERVICEKEY");

  curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json.c_str());

  CURLcode res = curl_easy_perform(curl);

  curl_slist_free_all(headers);
  curl_easy_cleanup(curl);

  return (res == CURLE_OK) ? 0 : 1;
}

#import <Foundation/Foundation.h>

int main() {
  @autoreleasepool {
    NSURL *url = [NSURL URLWithString:@"https://trackservice.trackroad.com/rest/dispatch"];
    NSMutableURLRequest *req = [NSMutableURLRequest requestWithURL:url];
    [req setHTTPMethod:@"POST"];
    [req setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
    [req setValue:@"YOUR_TRACKSERVICEKEY" forHTTPHeaderField:@"X-API-Key"];

    NSDictionary *payload = @{
      @"RoutingService": @0,
      @"DistanceUnit": @0,
      @"RouteOptimize": @0,
      @"DispatchMode": @0,
      @"Vehicles": @[
        @{
          @"Name": @"Truck 1",
          @"StartLocation": @{@"LatLong": @{@"Latitude": @37.7946, @"Longitude": @-122.3950}, @"LocationType": @1},
          @"FinishLocation": @{@"LatLong": @{@"Latitude": @37.7946, @"Longitude": @-122.3950}, @"LocationType": @2}
        }
      ],
      @"Locations": @[
        @{@"Name": @"Stop A", @"LatLong": @{@"Latitude": @37.7897, @"Longitude": @-122.4011}, @"LocationType": @0},
        @{@"Name": @"Stop B", @"LatLong": @{@"Latitude": @37.7810, @"Longitude": @-122.4110}, @"LocationType": @0}
      ]
    };

    NSData *body = [NSJSONSerialization dataWithJSONObject:payload options:0 error:nil];
    [req setHTTPBody:body];

    NSURLSessionDataTask *task =
      [[NSURLSession sharedSession] dataTaskWithRequest:req
      completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
        if (error) { NSLog(@"%@", error); return; }
        NSString *text = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
        NSLog(@"%@", text);
      }];

    [task resume];
    [[NSRunLoop currentRunLoop] run];
  }
  return 0;
}

import Foundation

let url = URL(string: "https://trackservice.trackroad.com/rest/dispatch")!
var req = URLRequest(url: url)
req.httpMethod = "POST"
req.setValue("application/json", forHTTPHeaderField: "Content-Type")
req.setValue("YOUR_TRACKSERVICEKEY", forHTTPHeaderField: "X-API-Key")

let payload: [String: Any] = [
  "RoutingService": 0,
  "DistanceUnit": 0,
  "RouteOptimize": 0,
  "DispatchMode": 0,
  "Vehicles": [
    [
      "Name": "Truck 1",
      "StartLocation": ["LatLong": ["Latitude": 37.7946, "Longitude": -122.3950], "LocationType": 1],
      "FinishLocation": ["LatLong": ["Latitude": 37.7946, "Longitude": -122.3950], "LocationType": 2]
    ]
  ],
  "Locations": [
    ["Name": "Stop A", "LatLong": ["Latitude": 37.7897, "Longitude": -122.4011], "LocationType": 0],
    ["Name": "Stop B", "LatLong": ["Latitude": 37.7810, "Longitude": -122.4110], "LocationType": 0]
  ]
]

req.httpBody = try! JSONSerialization.data(withJSONObject: payload)

let task = URLSession.shared.dataTask(with: req) { data, _, error in
  if let error = error { print(error); return }
  print(String(data: data ?? Data(), encoding: .utf8) ?? "")
}
task.resume()
RunLoop.main.run()

SOAP request examples (multiple languages)#

SOAP uses the same DispatchSpecification model, but it’s wrapped in a SOAP envelope and authenticated via SessionIDHeader (SessionID = TrackServiceKey).

curl -X POST "https://trackservice.trackroad.com/TrackService.asmx" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H "SOAPAction: http://trackservice.trackroad.com/Dispatch" \
  -d @dispatch-soap.xml

/*
  Recommended: use a WSDL-generated client for SOAP.

  1) Add Service Reference to:
     https://trackservice.trackroad.com/TrackService.asmx?WSDL

  2) Set SessionIDHeader.SessionID = YOUR_TRACKSERVICEKEY
     then call Dispatch(spec).
*/

var client = new TrackService.TrackServiceSoapClient();
var header = new TrackService.SessionIDHeader { SessionID = "YOUR_TRACKSERVICEKEY" };

var spec = new TrackService.DispatchSpecification
{
    RoutingService = TrackService.RoutingService.NetRoad,
    DistanceUnit = TrackService.DistanceUnit.Mile,
    RouteOptimize = TrackService.RouteOptimize.MinimizeTime,
    DispatchMode = TrackService.DispatchMode.Auto,
    Vehicles = new TrackService.Vehicle[]
    {
        new TrackService.Vehicle
        {
            Name = "Truck 1",
            StartLocation = new TrackService.Location
            {
                LatLong = new TrackService.LatLong { Latitude = 37.7946, Longitude = -122.3950 },
                LocationType = TrackService.LocationType.Start
            },
            FinishLocation = new TrackService.Location
            {
                LatLong = new TrackService.LatLong { Latitude = 37.7946, Longitude = -122.3950 },
                LocationType = TrackService.LocationType.Finish
            }
        }
    },
    Locations = new TrackService.Location[]
    {
        new TrackService.Location
        {
            Name = "Stop A",
            LatLong = new TrackService.LatLong { Latitude = 37.7897, Longitude = -122.4011 },
            LocationType = TrackService.LocationType.Midway
        },
        new TrackService.Location
        {
            Name = "Stop B",
            LatLong = new TrackService.LatLong { Latitude = 37.7810, Longitude = -122.4110 },
            LocationType = TrackService.LocationType.Midway
        }
    }
};

var result = client.Dispatch(header, spec);

// SOAP in browser JS is uncommon; use Node.js + fetch (undici) or axios.
// This example uses fetch in Node 18+.

const endpoint = "https://trackservice.trackroad.com/TrackService.asmx";

const xml = `<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <SessionIDHeader xmlns="http://trackservice.trackroad.com/">
      <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
    </SessionIDHeader>
  </soap:Header>
  <soap:Body>
    <Dispatch xmlns="http://trackservice.trackroad.com/">
      <specification>
        <RoutingService>0</RoutingService>
        <DistanceUnit>0</DistanceUnit>
        <RouteOptimize>0</RouteOptimize>
        <DispatchMode>0</DispatchMode>
        <Vehicles>
          <Vehicle>
            <Name>Truck 1</Name>
            <StartLocation>
              <LatLong><Latitude>37.7946</Latitude><Longitude>-122.3950</Longitude></LatLong>
              <LocationType>1</LocationType>
            </StartLocation>
            <FinishLocation>
              <LatLong><Latitude>37.7946</Latitude><Longitude>-122.3950</Longitude></LatLong>
              <LocationType>2</LocationType>
            </FinishLocation>
          </Vehicle>
        </Vehicles>
        <Locations>
          <Location>
            <Name>Stop A</Name>
            <LatLong><Latitude>37.7897</Latitude><Longitude>-122.4011</Longitude></LatLong>
            <LocationType>0</LocationType>
          </Location>
          <Location>
            <Name>Stop B</Name>
            <LatLong><Latitude>37.7810</Latitude><Longitude>-122.4110</Longitude></LatLong>
            <LocationType>0</LocationType>
          </Location>
        </Locations>
      </specification>
    </Dispatch>
  </soap:Body>
</soap:Envelope>`;

const res = await fetch(endpoint, {
  method: "POST",
  headers: {
    "Content-Type": "text/xml; charset=utf-8",
    "SOAPAction": "http://trackservice.trackroad.com/Dispatch"
  },
  body: xml
});

console.log(await res.text());

// Option A (recommended): use a SOAP client generated from WSDL (JAX-WS).
// Option B: post raw XML (shown here) using OkHttp.

import okhttp3.*;

public class Main {
  public static void main(String[] args) throws Exception {
    OkHttpClient client = new OkHttpClient();

    String xml =
      "<?xml version=\"1.0\" encoding=\"utf-8\"?>"
    + "<soap:Envelope xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\""
    + " xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\""
    + " xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\">"
    + "  <soap:Header>"
    + "    <SessionIDHeader xmlns=\"http://trackservice.trackroad.com/\">"
    + "      <SessionID>YOUR_TRACKSERVICEKEY</SessionID>"
    + "    </SessionIDHeader>"
    + "  </soap:Header>"
    + "  <soap:Body>"
    + "    <Dispatch xmlns=\"http://trackservice.trackroad.com/\">"
    + "      <specification>"
    + "        <RoutingService>0</RoutingService>"
    + "        <DistanceUnit>0</DistanceUnit>"
    + "        <RouteOptimize>0</RouteOptimize>"
    + "        <DispatchMode>0</DispatchMode>"
    + "        <Vehicles />"
    + "        <Locations />"
    + "      </specification>"
    + "    </Dispatch>"
    + "  </soap:Body>"
    + "</soap:Envelope>";

    RequestBody body = RequestBody.create(xml, MediaType.parse("text/xml; charset=utf-8"));

    Request request = new Request.Builder()
      .url("https://trackservice.trackroad.com/TrackService.asmx")
      .post(body)
      .addHeader("Content-Type", "text/xml; charset=utf-8")
      .addHeader("SOAPAction", "http://trackservice.trackroad.com/Dispatch")
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

import requests

endpoint = "https://trackservice.trackroad.com/TrackService.asmx"

xml = """<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <SessionIDHeader xmlns="http://trackservice.trackroad.com/">
      <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
    </SessionIDHeader>
  </soap:Header>
  <soap:Body>
    <Dispatch xmlns="http://trackservice.trackroad.com/">
      <specification>
        <RoutingService>0</RoutingService>
        <DistanceUnit>0</DistanceUnit>
        <RouteOptimize>0</RouteOptimize>
        <DispatchMode>0</DispatchMode>
        <Vehicles />
        <Locations />
      </specification>
    </Dispatch>
  </soap:Body>
</soap:Envelope>
"""

headers = {
  "Content-Type": "text/xml; charset=utf-8",
  "SOAPAction": "http://trackservice.trackroad.com/Dispatch"
}

r = requests.post(endpoint, headers=headers, data=xml.encode("utf-8"))
print(r.text)

<?php
$endpoint = "https://trackservice.trackroad.com/TrackService.asmx";

$xml = <<<XML
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <SessionIDHeader xmlns="http://trackservice.trackroad.com/">
      <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
    </SessionIDHeader>
  </soap:Header>
  <soap:Body>
    <Dispatch xmlns="http://trackservice.trackroad.com/">
      <specification>
        <RoutingService>0</RoutingService>
        <DistanceUnit>0</DistanceUnit>
        <RouteOptimize>0</RouteOptimize>
        <DispatchMode>0</DispatchMode>
        <Vehicles />
        <Locations />
      </specification>
    </Dispatch>
  </soap:Body>
</soap:Envelope>
XML;

$ch = curl_init($endpoint);
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: text/xml; charset=utf-8",
    "SOAPAction: http://trackservice.trackroad.com/Dispatch"
  ],
  CURLOPT_POSTFIELDS => $xml
]);

echo curl_exec($ch);
curl_close($ch);

require "net/http"

endpoint = URI("https://trackservice.trackroad.com/TrackService.asmx")

xml = <<~XML
  <?xml version="1.0" encoding="utf-8"?>
  <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Header>
      <SessionIDHeader xmlns="http://trackservice.trackroad.com/">
        <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
      </SessionIDHeader>
    </soap:Header>
    <soap:Body>
      <Dispatch xmlns="http://trackservice.trackroad.com/">
        <specification>
          <RoutingService>0</RoutingService>
          <DistanceUnit>0</DistanceUnit>
          <RouteOptimize>0</RouteOptimize>
          <DispatchMode>0</DispatchMode>
          <Vehicles />
          <Locations />
        </specification>
      </Dispatch>
    </soap:Body>
  </soap:Envelope>
XML

http = Net::HTTP.new(endpoint.host, endpoint.port)
http.use_ssl = true

req = Net::HTTP::Post.new(endpoint)
req["Content-Type"] = "text/xml; charset=utf-8"
req["SOAPAction"] = "http://trackservice.trackroad.com/Dispatch"
req.body = xml

res = http.request(req)
puts res.body

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  endpoint := "https://trackservice.trackroad.com/TrackService.asmx"

  xml := []byte(`<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <SessionIDHeader xmlns="http://trackservice.trackroad.com/">
      <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
    </SessionIDHeader>
  </soap:Header>
  <soap:Body>
    <Dispatch xmlns="http://trackservice.trackroad.com/">
      <specification>
        <RoutingService>0</RoutingService>
        <DistanceUnit>0</DistanceUnit>
        <RouteOptimize>0</RouteOptimize>
        <DispatchMode>0</DispatchMode>
        <Vehicles />
        <Locations />
      </specification>
    </Dispatch>
  </soap:Body>
</soap:Envelope>`)

  req, _ := http.NewRequest("POST", endpoint, bytes.NewBuffer(xml))
  req.Header.Set("Content-Type", "text/xml; charset=utf-8")
  req.Header.Set("SOAPAction", "http://trackservice.trackroad.com/Dispatch")

  resp, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer resp.Body.Close()

  b, _ := io.ReadAll(resp.Body)
  fmt.Println(string(b))
}

import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse

fun main() {
  val endpoint = "https://trackservice.trackroad.com/TrackService.asmx"
  val xml = """
    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <soap:Header>
        <SessionIDHeader xmlns="http://trackservice.trackroad.com/">
          <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
        </SessionIDHeader>
      </soap:Header>
      <soap:Body>
        <Dispatch xmlns="http://trackservice.trackroad.com/">
          <specification>
            <RoutingService>0</RoutingService>
            <DistanceUnit>0</DistanceUnit>
            <RouteOptimize>0</RouteOptimize>
            <DispatchMode>0</DispatchMode>
            <Vehicles />
            <Locations />
          </specification>
        </Dispatch>
      </soap:Body>
    </soap:Envelope>
  """.trimIndent()

  val client = HttpClient.newHttpClient()
  val req = HttpRequest.newBuilder()
    .uri(URI.create(endpoint))
    .header("Content-Type", "text/xml; charset=utf-8")
    .header("SOAPAction", "http://trackservice.trackroad.com/Dispatch")
    .POST(HttpRequest.BodyPublishers.ofString(xml))
    .build()

  val resp = client.send(req, HttpResponse.BodyHandlers.ofString())
  println(resp.body())
}

#include <curl/curl.h>

int main(void) {
  CURL *curl = curl_easy_init();
  if(!curl) return 1;

  const char *endpoint = "https://trackservice.trackroad.com/TrackService.asmx";
  const char *xml =
    "<?xml version=\"1.0\" encoding=\"utf-8\"?>"
    "<soap:Envelope xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\""
    " xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\""
    " xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\">"
    "  <soap:Header>"
    "    <SessionIDHeader xmlns=\"http://trackservice.trackroad.com/\">"
    "      <SessionID>YOUR_TRACKSERVICEKEY</SessionID>"
    "    </SessionIDHeader>"
    "  </soap:Header>"
    "  <soap:Body>"
    "    <Dispatch xmlns=\"http://trackservice.trackroad.com/\">"
    "      <specification>"
    "        <RoutingService>0</RoutingService>"
    "        <DistanceUnit>0</DistanceUnit>"
    "        <RouteOptimize>0</RouteOptimize>"
    "        <DispatchMode>0</DispatchMode>"
    "        <Vehicles />"
    "        <Locations />"
    "      </specification>"
    "    </Dispatch>"
    "  </soap:Body>"
    "</soap:Envelope>";

  struct curl_slist *headers = NULL;
  headers = curl_slist_append(headers, "Content-Type: text/xml; charset=utf-8");
  headers = curl_slist_append(headers, "SOAPAction: http://trackservice.trackroad.com/Dispatch");

  curl_easy_setopt(curl, CURLOPT_URL, endpoint);
  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  curl_easy_setopt(curl, CURLOPT_POSTFIELDS, xml);

  CURLcode res = curl_easy_perform(curl);

  curl_slist_free_all(headers);
  curl_easy_cleanup(curl);

  return (res == CURLE_OK) ? 0 : 1;
}

#include <curl/curl.h>
#include <string>

int main() {
  CURL* curl = curl_easy_init();
  if(!curl) return 1;

  std::string endpoint = "https://trackservice.trackroad.com/TrackService.asmx";
  std::string xml =
    "<?xml version=\"1.0\" encoding=\"utf-8\"?>"
    "<soap:Envelope xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\""
    " xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\""
    " xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\">"
    "  <soap:Header>"
    "    <SessionIDHeader xmlns=\"http://trackservice.trackroad.com/\">"
    "      <SessionID>YOUR_TRACKSERVICEKEY</SessionID>"
    "    </SessionIDHeader>"
    "  </soap:Header>"
    "  <soap:Body>"
    "    <Dispatch xmlns=\"http://trackservice.trackroad.com/\">"
    "      <specification>"
    "        <RoutingService>0</RoutingService>"
    "        <DistanceUnit>0</DistanceUnit>"
    "        <RouteOptimize>0</RouteOptimize>"
    "        <DispatchMode>0</DispatchMode>"
    "        <Vehicles />"
    "        <Locations />"
    "      </specification>"
    "    </Dispatch>"
    "  </soap:Body>"
    "</soap:Envelope>";

  struct curl_slist* headers = NULL;
  headers = curl_slist_append(headers, "Content-Type: text/xml; charset=utf-8");
  headers = curl_slist_append(headers, "SOAPAction: http://trackservice.trackroad.com/Dispatch");

  curl_easy_setopt(curl, CURLOPT_URL, endpoint.c_str());
  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  curl_easy_setopt(curl, CURLOPT_POSTFIELDS, xml.c_str());

  CURLcode res = curl_easy_perform(curl);

  curl_slist_free_all(headers);
  curl_easy_cleanup(curl);

  return (res == CURLE_OK) ? 0 : 1;
}

#import <Foundation/Foundation.h>

int main() {
  @autoreleasepool {
    NSURL *url = [NSURL URLWithString:@"https://trackservice.trackroad.com/TrackService.asmx"];
    NSMutableURLRequest *req = [NSMutableURLRequest requestWithURL:url];
    [req setHTTPMethod:@"POST"];
    [req setValue:@"text/xml; charset=utf-8" forHTTPHeaderField:@"Content-Type"];
    [req setValue:@"http://trackservice.trackroad.com/Dispatch" forHTTPHeaderField:@"SOAPAction"];

    NSString *xml =
    @"<?xml version=\"1.0\" encoding=\"utf-8\"?>"
     "<soap:Envelope xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\""
     " xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\""
     " xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\">"
     "  <soap:Header>"
     "    <SessionIDHeader xmlns=\"http://trackservice.trackroad.com/\">"
     "      <SessionID>YOUR_TRACKSERVICEKEY</SessionID>"
     "    </SessionIDHeader>"
     "  </soap:Header>"
     "  <soap:Body>"
     "    <Dispatch xmlns=\"http://trackservice.trackroad.com/\">"
     "      <specification>"
     "        <RoutingService>0</RoutingService>"
     "        <DistanceUnit>0</DistanceUnit>"
     "        <RouteOptimize>0</RouteOptimize>"
     "        <DispatchMode>0</DispatchMode>"
     "        <Vehicles />"
     "        <Locations />"
     "      </specification>"
     "    </Dispatch>"
     "  </soap:Body>"
     "</soap:Envelope>";

    NSData *body = [xml dataUsingEncoding:NSUTF8StringEncoding];
    [req setHTTPBody:body];

    NSURLSessionDataTask *task =
      [[NSURLSession sharedSession] dataTaskWithRequest:req
      completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
        if (error) { NSLog(@"%@", error); return; }
        NSString *text = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
        NSLog(@"%@", text);
      }];

    [task resume];
    [[NSRunLoop currentRunLoop] run];
  }
  return 0;
}

import Foundation

let url = URL(string: "https://trackservice.trackroad.com/TrackService.asmx")!
var req = URLRequest(url: url)
req.httpMethod = "POST"
req.setValue("text/xml; charset=utf-8", forHTTPHeaderField: "Content-Type")
req.setValue("http://trackservice.trackroad.com/Dispatch", forHTTPHeaderField: "SOAPAction")

let xml = """
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <SessionIDHeader xmlns="http://trackservice.trackroad.com/">
      <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
    </SessionIDHeader>
  </soap:Header>
  <soap:Body>
    <Dispatch xmlns="http://trackservice.trackroad.com/">
      <specification>
        <RoutingService>0</RoutingService>
        <DistanceUnit>0</DistanceUnit>
        <RouteOptimize>0</RouteOptimize>
        <DispatchMode>0</DispatchMode>
        <Vehicles />
        <Locations />
      </specification>
    </Dispatch>
  </soap:Body>
</soap:Envelope>
"""

req.httpBody = xml.data(using: .utf8)

let task = URLSession.shared.dataTask(with: req) { data, _, error in
  if let error = error { print(error); return }
  print(String(data: data ?? Data(), encoding: .utf8) ?? "")
}
task.resume()
RunLoop.main.run()

SOAP: Raw request (Envelope + SessionIDHeader)#

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <SessionIDHeader xmlns="http://trackservice.trackroad.com/">
      <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
    </SessionIDHeader>
  </soap:Header>
  <soap:Body>
    <Dispatch xmlns="http://trackservice.trackroad.com/">
      <specification>
        <RoutingService>0</RoutingService>
        <DistanceUnit>0</DistanceUnit>
        <RouteOptimize>0</RouteOptimize>
        <DispatchMode>0</DispatchMode>
        <Vehicles></Vehicles>
        <Locations></Locations>
      </specification>
    </Dispatch>
  </soap:Body>
</soap:Envelope>

JSON: Response example#

{
  "Items": [
    {
      "Vehicle": { "Name": "Truck 1" },
      "Locations": [
        { "Name": "Stop A", "LatLong": { "Latitude": 37.7897, "Longitude": -122.4011 } },
        { "Name": "Stop B", "LatLong": { "Latitude": 37.7810, "Longitude": -122.4110 } }
      ]
    }
  ],
  "Errors": [],
  "Status": 1
}

SOAP: Response example#

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <DispatchResponse xmlns="http://trackservice.trackroad.com/">
      <DispatchResult>
        <Status>1</Status>
        <Errors />

        <Items>
          <VehicleItem>
            <Vehicle>
              <Name>Truck 1</Name>
            </Vehicle>

            <Locations>
              <Location>
                <Name>Stop A</Name>
                <LocationType>0</LocationType>
                <LatLong>
                  <Latitude>37.7897</Latitude>
                  <Longitude>-122.4011</Longitude>
                </LatLong>
              </Location>

              <Location>
                <Name>Stop B</Name>
                <LocationType>0</LocationType>
                <LatLong>
                  <Latitude>37.7810</Latitude>
                  <Longitude>-122.4110</Longitude>
                </LatLong>
              </Location>
            </Locations>
          </VehicleItem>
        </Items>

      </DispatchResult>
    </DispatchResponse>
  </soap:Body>
</soap:Envelope>

Errori comuni#

REST 401 / Unauthorized: X-API-Key mancante o non valido.
REST 403 / Forbidden: la chiave è valida ma bloccata, scaduta o senza credito.
Errori di validazione: uno stop non contiene né LatLong né Address, oppure le coordinate non sono valide.
Errori di autenticazione SOAP: SessionIDHeader mancante o non valido, oppure SessionID vuoto.

Best practice

Preferisci LatLong per evitare ambiguità di geocodifica e migliorare la coerenza del routing.
Usa StartLocation e FinishLocation per il routing basato su deposito e per ETA più accurati.
Aggiungi vincoli di capacità come peso, volume e skid per assegnazioni di percorso più realistiche.
Usa finestre temporali quando gli stop devono essere visitati entro orari del cliente o operativi.
Per SOAP, usa TrackServiceKey in SessionIDHeader. Il flusso di login legacy non è richiesto.

FAQ#

Cosa fa l'API Dispatch?

Dispatch ottimizza gli stop su più veicoli e restituisce percorsi ordinati per veicolo con tempi e distanze.

Come si autentica Dispatch in REST e SOAP?

REST usa il tuo TrackServiceKey nell'header X-API-Key. SOAP usa lo stesso TrackServiceKey in SessionIDHeader come SessionID.

Per gli stop servono LatLong o Address?

LatLong è preferibile. Se LatLong non è fornito, Address è obbligatorio affinché TrackRoad possa geocodificare lo stop.

Pronto a ottimizzare i percorsi?

Genera la tua chiave API e inizia a integrare Dispatch per l'ottimizzazione multiveicolo dei percorsi con REST o SOAP.

Ottieni API Key SOAP WSDL Swagger UI