Dispatch API (Route Optimization)

Q: How do I authenticate to Dispatch REST and SOAP?

REST uses your TrackServiceKey in the X-API-Key header. SOAP uses the same TrackServiceKey in SessionIDHeader as SessionID.

Q: Do I need LatLong or Address for stops?

LatLong is preferred. If LatLong is not provided, Address is required so TrackRoad can geocode the stop.

Use Dispatch to optimize routes across multiple vehicles and many stops. Dispatch returns an ordered route per vehicle with timing, distance, and assignment output for delivery routing, field service, courier operations, and fleet planning.

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

Need the full contract?

Use Swagger for REST models and WSDL for SOAP integration details.

View Swagger UI View SOAP WSDL API Reference Overview

What Dispatch does
Optima mode, Time Window & TimeWindowDepot
Multiple pickups and deliveries
Endpoints and base URLs
Authentication
Request schema
Response schema
Common errors
Best practices
Related endpoints
FAQ

What Dispatch does#

Dispatch solves a multi-vehicle routing problem. It assigns stops to vehicles and orders each route using constraints such as time windows, capacity, priority, and start or finish 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.

The Dispatch method accepts a list of vehicles and a list of stop locations. Each vehicle can include a start location and an optional finish location. Each location can contain a name, address fields, and latitude and longitude.

If latitude and longitude are present, TrackRoad uses them directly. Otherwise, the service geocodes the address to obtain coordinates.

Dispatch returns vehicle items. Each vehicle item contains the assigned route as an ordered list of stops, optimized by location, capacity, timing, and other routing factors.

When only one vehicle is available, Dispatch performs route optimization only. Dispatching modes primarily matter when there are multiple vehicles available.

If you are unsure which dispatching mode to use, start with Auto. For highly accurate single-vehicle optimization, use Optima.

Optima mode, Time Window & TimeWindowDepot#

In some languages it may not be possible to pass a null datetime. In that case, use 0001-01-01T00:00:00. Dates older than the system threshold are treated as null values.

For best results, use DispatchMode Optima.

Three variables affect time-window dispatching behavior:

CanArriveEarly
TimeConstraintArrival
TimeConstraintDeparture

Option 1: CanArriveEarly = true

When CanArriveEarly is true, the time window starts at the beginning of the day. If TimeConstraintArrival is null, the stop can be visited any time during the day. If TimeConstraintArrival is set, it defines the latest acceptable arrival time. Departure time is ignored.

Option 2: CanArriveEarly = false

When CanArriveEarly is false, arrival and departure define the allowed time window. If arrival is set and departure is null, the stop is treated like a precise appointment. If both are set, TrackRoad attempts to visit the stop within that time range.

Option 3: Two time windows

You can also specify a second time window using TimeConstraintArrival2 and TimeConstraintDeparture2. This is useful when a stop can only be visited during two separate periods, such as restricted downtown delivery hours. TimeWindowDepot follows the same logic but assumes vehicles start and finish from a common depot.

Breaks can be modeled with LocationType = Break. Multiple pickup and delivery chains support only one delivery time window at the delivery level, and that child time constraint cannot be tighter than the parent constraint.

Multiple pickups and deliveries#

Dispatch supports pickup and delivery chaining. This is useful for courier operations and workflows where one stop must be visited before another.

Use Midway for the first stop in a chain and Delivery to specify the next related location. Use DeliveryNonStop to determine whether the next linked delivery must happen immediately or can occur later in the same route.

For example, if a parcel is picked up at location B and delivered to location M, TrackRoad preserves the required relationship between the pickup and the delivery while still optimizing the route around the remaining stops.

DeliveryNonStop = true

When DeliveryNonStop is true, the linked delivery stop must be visited immediately after the pickup stop.

DeliveryNonStop = false

When DeliveryNonStop is false, the linked delivery must still occur after the pickup, but it does not need to happen immediately.

You can daisy-chain multiple deliveries, such as B → M → N, by setting Delivery and KeepSameOrder on each linked stop.

For round-trip jobs, define pickup, delivery, and return locations as a chain. A common recommendation is DeliveryNonStop = false and KeepSameOrder = true for more flexible optimization while preserving business order.

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 DispatchSpecification and DispatchResult models. The main difference is the SOAP envelope and header-based authentication.

Authentication#

REST authentication (X-API-Key)

Include your TrackServiceKey in the X-API-Key header on every request. Generate the key in your TrackRoad account at 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 SessionIDHeader as SessionID. Legacy Login and Logout are not required when you use TrackServiceKey authentication.

<?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 namespaces and prefixes may vary depending on your tooling. A WSDL-generated client is usually the easiest option.

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: 0 = NetRoad.
`IsNeedMatchCode`	bool	No	If true, includes geocoding match-quality codes where relevant.
`CurrentTime`	string (date-time)	No	Current time reference used for time constraints in ISO 8601 format.
`DispatchMode`	int (enum)	No	Optimization strategy. For mode recommendations, see Dispatch Modes.
`MinimumOptimization`	int	No	Optimization intensity threshold. Typical range: 1 to 10.
`DistanceUnit`	int (enum)	No	0 = Mile, 1 = Kilometer.
`RouteOptimize`	int (enum)	No	0 = MinimizeTime, 1 = MinimizeDistance. Recommended: 0 = MinimizeTime.
`Vehicles`	Vehicle[]	No	Vehicles available for dispatch.
`Locations`	Location[]	Yes	Stops to be assigned and ordered.

DispatchMode

Property	Type	Value	Description
`Auto`	int	0	Automatically selects a suitable dispatching strategy. Best default starting point.
`EqualStop`	int	1	Attempts to distribute an equal number of stops across vehicles.
`SingleRegion`	int	2	Useful when vehicles are geographically dispersed but serve stops in similar areas.
`MultipleRegion`	int	3	Useful for vehicles operating in different cities or distant regions and for real-time field dispatch.
`EqualHour`	int	4	Attempts to divide work into routes with similar total time.
`EqualDistance`	int	5	Attempts to divide work into routes with similar total distance.
`TimeWindow`	int	6	Prioritizes appointment and delivery windows. Optimization may be reduced to meet timing constraints.
`TimeWindowDepot`	int	7	Time-window mode that assumes a central depot shared by vehicles.
`Optima`	int	8	Highly accurate mode for a single vehicle, with or without time windows.
`BalanceLocation`	int	9	Balances the number of assigned stops across multiple drivers.
`BalanceTime`	int	10	Balances route time across multiple drivers.
`MinimumVehicles`	int	11	Selects the minimum number of vehicles required to service all stops, taking routing factors into account.

Vehicle

Property	Type	Required	Description
`Name`	string	Recommended	Vehicle identifier displayed in results.
`Email`	string	No	Optional driver or vehicle contact.
`Group`	string	No	Optional grouping field such as team, depot, or region.
`Speed`	int	No	Optional speed override. If set to 0, default road speed is used.
`MaxStops`	int	No	Maximum number of stops per route for the vehicle.
`MaxWeight`	double	No	Maximum weight capacity for the vehicle.
`MaxSkids`	int	No	Maximum skid capacity for the vehicle.
`MaxVolume`	double	No	Maximum volume capacity for the vehicle.
`MaxMinutes`	int	No	Maximum route duration for the vehicle.
`FuelCost`	double	No	Optional cost parameter used by some optimization modes.
`OnTheRoad`	bool	No	If true, a multi-day route can continue from the prior day’s end location instead of returning to the original start point.
`Tin`	string (date-time)	No	Vehicle available-from timestamp.
`Tout`	string (date-time)	No	Vehicle available-until timestamp.
`StartLocation`	Location	No	Optional start depot or start position for the vehicle.
`FinishLocation`	Location	No	Optional finish depot or end position for the vehicle.
`Roles`	string	No	Optional role string that can be matched against stop conditions.
`TransportType`	int (enum)	No	Transport mode such as car, truck, bus, motorcycle, pedestrian, scooter, or bicycle.
`ExcludeTolls`	bool	No	Specifies whether toll roads should be avoided.
`ExcludeHighways`	bool	No	Specifies whether highways should be avoided.
`UseTruckRoute`	bool	No	Specifies whether truck routes should be preferred or allowed.
`Width`	float	No	Vehicle width in meters.
`Height`	float	No	Vehicle height in meters.
`Length`	float	No	Vehicle length in meters.
`AxleLoad`	float	No	Vehicle axle load in metric tons.
`AxleCount`	int	No	Number of axles.

Location

Each location should include LatLong when possible. If coordinates are missing, Address is required so TrackRoad can geocode the stop.

Property	Type	Required	Description
`MatchCode`	int (enum)	No	Geocode match quality code.
`Name`	string	No	Stop label shown in results.
`Delivery`	string	No	Linked delivery location name or customer label.
`DeliveryNonStop`	bool	No	Determines whether the linked delivery must happen immediately after the current stop.
`KeepSameOrder`	bool	No	If true, preserves the relative order defined in the request.
`Vehicle`	string	No	Optional pre-assignment to a specific vehicle by name.
`Description`	string	No	Optional notes or description.
`Phone`	string	No	Optional contact phone number.
`LatLong`	LatLong	Conditional	Preferred coordinate input. Required if Address is not provided.
`Address`	Address	Conditional	Address input used for geocoding when LatLong is not provided.
`Priority`	int	No	Priority hint for optimization.
`Wait`	int	No	Service time or wait time at the stop.
`Volume`	double	No	Volume demand consumed from vehicle capacity.
`Weight`	double	No	Weight demand consumed from vehicle capacity.
`Skids`	int	No	Skid demand consumed from vehicle capacity.
`TimeConstraintArrival`	string (date-time)	No	Primary time-window arrival value.
`TimeConstraintDeparture`	string (date-time)	No	Primary time-window departure value.
`TimeConstraintArrival2`	string (date-time)	No	Optional second time-window arrival value.
`TimeConstraintDeparture2`	string (date-time)	No	Optional second time-window departure value.
`LocationType`	int (enum)	No	0 = Midway, 1 = Start, 2 = Finish, 3 = Delivery, 4 = MidwayDrop, 5 = Break.
`CanArriveEarly`	bool	No	If false, arrival before the allowed time window is not permitted.
`Conditions`	string	No	Optional business rule or role-matching condition.

LatLong

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

Address

Property	Type	Required	Description
`Street`	string	Recommended	Street address.
`City`	string	Recommended	City.
`State`	string	No	State or region.
`PostalCode`	string	No	ZIP or postal code.
`Country`	string	Recommended	Country.

Response schema#

A successful response returns DispatchResult containing per-vehicle route items and optional errors or warnings.

DispatchResult

Property	Type	Description
`Items`	VehicleItem[]	Per-vehicle result items containing the assigned route.
`Errors`	Error[]	Optional errors or warnings.
`Status`	int (enum)	Operation status: 0 = None, 1 = Success, 2 = Failed, 3 = SuccessWithErrors.

VehicleItem

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

Error

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

Examples#

Example request and response code blocks can remain unchanged and do not need localization.

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>

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 or invalid SessionIDHeader or empty SessionID.

Best practices

Prefer LatLong to avoid geocoding ambiguity and improve routing consistency.
Use StartLocation and FinishLocation for depot-based routing and better ETAs.
Add capacity constraints such as weight, volume, and skids for more realistic route assignment.
Use time windows when stops must be visited within customer or operational schedules.
For SOAP, use TrackServiceKey in SessionIDHeader. Legacy login flow is not required.

FAQ#

What does the Dispatch API do?

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

How do I authenticate to Dispatch REST and SOAP?

REST uses your TrackServiceKey in the X-API-Key header. SOAP uses the same TrackServiceKey in SessionIDHeader as SessionID.

Do I need LatLong or Address for stops?

LatLong is preferred. If LatLong is not provided, Address is required so TrackRoad can geocode the stop.

Ready to optimize routes?

Generate your API key, then start integrating Dispatch for multi-vehicle route optimization using REST or SOAP.

Get API Key SOAP WSDL Swagger UI

Table of contents