What does the Dispatch API do?

Dispatch optimizes stops across multiple vehicles and returns per-vehicle ordered routes with timing and distance outputs.

How do I authenticate to Dispatch (REST and SOAP)?

REST: send TrackServiceKey in the X-API-Key request header. SOAP: send TrackServiceKey in SessionIDHeader as SessionID.

Do I need LatLong or Address for stops?

Provide LatLong when possible (preferred). If LatLong is omitted, Address is required so the service can geocode the stop.

Dispatch API (Route Optimization)

Use Dispatch to optimize routes across multiple vehicles and many stops. The result returns an ordered list of stops per vehicle along with computed distances and times.

Dispatch assigns stops across multiple vehicles and returns optimized routes (stop order, ETA, distance, and duration) for each vehicle.

Need the full contract?

REST models are available in Swagger. SOAP is available via the WSDL.

View Swagger UI View SOAP WSDL API Reference Overview

What Dispatch does
Endpoints and base URLs
Authentication (REST & SOAP)
Request schema
Response schema
Examples (REST & SOAP)
Common errors
Best practices
Related endpoints

What Dispatch does#

Dispatch solves a multi-vehicle routing problem: it assigns stops to vehicles and orders each vehicle’s route. You can provide constraints such as time windows, per-stop wait time, priority, vehicle capacity limits (weight/volume/skids), and start/finish depot locations.

LatLong is preferred. Each stop should include LatLong whenever possible. If LatLong is not provided, you must provide Address so the service can geocode the stop.

Dispatch method accepts two parameters. The first is a list of vehicles objects. The vehicle object has Start lat/lon and lat/lon for an optional Finish location. The second parameter to the web service is a list of stop locations that must be visited by the vehicles. The location object can contain name, street, city, state, zip, country and lat/lon fields. TrackService will geocode locations addresses on-the-fly. In the event lat/lon are present, they will be used for the location and no geocoding will be performed, otherwise geocoding is carried out to find lat/lon for the given location.

Dispatch returns a list of vehicle items. Each vehicle has a list of stops that contains the route assigned to the vehicle. The list is optimized based on stop location, weight, time and other factors. The return list may also contain start/finish locations of the vehicle.

Suppose we call Dispatch() method with one vehicle V1 and six stops B, A, C, F, E, D.
Dispatch() result will be:
V1---->A--->B---->C---->D---->F---->E (order is optimized route)

Suppose we call Dispatch() method with two vehicles V1 and V2 and six stops B, A, C, F, E, D.
Depending on factors such as geographic dispersed, time, weight, etc. Dispatch() can assign A, E to V1 and B, C, D, F to V2 vehicle.
V1---->A---->E (order is optimized route)
V2---->B---->D---->C---->F (order is optimized route)

You can use the location TimeConstraintArrival property only if you have time-sensentive deliveries.

Except for the TimeWindow mode, Dispatching mode only applies when there are mutiple vehicles. When there is one vehicle available then only route optimization is performed since there is nothing to dispatch (all stops are assigned to a single vehicle). Leave on 'Auto' for system if you are not sure and to select the best match.

Optima mode, Time Window & TimeWindowDepot#

In some languages it may not be possible to pass datetime as null, in that case please set datetime to "0001-01-01T00:00:00". Our system will treat any date less than (or equal to) Jan012012 as a null date.

For best result use DispatchMode Optima.

There are three variables that can affect time window dispatching mode:

CanArriveEarly
TimeConstraintArrival
TimeConstraintDeparture

Depending on how these variables are used we can set different time windows:

Option 1: CanArriveEarly == true

Window start time is always start of the day which is 12am. When CanArriveEarly is true, two things can affect closing time.
If TimeConstraintArrival is null then time window is from 12AM---11:59pm
if TimeConstraintArrival is valid time like 4pm then time window is from 12AM--4pm
When CanArriveEarly is true, departure time is ignored.

Option 2: CanArriveEarly == false

When CanArrive is false then start/end times are solely determined by TimeConstraintArrival and TimeConstraintDeparture. In this case, there can also be different scenarios. If both variables are null (Jan012012) then entire day is available (12am --- 11:59pm) and stop is treated like it has no time window.
If arrival time is not null but departure is null then departure time will be same as arrival time. So if you need to be at a location at precisely 10AM then set TimeConstraintArrival to 10AM and set TimeConstraintDeparture to either 10AM or null. Either way, system will try to arrive at the location at 10AM and no later than 10AM.
In case if you need to create a time window then set arrival time to a valid time and departure time to a valid time that is later than arrival time. For example, if you need a time window of 10am to 5pm then set TimeConstraintArrival to 10am and TimeConstraintDeparture to 5pm. System will try to reach the stop somewhere between 10am and 5pm.

Option 3: Two Time Windows

TimeConstraintArrival2
TimeConstraintDeparture2
There is also a possiblity of using two time windows. Suppose due to traffic restrictions in downtown Brussels, a delivery truck can only visit between the hours of 4am-7am OR 9pm-11pm. This would consitute two time windows:
TimeContraintArrival = 4am
TimeContraintDeparture = 7am
TimeContraintArrival2 = 9pm
TimeContraintDeparture2 = 11pm
Note that there will still be only one visit per route. However, TrackRoad will try to select best possible window; either between 4am and 7am or 9pm and 11pm.
TimeWindowDepot mode follows exact same logic as TimeWindow. TimeWindowDepot uses first vehicle information to assume all vehicles start from a central(depot) location. In this case there are no geographically dispersed vehicles and it is assumed all vehicles start/finish are at same location.

It is possible to block off a time window for breaks, park or rest. Use LocationType Break to block off a time window.
The multiple pickup and delivery (chaining) while using the <delivery> tag only supports one time window of TimeConstraintArrival and TimeConstraintDeparture. Also, the <delivery> timeconstraint cannot be less than the parent constraint. S ee Multiple Pickups and Deliveries for more information.

Multiple Pickups and Deliveries#

In addition to visiting stops, it is sometimes necessary to pickup at one or more locations before delivering to another location(s). For example, in most courier operation, it is required that the courier pick up a package at locaion A, then deliver it to location B. This kind of situation is well supported with TrackRoad.com web services. In fact, it is possible to daisy-chain up to 1,000 pickups and delivery locations together to form a consistent set of deliveries that follow each other.

Use the tag <Midway> for first stop in the chain. Thereafter, all children should use <Delivery> to specify a delivery point for the pickup location. Each location can also have a DeliveryNonStop property. Tag <DeliveryNonStop> (boolean) can be used to specify whether the delivery to next location should be non-stop or can be with stops in-between.

For example, suppose we have locations A, B, C, D we need to visit in optimized order. However, at location B, we must pickup a parcel and deliver it to location M. In the API, we will create 5 locations (note the order of specification is not important but we must put all delivery locations (M) after pickups). For simplicity, we eliminated location lat/lon and other tags in the following sample:
<Name> <A>
<Name><B>
<Delivery><M>
<DeliveryNonStop><true>
<Name><C>
<Name><D>
<Name><M>

Note that at location B, we specify the name of delivery location M. Addtionally, we shall make M to be a non-stop delivery (visit M immediately after B). Upon building the route, the following routes are a few possiblities (for now, we disregard shortest route and show all possible routes):

DeliveryNonStop = true

C--->B--->M---->D---->A
A--->B--->M---->D---->C
A--->B--->M---->C---->D
A--->C--->B--->M----->D
D--->B--->M----->C-->A
C--->A---->D---->B--->M

In the above routing example, if KeepSameOrder tag is used then M is always guaranteed to come after B. Additionally, since DeliveryNonStop is true, M is visited IMMEDIATELY after B.

DeliveryNonStop = false

In another example, let's assume DeliveryNonStop is false. Possible routes are:
C--->B--->D---->M---->A
A--->B--->C---->D---->M
A--->B--->M---->C---->D
A--->C--->B--->D----->M
D--->B--->D---->A---->M
C--->A---->D---->B--->M
Note that M is still visited after B. However, it can be anywhere after B.

As mentioned before, you may daisy-chain multiple deliveries using the tag <delivery> to specify one delivery to the next. For example, in the following, location M too has a delivery location. Thus somewhere in our route, we will be visiting B--->M---->N in that order before continuing to visit other locations. You can continue the delivery chain several times while individually setting DeliveryNonStop to either true or false .

Here's round trip example where we pick up a parcel from origin, take it to destination then return back to origin. For best result, set DeliveryNonStop to false and KeepSameOrder to true:
<Name> <P> // pickup location
<Delivery><D> // delivery location name goes in pick up location
<DeliveryNonStop><false>
<KeepSameOrder><true>

<Name><D> // delivery location
<Delivery><R> // return to pickup location name goes here
<DeliveryNonStop><false>
<KeepSameOrder><true>

<Name><R> // return location name and property (same as P)
<DeliveryNonStop><false>
<KeepSameOrder><true>

TrackRoad API round trip stops example. — Example: Round trip stops.

TrackRoad API round trip route example. — Example: Round trip route.

Endpoints and base URLs#

REST#

Item	Value
Base URL	https://trackservice.trackroad.com
Endpoint	`POST /rest/dispatch`
Full URL	https://trackservice.trackroad.com/rest/dispatch
Content-Type	`application/json`

SOAP#

Item	Value
Endpoint	https://trackservice.trackroad.com/TrackService.asmx
WSDL	https://trackservice.trackroad.com/TrackService.asmx?WSDL
Method	`Dispatch`
SOAPAction	http://trackservice.trackroad.com/Dispatch

SOAP uses the same request/response model (DispatchSpecification / DispatchResult). The transport differs (SOAP envelope + header).

Authentication (REST & SOAP)#

REST authentication (X-API-Key)#

Include your TrackServiceKey in the X-API-Key header on every request. Generate the key in your TrackRoad account: API Authentication.

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()

Keep API keys server-side. Do not embed keys in browser or mobile client code.

SOAP authentication (SessionIDHeader)#

For SOAP requests, send your TrackServiceKey in the SessionIDHeader as SessionID. Login/Logout are no longer required when using TrackServiceKey (keep them documented as legacy if you want).

<?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);

SOAP note: namespaces/prefixes may differ depending on tooling. Prefer a WSDL-generated client when possible.

Request schema#

The request body is a single object: DispatchSpecification. At minimum, provide Vehicles and Locations.

DispatchSpecification#

Property	Type	Required	Description
`RoutingService`	int (enum)	No	Routing engine. 0=NetRoad, 1=TrackRoad, 2=Bing (Recommended is 0=NetRoad)
`IsNeedMatchCode`	bool	No	If true, include match quality codes where relevant.
`CurrentTime`	string (date-time)	No	Current time reference used for time constraints (ISO 8601).
`DispatchMode`	int (enum)	No	Optimization strategy (0=Auto, 1=EqualStop, 2=SingleRegion, 3=MultipleRegion, 4=EqualHour, 5=EqualDistance 6=TimeWindow, 7=TimeWindowDepot, 8=Optima, 9=BalanceLocation, 10=BalanceTime, 11=MinimumVehicles). For recommendations see Dispatch Modes (Recommended is 0=Auto).
`MinimumOptimization`	int	No	Optimization intensity / minimum optimization threshold. Range 1 - 10.
`DistanceUnit`	int (enum)	No	0=Mile, 1=Kilometer.
`RouteOptimize`	int (enum)	No	0=MinimizeTime, 1=MinimizeDistance (Recommended is 0=MinimizeTime).
`Vehicles`	Vehicle[]	No	Vehicles available for dispatch.
`Locations`	Location[]	Yes	Stops to be ordered.

DispatchMode#

Property	Type	Value	Description
`Auto`	int	0	Select Auto for best performance.
`EqualStop`	int	1	Driver's max stops is changed to an equal number. Use this if you want every driver to have same number of stops. Not terribly efficient but may apply in some situations.
`SingleRegion`	int	2	Drivers are sent to the same area. Very efficient when vehicles are scattered. Not efficient if drivers start at same location. However, this mode is fastest for servicing clients who are in the same area.
`MultipleRegion`	int	3	Dispatches in geographically dispersed mode. Works great when vehicles are in completely different cities, constantly on the move or are in different areas of the same city. This is probably the best method for time-sensitive and mission-critical application like courier, dispatching or trucking. Itc can work well in real-time mode using GPS devices.
`EqualHour`	int	4	Route is divided into equal chuncks of approximately same distance. Works well for deliveries orginating from Warehouse or a Single Depot(central) or when all vehicles start from same location
`EqualDistance`	int	5	Route is divided into equal segment of approximately same distance. Works well for deliveries orginating from warehouse or a single depot(central) or when all vehicles start from same location and everyone is supposed to drive same distance.
`TimeWindow`	int	6	Uses the times in each stop to determine best route option. See Time Window page for more info. Please note that when using this mode, optimization can be lost in favor of achieving best arrival/departure times.
`TimeWindowDepot`	int	7	Same as TimeWindow with the exception that this mode uses first vehicle start/finish position as central depot. Use this if you need time window and all your vehicles start/finish from a warehouse or depot. This mode can determine exactly how many vehicles are needed to visit all the stops within times required. Best to use when you need to know before hand how many vehicles are needed. This mode assumes no limits on capacity or weight of vehicles since it must determine number of vehicles required.
`Optima`	int	8	Single Vehicle Only. Highly recommended, gives best result. Use this mode with or without Time Windows, and/or if you wish to have the highest possible accuracy. Optima can take slightly longer than Auto but the results are excellent.
`BalanceLocation`	int	9	To get an equal number of stops in routes with multiple drivers and multiple stops.
`BalanceTime`	int	10	To get an equal time in routes with multiple drivers and multiple stops.
`MinimumVehicles`	int	11	Use this if you need minimum number of vehicles to visit all of the stops. This mode uses the new Optima technology. Given a number of vehicles and a number of stops, a minimum number of vehicles is selected to visit all stops. Several factors can play into which vehicles are selected including Fuel Cost (FC). Suppose V1 and V2 are at the same location V1.MaxWeight=25000 and FC=2.00 Dist=10 V2.MaxWeight=10000 and FC=3.00 Dist=10 Cost1 = 2.010=20 Cost2 = 3.010=30 we prefer V1 with cost 20 Suppose V1 and V2 are in different locations V1.MaxWeight=25000 and FC=2.00 Dist=50 V2.MaxWeight=10000 and FC=3.00 Dist=30 Cost1 = 2.050=100 Cost2 = 3.030=90 we prefer V2 with cost 90 If one of vehicles does not have FC then FC is ignored

Vehicle#

Property	Type	Required	Description
`Name`	string	Recommended	Vehicle identifier displayed in results.
`Email`	string	No	Optional driver contact.
`Group`	string	No	Optional grouping label (teams, depot, region).
`Speed`	int	No	Optional speed override (implementation-dependent). Speed of the vehicle. A constanct variable. Integer. It can be Mile or Kilometer per hour. Logic of many dispatching modes can use Speed internally. If vehicle Speed is specified then logic uses it instead of the road speed. Speed can change calculations dramatically. If you want to use default road speed, then set Speed to 0. No matter what vehicle Speed is, it cannot be greater than allowable road speed. In other words, even if you set Speed to 1000 Km/h, it will not go faster than 80Km/hour on a road with 80Km/h speed limit.
`MaxStops`	int	No	Max number of stops this vehicle can service (maximum number of stops vehicle can make in each single route). When MaxStops is reached the route is split into v_, v_2, v_3, etc.
`MaxWeight`	double	No	Capacity constraint. Each Location is given a weight variable. MaxWeight is total weight (double) a vehicle can accomodate before it is set aside.
`MaxSkids`	int	No	Capacity constraint. Maximum number of skids a vehicle can accomodate. When this value is reached, the vehicle is set aside.
`MaxVolume`	double	No	Capacity constraint. Maximum volume a vehicle can accoumodate. This value could be tonnage, metric, liter or anything you want it to be.
`MaxMinutes`	int	No	Max route time for this vehicle (seconds/minutes depending on setup). Maximum number of minutes vehicle can make in each single route. When MaxMinutes is reached the route is split into v_, v_2, v_3, etc. Integer
`FuelCost`	double	No	Optional cost parameter.
`OnTheRoad`	bool	No	OnTheRoad feature allows specifying whether the vehicle should come back to the start point before starting the next route sequence. The OnTheRoad only applies when MaxStops or MaxMinutes for a vehicle are greater than 0 and stops/minutes count reach maximum value. For example, a vehicle with a MaxStops of 10 per day and 50 stops will have a route that will last 5 days with 10 stops every day. When we have more than one day for a vehicle's route, the question becomes: do we want to start from the vehicle's initial starting point the next day (a warehouse) or do start from last day's finish location (we are on-the-road)? If a route spans over several days and you do not wish to return back to initial start point every time then set OnTheRoad to true. Example: A daily route example of OnTheRoad enabled versus disabled.
`Tin`	string (date-time)	No	Vehicle available-from timestamp. Time in/Time out for the vehicle. System uses time in/time out to calculate time windows and estimated arrival times. Always good to specify if you know when vehicle starts the route.
`Tout`	string (date-time)	No	Vehicle available-until timestamp.
`StartLocation`	Location	No	Optional start depot/position for this vehicle. Vehicle initial position and an important variable since all route optimization are calculated relative to this location
`FinishLocation`	Location	No	Optional end depot/position for this vehicle. An optional end location for the vehicle. Using a finish location can increase optimization even more. Use it if finish location at the end of the route is known.
`Roles`	string	No	Optional role string (business-specific). If not left blank, it must satisfiy "Conditions" in the stops separated by comma, i.e. Plumber, Electrician.
`Shapes`	Shape[]	No	Optional geofence / restriction shapes (experimental, not supported).

Location#

Each Location must include LatLong (preferred) and/or Address. If LatLong is omitted, Address is required so TrackRoad can geocode the stop.

Property	Type	Required	Description
`MatchCode`	int (enum)	No	Geocode match quality (None/Poor/Approx/Good/Exact).
`Name`	string	No	Stop label shown in results.
`Delivery`	string	No	Delivery location name / customer label.
`DeliveryNonStop`	bool	No	If true, proceed without stopping (business workflow option).
`KeepSameOrder`	bool	No	If true, keep this stop’s relative order as provided.
`Vehicle`	string	No	Optional pre-assignment to a specific vehicle by name.
`Description`	string	No	Optional notes.
`Phone`	string	No	Optional contact.
`LatLong`	LatLong	Conditional	Preferred coordinate input. If omitted, Address is required.
`Address`	Address	Conditional	Required if LatLong is missing.
`Priority`	int	No	Priority hint (e.g., 0=low, 10=high).
`Wait`	int	No	Service time at stop (often seconds).
`Volume`	double	No	Demand consumed from vehicle capacity.
`Weight`	double	No	Demand consumed from vehicle capacity.
`Skids`	int	No	Demand consumed from vehicle capacity.
`TimeConstraintArrival`	string (date-time)	No	Time window start.
`TimeConstraintDeparture`	string (date-time)	No	Time window end.
`TimeConstraintArrival2`	string (date-time)	No	Optional second window start.
`TimeConstraintDeparture2`	string (date-time)	No	Optional second window end.
`TimeEstimatedArrival`	string (date-time)	No	Estimated arrival (output/optional input depending on usage).
`LocationType`	int (enum)	No	0=Midway, 1=Start, 2=Finish, 3=Delivery, 4=MidwayDrop, 5=Break.
`CanArriveEarly`	bool	No	If false, do not arrive before window.
`Distance`	double	No	Computed/advanced use.
`Time`	int	No	Computed/advanced use (seconds).
`Conditions`	string	No	Optional conditions field.

LatLong#

Property	Type	Required	Description
`Latitude`	double	Yes	Latitude in degrees (-90..90).
`Longitude`	double	Yes	Longitude in degrees (-180..180).

Address#

Property	Type	Required	Description
`Street`	string	Recommended	Street address.
`City`	string	Recommended	City.
`State`	string	No	State/region.
`PostalCode`	string	No	ZIP/postal code.
`Country`	string	Recommended	Country (e.g., USA).

Shape#

Property	Type	Required	Description
`Points`	LatLong[]	Yes	Polygon/polyline points.
`Restriction`	int (enum)	No	0=DoNotEnter, 1=DoNotExit.

Response schema#

A successful response returns DispatchResult containing per-vehicle route items.

DispatchResult#

Property	Type	Description
`Items`	VehicleItem[]	Per-vehicle result items (vehicle + ordered locations).
`Errors`	Error[]	Optional errors/warnings (may be present even if Status indicates success-with-errors).
`Status`	int (enum)	Operation status: 0=None, 1=Success, 2=Failed, 3=SuccessWithErrors.

VehicleItem#

Property	Type	Description
`Vehicle`	Vehicle	The vehicle for this route.
`Locations`	Location[]	Ordered locations assigned to that vehicle.

Error#

Property	Type	Description
`Message`	string	Human-readable error or warning message.

Examples (REST & SOAP)#

REST: Minimal request example (recommended pattern)#

This example shows a typical pattern: vehicle + stops using LatLong. Replace coordinates, time windows, and capacity fields as needed.

{
  "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>

Common errors#

REST 401 / Unauthorized: Missing or invalid X-API-Key.
REST 403 / Forbidden: Key is valid but blocked, expired, or lacks credit.
Validation errors: A stop is missing both LatLong and Address, or coordinates are invalid.
SOAP authentication errors: Missing/invalid SessionIDHeader or empty SessionID.

Best practices#

Prefer LatLong to avoid geocoding cost/ambiguity. Use Address only when needed.
Use StartLocation / FinishLocation for depot-based routing.
Add capacity constraints (weight/volume/skids) if you need realistic assignment decisions.
Use time windows (TimeConstraintArrival/TimeConstraintDeparture) for appointment routing.
SOAP note: Login/Logout are not required when using TrackServiceKey (SessionIDHeader).

Ready to optimize routes?

Generate your API Key (TrackServiceKey), then start with Dispatch to build multi-vehicle route optimization (REST or SOAP).

Get API Key SOAP WSDL Swagger UI

Table of Contents