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 URL

The Route Reports endpoints are available via the following URL:

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 TypeDescriptionPOST Only?PC*MILER Versions
MileageThe 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.NPCM18 and later
DetailedThe Detailed Report provides a comprehensive report for each leg of the route.NPCM18 and later
CalcMilesThe CalcMiles Report is used to calculate the distance of a route. It can be set to retrieve distances in miles (default) or kilometers.NPCM24 and later
DirectionsThe Directions Report provides turn-by-turn directions for a route.NPCM18 and later
GeoTunnelThe GeoTunnel Report provides a series of latitude/longitude points along a route.NPCM24 and later.
HoursOfServiceThe 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.YPCM31 and later
LeastCostThe Comparison (LeastCost) Report provides a detailed comparison of the distance, time and costs associated with multiple possible routes between an origin and a destination.NPCM24 and later
RoadThe Road Report provides a distance breakdown by road category for each leg of the route.NPCM20 and later
StateThe State Report provides detailed mileage information for each state or country traveled through on the route.NPCM18 and later
TollDetailThe Toll Detail Report provide toll information for routes in EuropeYPCM34 and later. Requires add-on toll data license.
RoutePathThe Route Path Report retrieves a series of geographic coordinates that make up a route. The route is generated using the parameters below.NPCM34 and later. Requires add-on license for access to Trimble Maps JavaScript.
WeatherAlertsThe Weather Alerts Report provides detailed descriptions of all alerts generated along the route.NPCM29 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 March 14, 2023.
Contents