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 higher.
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
… throughPCM36
). 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.
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:
|
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:
|
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:
|
Example
"Options": {
"HazMatTypes": [1, 2],
}
Parameter | Description | Required? |
---|---|---|
TunnelCategories | An array of tunnel categories to apply when generating a route. (Europe only) Options are:
|
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
}
]