Geocode API (Address → Latitude/Longitude)

Use Geocode to convert postal addresses into LatLong coordinates. Geocoding is typically the first step before route planning or dispatch optimization when you don’t already have coordinates.

TrackRoad Geocode API converting an address into latitude/longitude coordinates (REST + SOAP).
Geocode API example: convert an address into Lat/Long coordinates for accurate routing and dispatch.

Best practice: Validate stops before route optimization

Bad addresses are the #1 cause of missing stops, incorrect routes, and optimization failures. Use Geocode first, then Dispatch.

Route Optimization API Reference Overview View Swagger UI

Table of Contents

  1. What is geocoding and why it matters
  2. What Geocode does
  3. Understanding MatchCode
  4. REST endpoint and base URL
  5. SOAP endpoint
  6. Authentication
  7. Request schema
  8. Response schema
  9. Examples (REST + SOAP)
  10. Common errors
  11. Best practices
  12. Related endpoints

What is geocoding and why it matters#

Geocoding converts an address like 350 5th Ave, New York, NY into latitude/longitude coordinates. Route optimization engines depend on accurate stop coordinates.

  • Incorrect coordinates → wrong routes and wrong distances
  • Missing coordinates → dispatch failures / missing stops
  • Ambiguous addresses → low MatchCode and poor results

If you optimize routes without validating addresses, you will often see “missing stops” or impossible time windows.

What Geocode does#

Geocode accepts one or more Address objects and returns one or more candidate Location results per address. Each returned Location includes LatLong coordinates and a MatchCode indicating match quality.

Costs / transactions: Each address geocoded counts as a transaction (one request can include multiple addresses).

Understanding MatchCode#

MatchCode is a confidence score returned when geocoding. It shows how well TrackRoad matched your address to a real location.

  • High MatchCode = precise match (best for dispatch)
  • Low MatchCode = ambiguous / incomplete address
  • No match = invalid address or missing city/state/country

If MatchCode is low, fix the address or submit latitude/longitude directly.

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 are POST and can return JSON (and XML depending on content-type).

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/headers for Geocode are defined in the WSDL (SOAP 1.1 / SOAP 1.2).

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": [] }'

Keep API keys server-side. Do not embed keys 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 in the header for each call (Login/Logout are not required anymore, but can remain documented as legacy).

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

Request schema#

The request body is a single object: GeocodeSpecification. Provide one or more Addresses.

GeocodeSpecification#

Property Type Required Description
IsNeedMatchCode bool No If true, includes match quality codes in results (recommended).
Addresses Address[] Yes* One or more addresses to geocode. Each item is a transaction.

Address#

Address is shared across endpoints. Full Address schema is defined on: Dispatch API (shared models).

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

Response schema#

A successful response returns GeocodeResult containing a list of GeocodeItem objects. Each item corresponds to an input Address.

GeocodeResult#

Property Type Description
Items GeocodeItem[] One item per input address (may contain multiple candidate Locations).
Errors Error[] Errors/warnings if any.
Status int (enum) 0=None, 1=Success, 2=Failed, 3=SuccessWithErrors.

GeocodeItem#

Property Type Description
Address Address The original input address.
Locations Location[] Candidate geocode results (may be 0, 1, or many).

Location, LatLong, MatchCode#

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

Error#

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

Examples (REST + SOAP)#

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" }
    ]
  }'

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>'

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 (REST).
  • 403 / Forbidden: Key valid but blocked, expired, or lacks credit.
  • Invalid address: Address is incomplete/ambiguous; response may return zero candidates or low match code.
  • SOAP auth failure: Missing/invalid SessionIDHeader (SessionID must be your TrackServiceKey).

Best practices#

  • Cache geocoding results in your system. Don’t geocode the same address repeatedly unless it changes.
  • Prefer stable inputs: street + city + state + postal code + country reduces ambiguity.
  • Use MatchCode to filter/approve results (Exact/Good typically safe; Poor/Approx may require review).
  • Feed Dispatch/Route with LatLong once geocoded (faster + avoids repeated geocoding).
  • If Geocode returns multiple candidates, pick the best one (highest MatchCode + best formatted address for your use case).

Next step: optimize routes

After geocoding, use Dispatch or Route with LatLong to generate accurate ETAs, distances, and optimized stop order.

Go to Dispatch View Swagger UI