RESTful APIs Developer Guide

Our routing, location and mapping APIs allow you to enhance and develop your own specialty applications by calling data from PC*Miler, the transportation industry standard for more than 30 years.

With our easy-to-use RESTful APIs, you can generate routes for trucks and other commercial vehicles, calculate distances, and gather location information throughout the world.

What Can You Do?

Our services are widely used by fleet management companies, carriers and shippers in the U.S., Canada, Mexico, and Europe for applications such as freight rating, fuel surcharge computations, and equipment usage monitoring.

They can be used in developing native .NET based applications on your Microsoft Windows machines, Android and iOS applications on mobile devices, as well as web browser applications.

You can also use our JavaScript Maps SDK to build map-centric web applications that call routing and location data.

Accessing Services

The APIs provide a direct way to access these services via HTTP/S requests. The base URIs to access our various services via HTTP REST requests are:

PC*Miler Web Services

Other Licensed Services

CoPilot Web Tools

API Key

All requests to Web Services must include a valid API Key. You can request a free, trial key to test the PC*Miler Web Services APIs for a limited time.

The API Key must be supplied with every request. If the client making the API request has an invalid API key, then the key will fail to authenticate.

For POST requests, insert the API Key in the http Authorization: header

For GET requests, use authToken={APIKey} in the query string in the URI of the request. For example:

https://pcmiler.alk.com/apis/rest/v1.0/Service.svc/maptile?authToken=23423421341341234&x=5&y=4&z=3

(Several APIs and data sets require add-on licensing. A Trimble Maps representative will discuss these options when you purchase a subscription for an API key.)

Request Properties

All API request parameters and method parameters can be sent via the standard HTTP methods—POST, GET, PUT, and DELETE.

A typical REST action consists of sending an HTTP request to the API Server and waiting for the response. Like any HTTP request, a REST request to API Server contains a request method, a URI, request headers, and a query string or request body. The response contains an HTTP status code, response headers, and a response body.

URL Encoding Requests

It is important that you URL encode any URL in order to ensure that it does not contain any “Unsafe” or “Reserved” characters. It is especially important to URL encode any data included in a URL—things like coordinates, addresses, or other text will often include characters that must be encoded in order to be included in a URL.

Most programming languages have packages or functions that will automatically encode a URL. For example, in JavaScript there is a built-in function called encodeURIComponent.

function dictToParamString(obj) {
  var str = [];
  for (var p in obj) str.push(encodeURIComponent(p) + "=" + encodeURIComponent(obj[p]));
  return str.join("&");
}

params = {
  coords: "-85.974742,36.89",
  states: "NJ,NY,VA,CT",
  query: "79th Place North & Everest Lane North, Osseo, MN, 55311",
  other: "Other characters that need encoding include: ':/?#[]@!'"
};

alert(dictToParamString(params));

In C#, the HTTPUtility class provides methods for encoding and decoding

var parameters = new Dictionary<string, string>(){
   {"coords", "-85.974742,36.89"},
   {"states", "NJ,NY,VA,CT"},
   {"query", "79th Place North & Everest Lane North, Osseo, MN, 55311"},
   {"other", "Other characters that need encoding include: ':/?#[]@!'"}
};

var url = string.Format("http://yoursite.example.com?{0}",
   HttpUtility.UrlEncode(string.Join("&",
       parameters.Select(kvp =>
           string.Format("{0}={1}", kvp.Key, kvp.Value)))));

Console.WriteLine(url);

In Java, the URLEncode class provides encode and decode methods

  URLEncoder.encode(value, StandardCharsets.UTF_8.toString());

Complete example requests using these methods can be found in the section below.

View sample API calls in popular languages.

Examples

Throughout this guide, you will see interactive examples where you can both validate your API key and test any calls to our Web Services. You need to enter your key in the YOUR API KEY HERE field in order for the sample requests to return a response.