Route Reports

The /route/routeReports resource allows a user to retrieve report data for a route with the supplied parameters. 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), set the avoidFavors parameter to true and select your sets using afSetIDs or afSetNames.

Report Request Parameters

Data ElementDescriptionData TypeValue/Example
routeIdrouteId is used to identify the current report request.stringNewYorkToLA
stopsThe 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
vehTypeThe vehicle typeEnum0 - Truck (Default)
1 - LightTruck
2 - Auto
routeTypeThe desired routing algorithmEnum0 - Practical (Default)
1 - Shortest
2 - Fastest
hwyOnlyIndicates whether to use highways onlybooleanTrue
False (Default)
CustRdSpeedsIndicates whether to use custom road speeds.booleanTrue
False (Default)
avoidFavorsIndicates whether to use Route Modifiers (roads to avoid or favor) when generating a routingbooleanTrue
False (Default)
overrideClassA 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.
Enum0 - None (Default)
1 - FiftyThreeFoot
2 - NationalNetwork
3 - NationalNetwork and FiftyThreeFoot
distUnitsDistance Units.Enum0 - Miles (Default)
1 - Km
fuelUnitsFuel UnitsEnum0 - Gallons
1 - Liters
avoidTollsIndicates whether or not to avoid tollsbooleanTrue
False (Default)
inclFerryDistIndicates whether or not to include ferry distances in mileage calculations.booleanTrue (Default)
False
openBordersSets 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.

booleanTrue (Default)
False
restrOverridesIndicates whether or not to override truck restrictions pertaining to specific sizes and weights when generating a route.booleanTrue
False (Default)
hazMatIndicates the hazardous material type. See details in Glossary.Enum0 - None (Default)
1 - General
2 - Caustic
3 - Explosives
4 - Flammable
5 - Inhalants
6 - Radioactive
routeOptIndicates the method by which to optimize route stops.Enum0 - None (Default)
1 - ThruAll
2 - DestinationFixed
langLanguageEnum0 - ENUS (U.S. English)
1 - ENGB (Great Britain English)
2 - DE (German)
3 - FR (French)
4 - ES (Spanish)
5 - IT (Italian)
hubRoutingIndicates whether or not to enable hub routing. Hub Routing generates routes from a single starting place (origin) to multiple destinations.booleanTrue
False (Default)
vehProfileIndicates the vehicle routing profile which is a preset collection of dimensions and routing options.Enum0 - 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 (NA only)
8 - SmallSchoolBus (NA only)
vehDimUnitsVehicle dimension unitsEnum0 - English (Default)
1 - Metric
vehHeightThe height of the truck in feet and inches or meters depending on units.string13'6" or 4.1148
vehLengthThe length of the truck in feet and inches or meters depending on units.string53' or 16.1544
vehWidthThe width of the truck in feet and inches or meters depending on units.string96" or 2.4384
vehWeightThe weight of the truck in pounds or kilograms depending on units.string5000 or 2268
AxlesThe number of axles on the truckIntAcceptable values are 2 through 14 and the default value is 5
truckConfigThe truck style.Enum0 - None (Default)
1 - TwentyEightDoubleTrailer
2 - FortyStraightTruck
3 - FortyEightSemiTrailer
4 - FiftyThreeSemiTrailer
5 - FullSizeVan
6 - TwentySixStraightTruck
7 - ConventionalSchoolBus (NA only)
8 - SmallSchoolBus (NA only)
LCVIndicates whether the truck is a multi-trailer or longer combination vehicle.booleanTrue
False (Default)
refrigeratedIndicates 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)booleanTrue
False (Default)
fuelConsumptionThe amount of fuel a vehicle consumes in liters per 100 km. The format of this value is a floating point number. (For example, 0.5.) This value overrides our automatic calculation of fuel consumption. This parameter is used in State and Mileage reports to calculate "Tank-To-Wheel" (TTW) greenhouse gas (GHG) emissions. (Europe only)doubleDefault is 0
fuelTypeIndicates 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 FuelType0 - 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% biodeisel by vol)
7 - FuelType_Diesel_D7 (7% biodeisel by vol)
useTrafficIndicates whether or not use traffic which is only used in conjunction with fastest routing.booleanTrue
False (Default)
reportsIndicates the reports to retrieve. If an unlicensed report is specified, the request will result in a forbidden request, i.e. a 403 HTTP Response.EnumPossible values are a comma-separated list of the following:
0 - CalcMiles
1 - Mileage
2 - Directions
3 - State
4 - Detail
5 - Road
6 - Geotunnel
7 - TollDetail
inclTollDataIndicates whether or not toll data should be used.booleanTrue
False (Default)
fuelEconLoadThe fuel efficiency(distance units per fuel units) when loaded.doublevalue is decimal such as 11.9
fuelEconEmptyThe fuel efficiency(distance units per fuel units) when empty.doublevalue is decimal such as 11.9
costPerFuelUnitThe cost per fuel unit of fuel.doublevalue is decimal such as 4.15
costGHGThe cost of greenhouse gas in lbs per fuel unit.double
costMaintLoadThe maintenance cost per distance unit when loaded.double
costMaintEmptyThe maintenance cost per distance unit when empty.double
costTimeLoadThe time cost per mile when loaded.double
costTimeEmptyThe time cost per mile when empty.double
tollCurrencyThe toll currency US is default in NA and EUR is default in Europe.Enum0 - 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
exchangeRateThe 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.double
tollPlanIndicates the toll discount plan to consider when cacluating toll costs.stringDefault 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 reportdoubleAnything>= 0.1
hosEnabledIndicates whether or not to enable Hour of Service option.booleanTrue
False (Default)
hosRemDriveTimeUntilBreakThe available driving hours at origin before the driver needs to take a rest break.doubleThe format is in seconds.
hosRemDriveTimeThe available driving hours at origin until the end of work day.doubleThe format is in seconds.
hosRemOnDutyTimeThe available On-Duty hours available at origin until the end of work day.doubleThe format is in seconds.
hosRuleTypeThe hours of service rule to use.EnumValid values are 0 - USFed607LH, or 1 - USFed708LH for US Federal Long Haul rules.
hosRemCycleDutyTimeThe available Cycle time duty hours at origin until Cycle reset.doubleThe format is in seconds.
sideOfStreetAdherenceHow strict to be in order to avoid the destination being on the opposite side of the street.Enum0 - Off (Default)
1- Minimal
2 - Moderate
3 - Average
4 - Strict
5 - Adhere
6 - StronglyAdhere
governorSpeedLimitMaximum 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.doubleThe format is in mph or kph based on distUnits.
condenseDirsFlag indicating whether or not to condense the directions report.booleanTrue
False (Default)
elevLimitIndicates 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.Int3000
ferryDiscourageIndicates whether or not to discourage the use of ferries when creating the route. Default: falsebooleanTrue
False (Default)
estimatedTimeOptsEstimated time options allows setting of 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
stringExamples:
Depart|Monday|18:30
Arrive|2014-03-04T08:15:30|Local
useSitesIndicates whether the stops are on Sites or not and accordingly considers Site Gates in Routing. The default value is false.booleanTrue
False (Default)
afSetIDsThe 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.List of comma separated IDs24,133,204
afSetNamesThe 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
trlTypeThe type of trailer. This and all trailer related information below is used for Toll Detail reports in EuropeEnum1 - None (Default)
2 - Caravan
3 - Trailer
trlCountThe number of trailers and semi-trailers. Default is 0. For Toll Detail reports in Europe.Int0
trlMaxHtDo not use.string20'
trlMaxWtDo not use.Int30000
trlMaxAxlesThe maximum number of axles on the trailer. Acceptable values are 1 through 8. The default value is 1. For Toll Detail reports in Europe.Int1
isHybridIndicates whether the vehicle has a hybrid engine. Default is false. For Toll Detail reports in Europe.booleanTrue
False (Default)
emiTypeThe emission type of the engine. For Toll Detail reports in Europe.Enum3 - EuroI
4 - EuroII
5 - EuroIII
6 - EuroIV
7 - EuroV
8 - EuroVI
minPollIndicates whether vehicle is a minimum vehicle pollution. Default is false. For Toll Detail reports in Europe.booleanTrue
False (Default)
regionThe data region in which stop coordinates lie. Required to specify regions outside of NA.Enum0 - Unknown
1 - AF
2 - AS
3 - EU
4 - NA (Default)
5 - OC
6 - SA
7 - ME
dataVersionFor users licensed for multiple data versions or datasets.stringPCM18 - PCM33
PCM_EU
PCM_OC
PCM_SA
PCM_ME
PCM_AS
PCM_AF
PCM_WW (Worldwide)
PCM_GT (GeoTrack)
Current (Default)
stopCostsSpecifies the "Stop Costs" for each stop on the route. It is required to have an entry for each pair of coordinates in the stops query parameter.ComplexThe 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|5.0,5.0,true,false,true
breakIntervalThe elapsed time, in hours, of the trip before a break will be taken.Float3.5
breakLengthThe amount of time, in hours, a break will last.Float2.5
borderWaitThe amount of waiting time, in hours, at the border to add to the overall trip.Float1.5
remHrsOfSvcThe remaining hours of service at the start of the trip before the driver needs to take a break.Float4.5
afSetNamesApply the avoid/favor sets to the route. The format is comma separated names.String arrayHighways,TollRoads,Malls
tHoursWithSecondsIndicates whether to return THours with seconds precision for MileageReports.booleanPossible values are:
1 - True
2 - False (Default)
urgencyIndicates to retrieve weather alerts with an urgency attribute matching the listed values.EnumPossible values are:
0 - Immediate
1 - Expected
2 - Future
3 - Past
4 - Unknown
Default is none
severityIndicates to retrieve weather alerts with an severity attribute matching the listed values.EnumPossible values are:
0 - Extreme
1 - Severe
2 - Moderate
3 - Minor
4 - Unknown
Default is none
certaintyIndicates to retrieve weather alerts with an certainty attribute matching the listed values.EnumPossible values are:
0 - Observed
1 - Likely
2 - Possible
3 - Unlikely
4 - Unknown
Default is none
eventNamesLists the event names to match from the weather alerts when generating a report.String array
maintainHeadingIndicates whether or not to maintain heading at intermediate stops by avoid u-turns and instead leaving the stop in the same direction it entered it.booleanPossible values are:
1 - True
2 - False (Default is false except for School bus profiles)

POST Report Request Parameters

Alternatively, you can retrieve report data through a POST request in JSON format. The benefits of using a POST request are: in the Stops object, you can pass in either an Address object or Coords object. Also, you can add a label to each of the Stops. Hours of service options also benefit from a POST request. Additional hours of service options to fully support Cycle Time Gains, use of custom places for rest stops, and Canadian hours of service are only available through the POST version of the request. See examples in Post Route Reports and Post Derived Route Reports.