Skip to main content

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.

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 PCM36). 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

ParameterDescriptionRequired?
ReportTypesAn 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"
        }
      ],
ParameterDescriptionRequired?
StopsAn 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”
            },
ParameterDescriptionRequired?
RegionThe 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.

ParameterDescriptionRequired?
DistanceUnitsSet “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
	          }
ParameterDescriptionRequired?
RoutingTypeThe 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,
	          }
ParameterDescriptionRequired?
TollRoadsIndicates 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,
	          }
ParameterDescriptionRequired?
HazMatTypesAn 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],
	          }
ParameterDescriptionRequired?
TunnelCategoriesAn 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 August 4, 2022.
Contents