RESTful APIs

Mileage for rating

Contents

Shippers and carriers often use Trimble Maps Routing APIs to calculate distances between cities or postal/ZIP codes for freight rating and billing. That’s because the APIs use the same routing algorithm as PC*Miler, which has been the transportation industry’s standard for generating miles for trucking lanes for more than three decades.

With our Route Reports API, calculating PC*Miler distances between cities or postal/ZIP codes can be as straightforward as entering your locations—the origin, the destination, and any stops in between—and setting a handful of additional parameters. What’s more, you can calculate mileage for any version of PC*Miler, 18 and Later.

Place
The Route Reports API can generate the same mileage report as our installed PC*Miler applications (shown above).

How to generate mileage

We recommend making a POST method request for a Mileage Report. POST requests allow you to enter locations as postal/ZIP codes or as cities—the standard ways to generate PC*Miler distances.

All API calls require an API key for authentication. You can immediately request a trial API key by clicking on GET AN API KEY at the top of this screen.

Step 1: Choose a dataVersion

The Route Reports service is available via the following URL:

https://pcmiler.alk.com/apis/rest/v1.0/service.svc/route/routeReports?dataVersion={dataVersion}

dataVersion specifies the version of PC*Miler that you want to use to calculate distances. In the case of rating, choose:

  • A numbered PC*Miler version (PCM18, PCM19 … through PCM37). Shipping contracts often specify which version of PC*Miler should be used for calculating distances. Numbered versions are available for North America if you have a premium web services API key, or for PC*Miler Worldwide if you have a global premium API key.

Step 2: Set the parameters

The tables below show the parameters that should be set in the body of your POST request for a Mileage Report. There are many additional parameters available, but the values below are all that are necessary for a request for mileage for rating. When no additional parameters are set, the routes used to calculate mileage are based on default vehicle dimensions for each region.

These settings help ensure that distances you generate match the PC*Miler “practical” miles you or your customers may be calculating with our installed PC*Miler applications.

Required parameters

Parameter Description Required?
ReportTypes An array of the reports being requested. For rating, only the Mileage report needs to be requested. Yes

Example 

"ReportTypes": [
        {
          "__type": "MileageReport:http://pcmiler.alk.com/APIs/v1.0"
        }
      ],
Parameter Description Required?
Stops An array of address objects for the stops on a route. For rating, enter the stops as a ZIP/postal code or as a city, state, which uses the PC*Miler designated city center. Yes

Examples 

//Enter a ZIP
"Stops": [
         {
            "Address":{
                "Zip": “08540”
            },

//Enter a city, state
"Stops": [
         {
            "Address":{
                "City": “Princeton”,
                "State": “NJ”
            },
Parameter Description Required?
Region The area of the world where mileage is being requested. Possible values are:
  • 0 - Unknown
  • 1 - AF (Africa)
  • 2 - AS (Asia)
  • 3 - EU (Europe)
  • 4 - NA (North America) (Default)
  • 5 - OC (Oceania)
  • 6 - SA (South America)
  • 7 - ME (Middle East)
Yes, for regions outside of North America

Example 

"Stops": [
         {
            "Address":{
                "Zip": "13090"
            },
            "Region": 4
          },

Optional parameters

The routing Options object has dozens of settings available. However, generating mileage for rating uses the default values for all of them. The settings below are optional if you want to customize your results.

Parameter Description Required?
DistanceUnits Set “DistanceUnits”: 1 to generate distances in kilometers instead of miles. No, only needs to be set if you want to generate distances in kilometers instead of miles.

Example 

      "Options": {
	          "DistanceUnits": 1
	          }
Parameter Description Required?
RoutingType The type of route you want to calculate. Practical (0) is the default, and Shortest (1) is the only other setting recommended for trucks. No, default is Practical.

Example 

      "Options": {
	          "RoutingType": 1,
	          }
Parameter Description Required?
TollRoads Indicates whether or not to avoid toll roads when generating a route. By Default, this parameter is null. It can be set to:
  • 1 - Always Avoid
  • 2 - Avoid if Possible
  • 3 - Use
No

Example 

      "Options": {
	          "TollRoads": 1,
	          }
Parameter Description Required?
HazMatTypes An array of hazardous material types to apply when generating a route. Read more about hazmat routing.
Options are:
  • 0 - None (Default)
  • 1 - General
  • 2 - Caustic
  • 3 - Explosives
  • 4 - Flammable
  • 5 - Inhalants
  • 6 - Radioactive
  • 7 - HarmfulToWater
  • 8 - Tunnel
No

Example 

"Options": {
	          "HazMatTypes": [1, 2],
	          }
Parameter Description Required?
TunnelCategories An array of tunnel categories to apply when generating a route. (Europe only) Options are:
  • 0 - None (Default)
  • 1 - TunnelBCDE
  • 2 - TunnelCDE
  • 3 - TunnelDE
  • 4 - TunnelE
No

Example 

"Options": {
	          "TunnelCategories": [1, 2]
	          }

Step 3: Call for the report

POST https://pcmiler.alk.com/apis/rest/v1.0/Service.svc/route/routeReports?dataversion=PCM35
Authorization: YOURAPIKEY (You can click on GET AN API KEY at the top of this page to get a free, trial API key.)

Sample request body - North America 

{
  "ReportRoutes": [
    {
      "ReportTypes": [
        {
          "__type": "MileageReportType:http://pcmiler.alk.com/APIs/v1.0"
        }
      ],
      "Stops": [
        {
          "Address": {
            "Zip": "13090"
          },
          "Region": "4"
        },
        {
          "Address": {
            "Zip": "90210"
          },
          "Region": "4"
        }
      ],
      "Options": {
        "DistanceUnits": "0"
      }
    }
  ]
}

Sample response - North America 

[
  {
    "__type": "MileageReport:http://pcmiler.alk.com/APIs/v1.0",
    "ReportLines": [
      {
        "Stop": {
          "TimeZone": "EDT",
          "Address": {
            "StreetAddress": "",
            "City": "Liverpool",
            "State": "NY",
            "Zip": "13090",
            "County": "Onondaga",
            "Country": "United States",
            "SPLC": null,
            "CountryPostalFilter": 0,
            "AbbreviationFormat": 0,
            "StateName": "New York",
            "StateAbbreviation": "NY",
            "CountryAbbreviation": "US"
          },
          "Errors": [],
          "Coords": {
            "Lat": "43.148651",
            "Lon": "-76.222581"
          },
          "SpeedLimitInfo": null,
          "Region": 4,
          "ConfidenceLevel": "Exact",
          "Label": "",
          "DistanceFromRoad": null,
          "PlaceName": "",
          "CrossStreet": null
        },
        "LMiles": "0.000",
        "TMiles": "0.000",
        "LCostMile": "0.00",
        "TCostMile": "0.00",
        "LHours": "0:00",
        "THours": "0:00",
        "LTolls": "0.00",
        "TTolls": "0.00",
        "LEstghg": "0.0",
        "TEstghg": "0.0",
        "EtaEtd": null
      },
      {
        "Stop": {
          "TimeZone": "PDT",
          "Address": {
            "StreetAddress": "",
            "City": "Beverly Hills",
            "State": "CA",
            "Zip": "90210",
            "County": "Los Angeles",
            "Country": "United States",
            "SPLC": null,
            "CountryPostalFilter": 0,
            "AbbreviationFormat": 0,
            "StateName": "California",
            "StateAbbreviation": "CA",
            "CountryAbbreviation": "US"
          },
          "Errors": [],
          "Coords": {
            "Lat": "34.079799",
            "Lon": "-118.412935"
          },
          "SpeedLimitInfo": null,
          "Region": 4,
          "ConfidenceLevel": "Exact",
          "Label": "",
          "DistanceFromRoad": null,
          "PlaceName": "",
          "CrossStreet": null
        },
        "LMiles": "2683.483", //The “leg” mileage between those two stop locations.
        "TMiles": "2683.483", //The total mileage for the trip. (Would be different from leg miles if your request had more than two stops.)
        "LCostMile": "3758.23",
        "TCostMile": "3758.23",
        "LHours": "46:12",
        "THours": "46:12",
        "LTolls": "153.30",
        "TTolls": "153.30",
        "LEstghg": "8971.6",
        "TEstghg": "8971.6",
        "EtaEtd": null
      }
    ],
    "RouteID": null,
    "TrafficDataUsed": false
  }
]

Sample request body - Europe

POST https://pcmiler.alk.com/apis/rest/v1.0/Service.svc/route/routeReports?dataversion=PCM35
Authorization: YOURAPIKEY (You can click on GET AN API KEY at the top of this page to get a free, trial API key.) 

{
  "ReportRoutes": [
    {
      "ReportTypes": [
        {
          "__type": "MileageReportType:http://pcmiler.alk.com/APIs/v1.0"
        }
      ],
      "Stops": [
        {
          "Address": {
            "City": "London",
            "State": "UK"
          },
          "Region": "3"
        },
        {
          "Address": {
            "City": "Liverpool",
            "State": "UK"
          },
          "Region": "3"
        }
      ],
      "Options": {
        "DistanceUnits": "0"
      }
    }
  ]
}

Sample response - Europe 

[
  {
    "__type": "MileageReport:http://pcmiler.alk.com/APIs/v1.0",
    "ReportLines": [
      {
        "Stop": {
          "TimeZone": "+1:00",
          "Address": {
            "StreetAddress": "",
            "City": "London",
            "State": "UK",
            "Zip": "SW1A 2",
            "County": "London",
            "Country": "United Kingdom",
            "SPLC": null,
            "CountryPostalFilter": 0,
            "AbbreviationFormat": 0,
            "StateName": "England",
            "StateAbbreviation": "ENG",
            "CountryAbbreviation": "UK"
          },
          "Errors": [],
          "Coords": {
            "Lat": "51.506420",
            "Lon": "-0.127210"
          },
          "SpeedLimitInfo": null,
          "Region": 3,
          "ConfidenceLevel": "Exact",
          "Label": "",
          "DistanceFromRoad": null,
          "PlaceName": "",
          "CrossStreet": null
        },
        "LMiles": "0.000",
        "TMiles": "0.000",
        "LCostMile": "0.00",
        "TCostMile": "0.00",
        "LHours": "0:00",
        "THours": "0:00",
        "LTolls": "0.00",
        "TTolls": "0.00",
        "LEstghg": "0.0",
        "TEstghg": "0.0",
        "EtaEtd": null
      },
      {
        "Stop": {
          "TimeZone": "+1:00",
          "Address": {
            "StreetAddress": "",
            "City": "Liverpool",
            "State": "UK",
            "Zip": "L3 8",
            "County": "Merseyside",
            "Country": "United Kingdom",
            "SPLC": null,
            "CountryPostalFilter": 0,
            "AbbreviationFormat": 0,
            "StateName": "England",
            "StateAbbreviation": "ENG",
            "CountryAbbreviation": "UK"
          },
          "Errors": [],
          "Coords": {
            "Lat": "53.410050",
            "Lon": "-2.978390"
          },
          "SpeedLimitInfo": null,
          "Region": 3,
          "ConfidenceLevel": "Exact",
          "Label": "",
          "DistanceFromRoad": null,
          "PlaceName": "",
          "CrossStreet": null
        },
        "LMiles": "210.653", //The “leg” mileage between those two stop locations.
        "TMiles": "210.653", //The total mileage for the trip. (Would be different from leg miles if your request had more than two stops.)
        "LCostMile": "328.77",
        "TCostMile": "328.77",
        "LHours": "4:13",
        "THours": "4:13",
        "LTolls": "0.00",
        "TTolls": "0.00",
        "LEstghg": "323.4",
        "TEstghg": "323.4",
        "EtaEtd": null
      }
    ],
    "RouteID": null,
    "TrafficDataUsed": false
  }
]
Last updated July 2, 2024.
API Endpoint:
AWS Azure
Contents