Route Reports

Contents

With our Route Reports APIs, you can retrieve report data for a route, customizing the route with a wide range of settings to fit your vehicles and business needs. For each route, a minimum of two stops and a report type are required. The report response returns a list of reports in JSON format. Below are descriptions of the parameters that can be used to generate reports.

Tip: To apply Route Modifiers (avoids and favors), select your sets using afSetIDs or afSetNames.

GET /route/routeReports

POST /route/routeReports

Resource URL

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

Report Request Parameters

(Some parameters have slightly different names for POST requests, as noted below. Read more about POST requests for route reports.)

Report Options

Data Element Description Data Type Value/Example
inclTollData
POST: UseTollData 		Indicates whether or not toll data should be used. 
boolean
True
False (Default)
IncludeRoadClass Available for POST report requests only Indicates whether or not to return RoadClass in Detailed and Directions reports. 
boolean
True
False (Default)
fuelUnits Fuel Units. 
Enum
0 - Gallons
1 - Liters
fuelEconLoad
POST: FuelEconomyLoaded 		The fuel efficiency (distance units per fuel units) when loaded. 
double
value is decimal such as 11.9
fuelEconEmpty
POST: FuelEconomyEmpty 		The fuel efficiency (distance units per fuel units) when empty. 
double
value is decimal such as 11.9
costPerFuelUnit
POST: PricePerFuelUnit 		The cost per fuel unit of fuel. 
double
value is decimal such as 4.15
truckConfig
POST: TruckStyle 		The truck style. 
Enum
 0 - None (Default)
1 - TwentyEightDoubleTrailer
2 - FortyStraightTruck
3 - FortyEightSemiTrailer
4 - FiftyThreeSemiTrailer
5 - FullSizeVan
6 - TwentySixStraightTruck
7 - ConventionalSchoolBus (North America only)
8 - SmallSchoolBus (North America only)
costGHG
POST: GreenHouseGas 		Greenhouse gas emissions in pounds or kilograms of carbon dioxide (CO2) per gallon. 
double
costMaintLoad
POST: OtherCostPerDistUnitLoaded 		The maintenance cost per distance unit when loaded. 
double
costMaintEmpty
POST: OtherCostPerDistanceUnitEmpty 		The maintenance cost per distance unit when empty. 
double
costTimeLoad
POST: CostTimeLoaded 		The labor time cost per distance units when the vehicle is loaded. The distance units are specified by the distUnits query parameter. The cost is currency agnostic. 
double
costTimeEmpty The labor time cost per distance units when the vehicle is empty. The distance units are specified by the distUnits query parameter. The cost is currency agnostic. 
double
breakInterval The elapsed time, in hours, of the trip before a break will be taken. 
Float
3.5
breakLength The amount of time, in hours, a break will last. 
Float
2.5
borderWait The amount of waiting time, in hours, at the border to add to the overall trip. 
Float
1.5
remHrsOfSvc
POST: RemainingHoursOfService 		The remaining hours of service at the start of the trip before the driver needs to take a break. 
Float
4.5
tollCurrency The toll currency. US is default in NA and EUR is default in Europe. 
Enum
0 - US
1 - CDN
For Toll Detail Report values below start at 2 (ALL) through 26 (UAH)
ALL - Albanian lek
AMD - Armenian dram
AZN - Azerbaijani manat
BAM - Bosnia and Herzegovina convertible mark
BGN - Bulgarian lev
BYR - Belarusian ruble
CHF - Swiss franc
CZK - Czech koruna
DKK - Danish krone
EUR - Euros
GBP - Pound sterling
GEL - Georgian lari
HRK - Croatian kuna
HUF - Hungarian forint
ISK - Icelandic króna: second króna
MDL - Moldovan leu
MKD - Second Macedonian denar
NOK - Norwegian krone
PLN - Polish złoty
RON - Fourth Romanian leu
RSD - Serbian dinar
RUB - Russian ruble
SEK - Swedish krona
TRY - Turkish lira
UAH - Ukrainian hryvnia
exchangeRate The exchange rate for changing currency listed in the tollCurrency query parameter to the cost units in which everything else is being calculated. The format of this value is a floating point number. (North America only, when exchanging between U.S. and Canadian dollars) 
double
tollPlan
POST: TollDiscount 		Indicates the toll discount plan to consider when calculating toll costs. 
string
 Default is none. Possible values are a comma-separated list of the following toll discount programs:
All, 407ETR Transponder, A25 Transponder, BreezeBy, C-Pass, Cruise Card, E-Pass, E-Pass Canada, EXpress Toll, EZ Tag, EZPass, EZPass-NJ, EZPass-WV, FAST LANE, FasTrak, GeauxPass, Good To Go, GO-PASS, I-Pass, I-Zoom, K-TAG, Laredo Trade Tag, LeeWay, MACPASS, NC Quick Pass, NEXPress, LeeWay, Palmetto Pass, Peach Pass, PikePass, Quickpass, Smart Tag, StraitPASS, SunPass, TollTag, TxTag, Wabash Pass
citeInt (Required when a geotunnel report is requested) The cite interval to be used when generating a geotunnel report. 
double
Anything>= 0.1
inclFerryDist
POST: IncludeFerryDistance 		Indicates whether or not to include ferry distances in mileage calculations. (North America only) 
boolean
True (Default)
False
CustRdSpeeds
POST: UseCustomRoadSpeeds 		Indicates whether to use custom road speeds. 
boolean
True
False (Default)
lang
POST: Language 		Language 
Enum
0 - ENUS (U.S. English)
1 - ENGB (Great Britain English)
2 - DE (German)
3 - FR (French)
4 - ES (Spanish)
5 - IT (Italian)
GET ONLY: estimatedTimeOpts Estimated time options allow you to set a departure or arrival time. This time will be reflected in mileage and detailed reports and can also affect routing with roads that have time-based restrictions.
Format:
Depart(Arrive)|[DayOfWeek]|[TimeOfDay]
or Depart(Arrive)|[SpecificDateTime]|[TimeZone]
Supported time zones can be found here. When setting a departure time, if the request is sent in the same time zone as the first stop (origin of the trip), within 15 minutes of the current time, the current time will be returned in the response. 
string
 Examples:
Depart|Monday|18:30
Arrive|2014-03-04T08:15:30|Local
POST: EstimatedTimeOptions Estimated time options allow you to set a departure or arrival time. This time will be reflected in mileage and detailed reports and can also affect routing with roads that have time-based restrictions. In a POST route reports call, EstimatedTimeOptions is an object with the following values:


ETAETD - Set to 0 for Arrival, 1 for Departure


DateOption - Set to 0 for Current time, 1 for Specific time, 2 for DayOfWeek.


DateAndTime - An object with the following values:


CalendarDate - A string value for the month, day and year in the following format mm/dd/yyyy


DayOfWeek - Day of the week, starting at 0-Sunday, 1-Monday, 2-Tuesday and so on...


TimeOfDay - A string value for the time in the format hh:mm AM/PM.


TimeZone - Set to 0 for local time. Other supported time zones can be found here. When setting a departure time, if the request is sent in the same time zone as the first stop (origin of the trip), within 15 minutes of the current time, the current time will be returned in the response. 

object
 Example:
"EstimatedTimeOptions": {
   "ETAETD": 1,
   "DateOption": 1,
   "DateAndTime": {
     "CalendarDate": "11/21/2021",
     "DayOfWeek": 0,
     "TimeOfDay": "6:00 AM",
     "TimeZone": 0
   }
useTraffic Indicates whether or not to use traffic data. Traffic data is only used to select the route path when the routing algorithm (routeType) is set to Fastest. For Practical and Shortest routes, traffic data is used to calculate ETAs and transit times. (Fastest routing is recommended for auto and van vehicle routing profiles only.) 
boolean
True
False (Default)

Stop Details and Route Options

Data Element Description Data Type Value/Example
routeId routeId is used to identify the current report request. 
string
NewYorkToLA
stops The coordinates that make up the stops of the route. Each stop is specified as a comma-separated pair of floating point numbers, representing longitude and latitude respectively. There must be at least two pairs of coordinates. List of comma-separated long/lat pairs, separated by semi-colons -76.123456,42.123456;-76.123126,42.123126
assetId The ID of the asset (device, vehicle or driver) associated with this request. 
string
abc1234
PlaceId The ID of the Place to be added as a stop on a route. If PlaceId is included, other location attributes included in the request are ignored, including an address or coordinates. The PlaceId for a location can be retrieved using our Places API. 
string
0xXBS0oPl3cEyBAGYYwU10_g
vehType
POST: VehicleType 		The vehicle type 
Enum
0 - Truck (Default)
1 - LightTruck
2 - Auto
routeType
POST: RoutingType 		The desired routing algorithm 
Enum
0 - Practical (Default)
1 - Shortest
2 - Fastest
hwyOnly
POST: HighwayOnly 		Indicates whether to use highways only 
boolean
True
False (Default)
overrideClass
POST: ClassOverrides 		A comma separated list of class overrides.
Note if if vehLength is larger than 48' (e.g. 48.1') and/or vehWidth is larger than 96" (e.g. 96.1"), then overrideClass is set to 3(National Network + FiftyThreeFoot) without an option to turn it off;
if vehLength is smaller than 48'and vehWidth is smaller than 96", then overrideClass is set to 0(None) by default. However, you can still provide overrideClass param to override it. 
Enum
0 - None (Default)
1 - FiftyThreeFoot
2 - NationalNetwork
3 - NationalNetwork and FiftyThreeFoot
distUnits
POST: DistanceUnits 		Distance Units. 
Enum
0 - Miles (Default)
1 - Km
avoidTolls
POST: TollDiscourage 		Indicates whether or not to avoid tolls. This parameter has been deprecated. Use tollRoads instead. 
boolean
True
False (Default)
tollRoads
POST: TollRoads 		Indicates whether or not to avoid toll roads when generating a route. If this parameter is specified, the value in avoidTolls will be ignored. If this parameter is null, the value in avoidTolls will be used. 
int
1 - Always Avoid
2 - Avoid if Possible
3 - Use
Default is null.
avoidCountry A comma-separated list of ISO2 codes for countries that should be avoided when generating a route. Default is an empty list. Available in PCM34 and higher. 
string
BE, LU
avoidState A comma-separated list of ISO2 codes for states that should be avoided when generating a route. Default is an empty list. North America only. Available in PCM34 and higher. 
string
DE, RI
favorCountry A comma-separated list of ISO2 codes for countries that should be favored when generating a route. Default is an empty list. For regions outside of North America. Available in PCM34 and higher. 
string
DE, FR
favorState A comma-separated list of ISO2 codes for states that should be favored when generating a route. Default is an empty list. North America only. Available in PCM34 and higher. 
string
PA, CT
openBorders
POST: BordersOpen 		Sets whether or not international borders are open to travel. Set to false to minimize the number of international border crossings, unless they are necessary to reach all of the stops on a route. For example, if all your stops are in the “lower 48” United States, the resulting route will stay in the United States even if the most practical or shortest route would normally involve some Canadian mileage.

The true option ignores international boundaries in generating the best route. 

boolean
True (Default)
False
restrOverrides
POST: OverrideRestrict 		Indicates whether or not to override truck restrictions pertaining to specific sizes and weights when generating a route. 
boolean
True
False (Default)
hazMat
POST: HazMatType 		Indicates the hazardous material type. See details in Glossary. 
Enum
0 - None (Default)
1 - General
2 - Caustic
3 - Explosives
4 - Flammable
5 - Inhalants
6 - Radioactive
7 - HarmfulToWater
8 - Tunnel
hazMatTypes An array of hazardous material types to apply when generating a route. See details in Glossary. 
Array of HazMatType
0 - None (Default)
1 - General
2 - Caustic
3 - Explosives
4 - Flammable
5 - Inhalants
6 - Radioactive
7 - HarmfulToWater
8 - Tunnel
tunnelCategory The tunnel category to apply when generating a route. (Europe only) 
Enum
0 - None (Default)
1 - TunnelBCDE
2 - TunnelCDE
3 - TunnelDE
4 - TunnelE
tunnelCategories An array of tunnel categories to apply when generating a route. (Europe only) 
Array of TunnelCategory
0 - None (Default)
1 - TunnelBCDE
2 - TunnelCDE
3 - TunnelDE
4 - TunnelE
routeOpt
POST: RouteOptimization 		Indicates the method by which to optimize route stops. 
Enum
0 - None (Default)
1 - ThruAll
2 - DestinationFixed
hubRouting Indicates whether or not to enable hub routing. Hub Routing generates routes from a single starting place (origin) to multiple destinations. 
boolean
True
False (Default)
vehProfile Indicates the vehicle routing profile which is a preset collection of dimensions and routing options. 
Enum
 0 - None (Default, which is equivalent to the 48-foot semitrailer profile)
1 - TwentyEightDoubleTrailer
2 - FortyStraightTruck
3 - FortyEightSemiTrailer
4 - FiftyThreeSemiTrailer
5 - FullSizeVan
6 - TwentySixStraightTruck
7 - ConventionalSchoolBus (North America only)
8 - SmallSchoolBus (North America only)
vehDimUnits Vehicle dimension units 
Enum
0 - English (Default)
1 - Metric
vehHeight The height of the truck in feet and inches or meters depending on units. 
string
13'6" or 4.1148
vehLength The length of the truck in feet and inches or meters depending on units. 
string
53' or 16.1544
vehWidth The width of the truck in feet and inches or meters depending on units. 
string
96" or 2.4384
vehWeight The weight of the truck in pounds or kilograms depending on units. 
string
5000 or 2268
Axles The number of axles on the truck 
Int
Acceptable values are 2 through 14 and the default value is 5
LCV Indicates whether the truck is a multi-trailer or longer combination vehicle. 
boolean
True
False (Default)
refrigerated Indicates whether the truck trailer is refrigerated. This parameter is used in State and Mileage reports to calculate "Tank-To-Wheel" (TTW) greenhouse gas (GHG) emissions. (Europe only) 
boolean
True
False (Default)
fuelConsumption The amount of fuel a vehicle consumes in liters per 100 km. The format of this value is a floating point number (for example, 23.5).

This individual value overrides the default fuel consumption values which are used when this parameter is set to 0. The default values for fuel consumption are based on UK DEFRA 2018. It provides average fuel consumption by weight class and vehicle setup, which are calculated automatically based on the dimension settings in the vehicle routing profile.

This parameter is used in State and Mileage reports to calculate "Tank-To-Wheel" (TTW) greenhouse gas (GHG) emissions. It is not used for fuel cost calculations. (Europe only) 

double
Default is 0
fuelType Indicates the type of fuel used. This parameter is used in State and Mileage reports to calculate "Tank-To-Wheel" (TTW) greenhouse gas (GHG) emissions. Default is Diesel. (Europe only) 
Enum
FuelType 		0 - FuelType_Petrol
1 - FuelType_Petrol_E5 (5% ethanol by vol)
2 - FuelType_Petrol_E10 (10% ethanol by vol)
3 - FuelType_Ethanol
4 - FuelType_Diesel (Default)
5 - FuelType_Biodiesel
6 - FuelType_Diesel_D5 (5% biodiesel by vol)
7 - FuelType_Diesel_D7 (7% biodiesel by vol)
reports Indicates the reports to retrieve. If an unlicensed report is specified, the request will result in a forbidden request, i.e. a 403 HTTP Response. 
Enum
Possible values are a comma-separated list of the following:
Mileage
Detail
CalcMiles
Directions
Geotunnel
LeastCost
Road
State
WeatherAlerts
TollDetail (Europe only)
RoutePath (Requires Maps License)
hosEnabled Indicates whether or not to enable Hour of Service option. 
boolean
True
False (Default)
hosRemDriveTimeUntilBreak The available driving hours at origin before the driver needs to take a rest break. 
double
The format is in seconds.
hosRemDriveTime The available driving hours at origin until the end of work day. 
double
The format is in seconds.
hosRemOnDutyTime The available On-Duty hours available at origin until the end of work day. 
double
The format is in seconds.
hosRuleType The hours of service rule to use. 
Enum
Valid values are 0 - USFed607LH, or 1 - USFed708LH for US Federal Long Haul rules.
hosRemCycleDutyTime The available Cycle time duty hours at origin until Cycle reset. 
double
The format is in seconds.
sideOfStreetAdherence How strict to be in order to avoid the destination being on the opposite side of the street. 
Enum
 0 - Off (Default)
1- Minimal
2 - Moderate
3 - Average
4 - Strict
5 - Adhere
6 - StronglyAdhere
useCrossStreetTurnAvoidance When set to true, it reduces the chances the route generated includes turns that go across the street in front of oncoming traffic. These turns will still be included if there is no reasonable alternative. (For auto and van Vehicle Routing Profiles only) 
boolean
True
False (Default).
governorSpeedLimit Maximum average road speed to use in route calculations that overrides all other road speeds when they are above this value. Default is disabled and valid value is between 1 and 100 mph. 
double
The format is in mph or kph based on distUnits.
condenseDirs Flag indicating whether or not to condense the directions report. 
boolean
True
False (Default)
elevLimit Indicates the elevation limit when generating a route. Default value is null.Elevation unit can be either meters or feet is determined by the distUnits parameter. Miles = feet, Kilometers = meters. Available for dataversions Current, PCM_NA, PCM29 and above. Limit will be ignored if: Routing is deemed impractical with the limit, or a stop is located at an elevation higher than the limit. (North America only) 
Int
3000
ferryDiscourage Indicates whether or not to discourage the use of ferries when creating the route. 
boolean
True
False (Default)
useSites
POST: UseSites 		Indicates whether the stops are on Sites or not and accordingly considers Site Gates in Routing. The default value is false. 
boolean
True
False (Default)
afSetIDs
POST: AFSetIDs 		The IDs of the Route Modifier (avoid/favor) sets that should be applied to the route. The format is comma separated IDs. The IDs are integers. Set to [-1] to select all sets. List of comma separated IDs 24,133,204
afSetNames The names of the Route Modifier (avoid/favor) sets that should be applied to the route. Default is an empty set. List of comma separated names. Highways,TollRoads,Malls
trlType The type of trailer. This and all trailer related information below is used for Toll Detail reports in Europe 
Enum
 1 - None (Default)
2 - Caravan
3 - Trailer
trlCount The number of trailers and semi-trailers. Default is 0. For Toll Detail reports in Europe. 
Int
0
trlMaxHt Do not use. 
string
20'
trlMaxWt Do not use. 
Int
30000
trlMaxAxles The maximum number of axles on the trailer. Acceptable values are 1 through 8. The default value is 1. For Toll Detail reports in Europe. 
Int
1
isHybrid Indicates whether the vehicle has a hybrid engine. Default is false. For Toll Detail reports in Europe. 
boolean
True
False (Default)
emiType The emission type of the engine. For Toll Detail reports in Europe. 
Enum
2 - Euro0
3 - EuroI
4 - EuroII
5 - EuroIII
6 - EuroIV
7 - EuroV
8 - EuroVI (Default)
9 - EuroEEV
minPoll Indicates whether vehicle is a minimum vehicle pollution. Default is false. For Toll Detail reports in Europe. 
boolean
True
False (Default)
POST: RestrictionZones (Europe Only) An object that sets whether the route can pass through a CongestionZone, a LowEmissionZone, or an UltraLowEmissionZone. For each type of zone, three settings are available:

Allow the route to pass through the zone (Default).

Avoid the zone and route around it.

Warn that the route enters the zone. 

boolean
"RestrictionZones": {
 "CongestionZone": Avoid,
 "LowEmissionZone": Allow,
 "UltraLowEmissionZone": Warn
}
region The data region in which stop coordinates lie. Required to specify regions outside of NA. 
Enum
 0 - Unknown
1 - AF
2 - AS
3 - EU
4 - NA (Default)
5 - OC
6 - SA
7 - ME
dataVersion For users licensed for multiple data versions or datasets.
Read more about setting the dataVersion. 
string
PCM18 - PCM35 (Detailed, Directions, Mileage and State reports are available for versions 18 and higher. Other reports were added in later versions. Please see each individual report's documentation page for details.)
PCM_EU
PCM_OC
PCM_SA
PCM_ME
PCM_AS
PCM_AF
PCM_WW (Worldwide)
PCM_GT (GeoTrack)
Current (Default)
stopCosts
POST: CostOfStop 		Specifies a flat monetary cost for each stop on the route, which is added to the total cost of the trip. It is required to have an entry for each pair of coordinates in the stops query parameter. 
Complex
The format is a list delimited by a vertical bar (|) of StopCosts for each stop that is supplied in the stops query parameter, respectively.
It has the following format:
CostOfStop ',' HoursPerStop ',' Loaded' ,' OnDuty' ,' UseOrigin
CostOfStop - Float
HoursPerStop - Float
Loaded - boolean
OnDuty - boolean
UseOrigin - boolean
Example: 0.0,0.0,true,true,true|1.0,0.2,false,true,true
ID The user created stop ID. 
String
Stop_1
afSetNames Apply the avoid/favor sets to the route. The format is comma separated names. 
String array
Highways,TollRoads,Malls
tHoursWithSeconds Indicates whether to return THours with seconds precision for MileageReports. 
boolean
Possible values are:
1 - True
2 - False (Default)
urgency Indicates to retrieve weather alerts with an urgency attribute matching the listed values. 
Enum
Possible values are:
0 - Immediate
1 - Expected
2 - Future
3 - Past
4 - Unknown
Default is none
severity Indicates to retrieve weather alerts with an severity attribute matching the listed values. 
Enum
Possible values are:
0 - Extreme
1 - Severe
2 - Moderate
3 - Minor
4 - Unknown
Default is none
certainty Indicates to retrieve weather alerts with an certainty attribute matching the listed values. 
Enum
Possible values are:
0 - Observed
1 - Likely
2 - Possible
3 - Unlikely
4 - Unknown
Default is none
eventNames Lists the event names to match from the weather alerts when generating a report. 
String array
Last updated September 8, 2021.