Geocode API (Address → Latitude/Longitude)

Q: How do I authenticate to the Geocode API?

For REST, send your TrackServiceKey in the X-API-Key header. For SOAP, send your TrackServiceKey in SessionIDHeader as SessionID.

Use Geocode to convert postal addresses into latitude/longitude coordinates. Geocoding is usually the first step before route planning or dispatch optimization when you do not already have reliable stop coordinates.

Geocode API example: convert an address into latitude/longitude coordinates for accurate routing and dispatch.

Best practice: validate stops before route optimization

Bad addresses are one of the most common causes of missing stops, incorrect routes, and avoidable optimization failures. Geocode first, then call Dispatch or Route.

API Reference Overview View Swagger UI

What geocoding is and why it matters
What Geocode does
Understanding MatchCode
REST endpoint and base URL
SOAP endpoint
Authentication
Request schema
Response schema
Examples
Common errors
Best practices
Related endpoints
FAQ

What geocoding is and why it matters#

Geocoding converts a postal address such as 350 5th Ave, New York, NY into latitude/longitude coordinates that software can use for routing, ETA calculation, and distance measurement.

Route optimization engines depend on accurate stop coordinates. When addresses are incomplete, ambiguous, or wrong, route results become less reliable.

Incorrect coordinates can produce wrong routes, wrong distances, and poor ETAs.
Missing coordinates can lead to dispatch failures, skipped stops, or unassigned work.
Ambiguous addresses can result in low MatchCode values and lower confidence results.

If you optimize routes without validating addresses first, you are more likely to see missing stops, infeasible plans, or poor route quality.

What Geocode does#

Geocode accepts one or more Address objects and returns one or more candidate Location results for each address. Each returned Location can include LatLong coordinates and a MatchCode value that helps you evaluate match quality.

Transactions: each address geocoded counts as a transaction, even when multiple addresses are submitted in the same request.

Understanding MatchCode#

MatchCode is a confidence indicator returned during geocoding. It shows how closely TrackRoad matched your input address to a real-world location.

High MatchCode usually means a more precise match and is typically safer for dispatch.
Low MatchCode usually means the address is incomplete, ambiguous, or less reliable.
No useful match may indicate an invalid address or missing city, state, postal code, or country data.

If MatchCode is low, correct the address or send latitude/longitude directly when coordinates are already known.

REST endpoint and base URL#

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

REST geocode requests use POST and typically return JSON. Depending on integration details, XML may also be supported.

SOAP endpoint#

Item	Value
SOAP URL	https://trackservice.trackroad.com/TrackService.asmx
WSDL	https://trackservice.trackroad.com/TrackService.asmx?wsdl
SOAPAction	http://TrackService.TrackRoad.com/Geocode
Content-Type	`text/xml; charset=utf-8`

SOAP request envelopes and headers for Geocode are defined in the WSDL and may vary by SOAP version.

Authentication#

REST authentication (X-API-Key)

Include your TrackServiceKey in the X-API-Key header on every REST request. See API Authentication .

curl -X POST "https://trackservice.trackroad.com/rest/geocode" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_TRACKSERVICEKEY" \
  -d '{ "IsNeedMatchCode": true, "Addresses": [] }'

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

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

var json = @"{
  ""IsNeedMatchCode"": true,
  ""Addresses"": []
}";
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/geocode";

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

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

import okhttp3.*;

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

    String json = "{"
      + "\"IsNeedMatchCode\":true,"
      + "\"Addresses\":[]"
      + "}";

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

    Request request = new Request.Builder()
      .url("https://trackservice.trackroad.com/rest/geocode")
      .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/geocode"
headers = {
  "Content-Type": "application/json",
  "X-API-Key": "YOUR_TRACKSERVICEKEY"
}
payload = {
  "IsNeedMatchCode": True,
  "Addresses": []
}

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

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

$payload = json_encode([
  "IsNeedMatchCode" => true,
  "Addresses" => []
]);

$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/geocode")
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 = { IsNeedMatchCode: true, Addresses: [] }.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/geocode"
  jsonBody := []byte(`{"IsNeedMatchCode":true,"Addresses":[]}`)

  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/geocode"
  val json = """{"IsNeedMatchCode":true,"Addresses":[]}"""

  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 <stdlib.h>
#include <string.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/geocode";
  const char *json = "{\"IsNeedMatchCode\":true,\"Addresses\":[]}";

  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 <iostream>
#include <string>

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

  std::string url = "https://trackservice.trackroad.com/rest/geocode";
  std::string json = R"({"IsNeedMatchCode":true,"Addresses":[]})";

  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/geocode"];
    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 = @{@"IsNeedMatchCode": @YES, @"Addresses": @[]};
    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/geocode")!
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] = [
  "IsNeedMatchCode": true,
  "Addresses": []
]
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 whenever possible. Avoid embedding production API keys directly in browser or mobile client code.

SOAP authentication (SessionIDHeader)

SOAP requests use a SessionIDHeader. For TrackRoad SOAP services, send your TrackServiceKey as the SessionID value for each call. Legacy Login/Logout methods may still appear in older documentation but are not required for modern usage.

Recommended: prefer REST unless you must integrate with an existing SOAP-only system.

Request schema#

The request body is a single GeocodeSpecification object. Provide one or more addresses that you want to geocode.

GeocodeSpecification

Property	Type	Required	Description
`IsNeedMatchCode`	bool	No	If true, includes match quality indicators in the result. Recommended for production integrations.
`Addresses`	Address[]	Yes*	One or more addresses to geocode. Each address counts as a transaction.

Address

Address is a shared model across endpoints. The full Address schema is also documented on Dispatch API (shared models) .

Property	Type	Required	Description
`Street`	string	Recommended	Street address line.
`City`	string	Recommended	City or locality.
`State`	string	No	State, province, or region.
`PostalCode`	string	No	ZIP or postal code.
`Country`	string	Recommended	Country code or country name, for example US.

Response schema#

A successful response returns a GeocodeResult containing one or more GeocodeItem objects. Each item maps to one input address.

GeocodeResult

Property	Type	Description
`Items`	GeocodeItem[]	One item per input address. Each item may contain zero, one, or multiple candidate locations.
`Errors`	Error[]	Errors or warnings returned by the service.
`Status`	int (enum)	Status code such as 0=None, 1=Success, 2=Failed, or 3=SuccessWithErrors.

GeocodeItem

Property	Type	Description
`Address`	Address	The original input address.
`Locations`	Location[]	Candidate geocoding results for the address.

Location, LatLong, MatchCode

These models are shared across endpoints. See the full schema tables on Dispatch API (shared models) .

Error

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

Examples#

Use the following sections for REST and SOAP example requests and responses. Example code can remain language-neutral and does not need localization.

REST JSON request example#

Send one or more addresses in a single request.

{
  "IsNeedMatchCode": true,
  "Addresses": [
    {
      "Street": "6718 Whittier Avenue",
      "City": "McLean",
      "State": "VA",
      "PostalCode": "22101",
      "Country": "US"
    },
    {
      "Street": "1450 Old Chain Bridge Road",
      "City": "McLean",
      "State": "VA",
      "PostalCode": "22101",
      "Country": "US"
    }
  ]
}

REST request examples (multiple languages)#

curl -X POST "https://trackservice.trackroad.com/rest/geocode" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_TRACKSERVICEKEY" \
  -d '{
    "IsNeedMatchCode": true,
    "Addresses": [
      { "Street": "6718 Whittier Avenue", "City": "McLean", "State": "VA", "PostalCode": "22101", "Country": "US" }
    ]
  }'

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

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

var json = @"{
  ""IsNeedMatchCode"": true,
  ""Addresses"": [
    { ""Street"": ""6718 Whittier Avenue"", ""City"": ""McLean"", ""State"": ""VA"", ""PostalCode"": ""22101"", ""Country"": ""US"" }
  ]
}";
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/geocode";

const payload = {
  IsNeedMatchCode: true,
  Addresses: [
    { Street: "6718 Whittier Avenue", City: "McLean", State: "VA", PostalCode: "22101", Country: "US" }
  ]
};

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 = "{"
      + "\"IsNeedMatchCode\":true,"
      + "\"Addresses\":[{"
      + "\"Street\":\"6718 Whittier Avenue\","
      + "\"City\":\"McLean\","
      + "\"State\":\"VA\","
      + "\"PostalCode\":\"22101\","
      + "\"Country\":\"US\""
      + "}]"
      + "}";

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

    Request request = new Request.Builder()
      .url("https://trackservice.trackroad.com/rest/geocode")
      .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/geocode"
headers = {
  "Content-Type": "application/json",
  "X-API-Key": "YOUR_TRACKSERVICEKEY"
}
payload = {
  "IsNeedMatchCode": True,
  "Addresses": [
    { "Street": "6718 Whittier Avenue", "City": "McLean", "State": "VA", "PostalCode": "22101", "Country": "US" }
  ]
}

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

<?php
$url = "https://trackservice.trackroad.com/rest/geocode";
$payload = json_encode([
  "IsNeedMatchCode" => true,
  "Addresses" => [[
    "Street" => "6718 Whittier Avenue",
    "City" => "McLean",
    "State" => "VA",
    "PostalCode" => "22101",
    "Country" => "US"
  ]]
]);

$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/geocode")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

payload = {
  IsNeedMatchCode: true,
  Addresses: [
    { Street: "6718 Whittier Avenue", City: "McLean", State: "VA", PostalCode: "22101", Country: "US" }
  ]
}

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/geocode"
  jsonBody := []byte(`{
    "IsNeedMatchCode": true,
    "Addresses": [
      { "Street": "6718 Whittier Avenue", "City": "McLean", "State": "VA", "PostalCode": "22101", "Country": "US" }
    ]
  }`)

  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/geocode"
  val json = """
    {
      "IsNeedMatchCode": true,
      "Addresses": [
        { "Street": "6718 Whittier Avenue", "City": "McLean", "State": "VA", "PostalCode": "22101", "Country": "US" }
      ]
    }
  """.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/geocode";
  const char *json =
    "{"
    "\"IsNeedMatchCode\":true,"
    "\"Addresses\":[{"
      "\"Street\":\"6718 Whittier Avenue\","
      "\"City\":\"McLean\","
      "\"State\":\"VA\","
      "\"PostalCode\":\"22101\","
      "\"Country\":\"US\""
    "}]"
    "}";

  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/geocode";
  std::string json =
    "{"
    "\"IsNeedMatchCode\":true,"
    "\"Addresses\":[{"
      "\"Street\":\"6718 Whittier Avenue\","
      "\"City\":\"McLean\","
      "\"State\":\"VA\","
      "\"PostalCode\":\"22101\","
      "\"Country\":\"US\""
    "}]"
    "}";

  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/geocode"];
    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 = @{
      @"IsNeedMatchCode": @YES,
      @"Addresses": @[
        @{
          @"Street": @"6718 Whittier Avenue",
          @"City": @"McLean",
          @"State": @"VA",
          @"PostalCode": @"22101",
          @"Country": @"US"
        }
      ]
    };

    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/geocode")!
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] = [
  "IsNeedMatchCode": true,
  "Addresses": [
    [
      "Street": "6718 Whittier Avenue",
      "City": "McLean",
      "State": "VA",
      "PostalCode": "22101",
      "Country": "US"
    ]
  ]
]

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

REST JSON response example (shape)#

{
  "Items": [
    {
      "Address": {
        "Street": "6718 Whittier Avenue",
        "City": "McLean",
        "State": "VA",
        "PostalCode": "22101",
        "Country": "US"
      },
      "Locations": [
        {
          "MatchCode": 4,
          "LatLong": { "Latitude": 38.931594, "Longitude": -77.17602 },
          "Address": {
            "Street": "6718 Whittier Avenue",
            "City": "McLean",
            "State": "VA",
            "PostalCode": "22101",
            "Country": "US"
          }
        }
      ]
    }
  ],
  "Errors": [],
  "Status": 1
}

SOAP 1.1 request example#

SOAP Geocode uses SessionIDHeader with SessionID = TrackServiceKey and SOAPAction http://TrackService.TrackRoad.com/Geocode.

<!-- POST https://trackservice.trackroad.com/TrackService.asmx -->
<!-- Content-Type: text/xml; charset=utf-8 -->
<!-- SOAPAction: "http://TrackService.TrackRoad.com/Geocode" -->

<?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>
    <Geocode xmlns="http://TrackService.TrackRoad.com/">
      <specification>
        <IsNeedMatchCode>true</IsNeedMatchCode>
        <Addresses>
          <Address>
            <Street>6718 Whittier Avenue</Street>
            <City>McLean</City>
            <State>VA</State>
            <PostalCode>22101</PostalCode>
            <Country>US</Country>
          </Address>
        </Addresses>
      </specification>
    </Geocode>
  </soap:Body>
</soap:Envelope>

SOAP request examples (multiple languages)#

SOAP Geocode uses SessionIDHeader with SessionID = TrackServiceKey and SOAPAction http://TrackService.TrackRoad.com/Geocode.

curl -X POST "https://trackservice.trackroad.com/TrackService.asmx" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H "SOAPAction: "http://TrackService.TrackRoad.com/Geocode"" \
  -d '<?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>
    <Geocode xmlns="http://TrackService.TrackRoad.com/">
      <specification>
        <IsNeedMatchCode>true</IsNeedMatchCode>
        <Addresses>
          <Address>
            <Street>6718 Whittier Avenue</Street>
            <City>McLean</City>
            <State>VA</State>
            <PostalCode>22101</PostalCode>
            <Country>US</Country>
          </Address>
        </Addresses>
      </specification>
    </Geocode>
  </soap:Body>
</soap:Envelope>'

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

var url = "https://trackservice.trackroad.com/TrackService.asmx";
using var http = new HttpClient();

var soapAction = "http://TrackService.TrackRoad.com/Geocode";
var xml = @"

  
    
      YOUR_TRACKSERVICEKEY
    
  
  
    
      
        true
        
          
            6718 Whittier Avenue
            McLean
            VA
            22101
            US
          
        
      
    
  
";

var req = new HttpRequestMessage(HttpMethod.Post, url);
req.Headers.Add("SOAPAction", $"\"{soapAction}\"");
req.Content = new StringContent(xml, Encoding.UTF8, "text/xml");

var resp = await http.SendAsync(req);
Console.WriteLine(await resp.Content.ReadAsStringAsync());

const url = "https://trackservice.trackroad.com/TrackService.asmx";
const soapAction = "http://TrackService.TrackRoad.com/Geocode";

const xml = `

  
    
      YOUR_TRACKSERVICEKEY
    
  
  
    
      
        true
        
          
            6718 Whittier Avenue
            McLean
            VA
            22101
            US
          
        
      
    
  
`;

const res = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "text/xml; charset=utf-8",
    "SOAPAction": `"${soapAction}"`
  },
  body: xml
});

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

import okhttp3.*;

public class Main {
  public static void main(String[] args) throws Exception {
    String url = "https://trackservice.trackroad.com/TrackService.asmx";
    String soapAction = "http://TrackService.TrackRoad.com/Geocode";

    String xml =
      ""
    + ""
    + "  "
    + "    "
    + "      YOUR_TRACKSERVICEKEY"
    + "    "
    + "  "
    + "  "
    + "    "
    + "      "
    + "        true"
    + "        "
    + "          "
    + "            6718 Whittier Avenue"
    + "            McLean"
    + "            VA"
    + "            22101"
    + "            US"
    + "          "
    + "        "
    + "      "
    + "    "
    + "  "
    + "";

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

    Request request = new Request.Builder()
      .url(url)
      .post(body)
      .addHeader("Content-Type", "text/xml; charset=utf-8")
      .addHeader("SOAPAction", "\"" + soapAction + "\"")
      .build();

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

import requests

url = "https://trackservice.trackroad.com/TrackService.asmx"
soap_action = "http://TrackService.TrackRoad.com/Geocode"

xml = """

  
    
      YOUR_TRACKSERVICEKEY
    
  
  
    
      
        true
        
          
            6718 Whittier Avenue
            McLean
            VA
            22101
            US
          
        
      
    
  
"""

headers = {
  "Content-Type": "text/xml; charset=utf-8",
  "SOAPAction": f"\"{soap_action}\""
}

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

<?php
$url = "https://trackservice.trackroad.com/TrackService.asmx";
$soapAction = "http://TrackService.TrackRoad.com/Geocode";

$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>
    <Geocode xmlns="http://TrackService.TrackRoad.com/">
      <specification>
        <IsNeedMatchCode>true</IsNeedMatchCode>
        <Addresses>
          <Address>
            <Street>6718 Whittier Avenue</Street>
            <City>McLean</City>
            <State>VA</State>
            <PostalCode>22101</PostalCode>
            <Country>US</Country>
          </Address>
        </Addresses>
      </specification>
    </Geocode>
  </soap:Body>
</soap:Envelope>';

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: text/xml; charset=utf-8",
    'SOAPAction: "' . $soapAction . '"'
  ],
  CURLOPT_POSTFIELDS => $xml
]);

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

require "net/http"

uri = URI("https://trackservice.trackroad.com/TrackService.asmx")
soap_action = "http://TrackService.TrackRoad.com/Geocode"

xml = <<~XML


  
    
      YOUR_TRACKSERVICEKEY
    
  
  
    
      
        true
        
          
            6718 Whittier Avenue
            McLean
            VA
            22101
            US
          
        
      
    
  

XML

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

req = Net::HTTP::Post.new(uri)
req["Content-Type"] = "text/xml; charset=utf-8"
req["SOAPAction"] = "\"#{soap_action}\""
req.body = xml

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

package main

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

func main() {
  url := "https://trackservice.trackroad.com/TrackService.asmx"
  soapAction := "http://TrackService.TrackRoad.com/Geocode"

  xml := []byte(`

  
    
      YOUR_TRACKSERVICEKEY
    
  
  
    
      
        true
        
          
            6718 Whittier Avenue
            McLean
            VA
            22101
            US
          
        
      
    
  
`)

  req, _ := http.NewRequest("POST", url, bytes.NewBuffer(xml))
  req.Header.Set("Content-Type", "text/xml; charset=utf-8")
  req.Header.Set("SOAPAction", fmt.Sprintf("\"%s\"", soapAction))

  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/TrackService.asmx"
  val soapAction = "http://TrackService.TrackRoad.com/Geocode"

  val xml = """
    
    
      
        
          YOUR_TRACKSERVICEKEY
        
      
      
        
          
            true
            
              
                6718 Whittier Avenue
                McLean
                VA
                22101
                US
              
            
          
        
      
    
  """.trimIndent()

  val client = HttpClient.newHttpClient()
  val req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Content-Type", "text/xml; charset=utf-8")
    .header("SOAPAction", "\"$soapAction\"")
    .POST(HttpRequest.BodyPublishers.ofString(xml))
    .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/TrackService.asmx";
  const char *soapAction = "http://TrackService.TrackRoad.com/Geocode";

  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>"
        "<Geocode xmlns=\"http://TrackService.TrackRoad.com/\">"
          "<specification>"
            "<IsNeedMatchCode>true</IsNeedMatchCode>"
            "<Addresses>"
              "<Address>"
                "<Street>6718 Whittier Avenue</Street>"
                "<City>McLean</City>"
                "<State>VA</State>"
                "<PostalCode>22101</PostalCode>"
                "<Country>US</Country>"
              "</Address>"
            "</Addresses>"
          "</specification>"
        "</Geocode>"
      "</soap:Body>"
    "</soap:Envelope>";

  struct curl_slist *headers = NULL;
  headers = curl_slist_append(headers, "Content-Type: text/xml; charset=utf-8");

  char soapHdr[256];
  snprintf(soapHdr, sizeof(soapHdr), "SOAPAction: \"%s\"", soapAction);
  headers = curl_slist_append(headers, soapHdr);

  curl_easy_setopt(curl, CURLOPT_URL, url);
  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 <cstdio>

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

  const char* url = "https://trackservice.trackroad.com/TrackService.asmx";
  const char* soapAction = "http://TrackService.TrackRoad.com/Geocode";

  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>"
        "<Geocode xmlns=\"http://TrackService.TrackRoad.com/\">"
          "<specification>"
            "<IsNeedMatchCode>true</IsNeedMatchCode>"
            "<Addresses>"
              "<Address>"
                "<Street>6718 Whittier Avenue</Street>"
                "<City>McLean</City>"
                "<State>VA</State>"
                "<PostalCode>22101</PostalCode>"
                "<Country>US</Country>"
              "</Address>"
            "</Addresses>"
          "</specification>"
        "</Geocode>"
      "</soap:Body>"
    "</soap:Envelope>";

  struct curl_slist* headers = NULL;
  headers = curl_slist_append(headers, "Content-Type: text/xml; charset=utf-8");

  char soapHdr[256];
  std::snprintf(soapHdr, sizeof(soapHdr), "SOAPAction: \"%s\"", soapAction);
  headers = curl_slist_append(headers, soapHdr);

  curl_easy_setopt(curl, CURLOPT_URL, url);
  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;
}

#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/Geocode"" 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>"
         "<Geocode xmlns=\"http://TrackService.TrackRoad.com/\">"
           "<specification>"
             "<IsNeedMatchCode>true</IsNeedMatchCode>"
             "<Addresses>"
               "<Address>"
                 "<Street>6718 Whittier Avenue</Street>"
                 "<City>McLean</City>"
                 "<State>VA</State>"
                 "<PostalCode>22101</PostalCode>"
                 "<Country>US</Country>"
               "</Address>"
             "</Addresses>"
           "</specification>"
         "</Geocode>"
       "</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/Geocode\"", forHTTPHeaderField: "SOAPAction")

let xml = """


  
    
      YOUR_TRACKSERVICEKEY
    
  
  
    
      
        true
        
          
            6718 Whittier Avenue
            McLean
            VA
            22101
            US
          
        
      
    
  

"""

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 response example (shape)#

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>

    <GeocodeResponse xmlns="http://TrackService.TrackRoad.com/">
      <GeocodeResult>

        <Status>1</Status>
        <Errors />

        <Items>
          <GeocodeItem>

            <Address>
              <Street>6718 Whittier Avenue</Street>
              <City>McLean</City>
              <State>VA</State>
              <PostalCode>22101</PostalCode>
              <Country>US</Country>
            </Address>

            <Locations>
              <Location>
                <MatchCode>4</MatchCode>
                <LatLong>
                  <Latitude>38.931594</Latitude>
                  <Longitude>-77.17602</Longitude>
                </LatLong>
                <Address>
                  <Street>6718 Whittier Avenue</Street>
                  <City>McLean</City>
                  <State>VA</State>
                  <PostalCode>22101</PostalCode>
                  <Country>US</Country>
                </Address>
              </Location>
            </Locations>

          </GeocodeItem>
        </Items>

      </GeocodeResult>
    </GeocodeResponse>

  </soap:Body>
</soap:Envelope>

Common errors#

401 / Unauthorized: missing or invalid X-API-Key on REST requests.
403 / Forbidden: the key may be valid but blocked, expired, or unable to process the request.
Invalid or incomplete address: the service may return zero candidates, weak matches, or low MatchCode values.
SOAP authentication failure: missing or invalid SessionIDHeader where SessionID must contain your TrackServiceKey.

Best practices#

Cache geocoding results in your system so that you do not geocode the same address repeatedly unless it changes.
Use stable address inputs such as street, city, state, postal code, and country to reduce ambiguity.
Use MatchCode to filter or approve results when data quality matters.
Send LatLong to Dispatch or Route after geocoding to improve performance and avoid repeated lookups.
If Geocode returns multiple candidates, choose the best one using match quality and the formatted address that best fits your business rules.

FAQ#

What does the Geocode API do?

The Geocode API converts postal addresses into one or more candidate locations with latitude/longitude coordinates, helping you prepare accurate stop data for routing and dispatch.

How do I authenticate to the Geocode API?

For REST, send your TrackServiceKey in the X-API-Key header. For SOAP, send your TrackServiceKey in SessionIDHeader as SessionID.

Why can geocoding return multiple results?

Some addresses are ambiguous or incomplete, so the API may return multiple candidate locations. Use MatchCode and the returned address details to choose the best result.

Why should I geocode before route optimization?

Geocoding before route optimization improves route accuracy, ETAs, stop assignment, and distance calculations by ensuring that every stop has valid coordinates.

Next step: optimize routes with accurate coordinates

After geocoding addresses, use Dispatch or Route with latitude/longitude coordinates to generate more accurate ETAs, distances, and route sequences.

Go to Dispatch API View Swagger UI

Table of contents