RESTful APIs

Route Reports

Contents

With our Route Reports API, you can create a route and retrieve a wide range of information about it—everything from PC*Miler practical miles and turn-by-turn directions to trip costs and a detailed route path. Each route can be customized with a wide range of settings to fit your vehicles and business needs.

Pre-requisites

To call the Route Reports API, you must have a PC*Miler Web Services API key. If you don’t have a key, you can request a free, limited-time trial key.

Use Cases

The Trimble Maps routing algorithm has been used for more than 30 years to build safe, legal, and efficient routes for all types of commercial vehicles, around the world. The Route Reports API allows you to build custom routes, and then call information about them. You can:

Operations

Most Route Reports can be called via both GET and POST requests, unless otherwise noted.

  • POST requests offer more options for the ways route stops are entered. They also allow for batch requests for reports on up to 20 routes in a single call.
  • GET requests may be easier to implement, especially if API calls only use a limited number of parameters and rely mostly on default settings.

Resource URI

The Route Reports endpoints are available via the following URI:

https://pcmiler.alk.com/apis/rest/v1.0/Service.svc/route/routeReports

Report Types

Each available report is described below, including the earliest PC*Miler version for which it is available. As noted, some reports are only available via a POST request and some require an add-on license to your API key.

You can get the available versions of PC*Miler via the /pcmversion endpoint.

Report Type Description POST Only? PC*Miler Versions
Mileage The Mileage Report provides the distance, time, and cost for each stop on a route. It can be set to retrieve distances in miles (default) or kilometers. N PCM18 and later
Detailed The Detailed Report provides a comprehensive report for each leg of the route. N PCM18 and later
CalcMiles The CalcMiles Report is used to calculate the distance of a route. It can be set to retrieve distances in miles (default) or kilometers. N PCM24 and later
Directions The Directions Report provides turn-by-turn directions for a route. N PCM18 and later
GeoTunnel The GeoTunnel Report provides a series of latitude/longitude points along a route. N PCM24 and later.
HoursOfService The Hours of Service Report calculates estimated departure and arrival times for all stops using detailed hours of service (HOS) information. It will also report additional stops that were inserted to maintain hours of service compliance. Y PCM31 and later
LeastCost The Comparison (LeastCost) Report provides a detailed comparison of the distance, time and costs associated with multiple possible routes between an origin and a destination. N PCM24 and later
Road The Road Report provides a distance breakdown by road category for each leg of the route. N PCM20 and later
State The State Report provides detailed mileage information for each state or country traveled through on the route. N PCM18 and later
TollDetail The Toll Detail Report provide toll information for routes in Europe Y PCM34 and later. Requires add-on toll data license.
RoutePath The Route Path Report retrieves a series of geographic coordinates that make up a route. The route is generated using the parameters below. N PCM34 and later. Requires add-on license for access to Trimble Maps JavaScript.
WeatherAlerts The Weather Alerts Report provides detailed descriptions of all alerts generated along the route. N PCM29 and Later

Getting Started

Parameter descriptions and sample report requests are available for both GET and POST requests. The individual pages about each report provide more specific information, including a section where you can make sample GET calls with your API key.

Our developer guide also provides code samples for requests in common programming languages, as well as “How to Guides” for common tasks with the APIs.

Handling Responses

Route reports responses include standard fields, and it is likely that not all of those fields will be necessary for your use case. As a result, we recommend that your implementation parse only the response fields that you need and ignore the rest.

For example, if you are calling a State report, you may only care about total miles in each state or country of travel. In that case, you would only need to consider the StCntry and Total fields in the StateReportLines object. The other fields can be ignored. 

 // This is an snippet from a state report response
 "StateReportLines": [
            {
                "StCntry": "NJ",
                "Total": "69.498",
                "Toll": "51.923",
                "Free": "17.575",
                "Ferry": "0.000",
                "Loaded": "69.498",
                "Empty": "0.000",
                "Tolls": "24.85",
                "Energy": "0.000"
            }
// Response continues
Last updated June 7, 2024.
API Endpoint:
AWS Azure
Contents