Route Reports (GET method)

Contents

With our Route Reports API, you can create a route and retrieve a wide range of information about it—everything from PC*MILER practical miles and turn-by-turn directions to trip costs and a detailed route path. Each route can be customized with a wide range of settings to fit your vehicles and business needs.

For each route report request, a minimum of two stops (origin and destination) and one or more requested reports are required. The report response returns a list of reports in JSON format.

GET /route/routeReports

Resource URL

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

Report Request Parameters

Below are descriptions of the parameters that can be used to generate route reports.

The only two required parameters are stops and reports. If no other parameters are entered, routes will be calculated based on default vehicle dimensions and default settings.

Stop Details

These parameters identify the stops in a route.

Data Element	Description	Data Type	Value/Example
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 in the request are ignored, including an address or coordinates. The `PlaceId` for a location can be retrieved using our Single Search API. Available in `dataVersion` PCM35 and higher.	string	0xXBS0oPl3cEyBAGYYwU10_g
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
ID	The user created stop ID.	String	Stop_1

Route Options

These parameters help customize the way the routing algorithm generates a route.

Data Element	Description	Data Type	Value/Example
profileName	The name of the vehicle routing profile to be used in calculations. A vehicle routing profile is a preset collection of vehicle dimensions and other routing options that ensure the routing algorithm knows the type of vehicle being driven so it can generate a safe, efficient, and legal route.	String	Default is null. Read more about selecting a vehicle routing profile.
useTraffic	Indicates whether or not to use traffic data. When set to true, the routing algorithm will consider traffic closures when selecting the route and use historical traffic patterns to calculate the trip’s ETA and travel time. If set to true, and the trip’s departure time is also set to within 15 minutes of the current time, real-time traffic data will be used for the first 15 miles and historical traffic patterns will be used for the remainder of the route. (By default, `useTraffic` is false, and ETA and travel time are computed using Trimble Maps’s average road speeds by road class.) With the exception of road closures, traffic data is only used to select the route path a vehicle will take when the routing algorithm (`routeType`) is set to `Fastest`. (Fastest routing is not recommended for trucks—autos and vans only.)	boolean	True False (Default)
vehType	Restricts the route to roads that are accessible by the selected vehicle type.	Enum	0 - Truck (Default) 1 - LightTruck 2 - Auto 3 - Midsize Truck 4 - School Bus 5 - RV/Caravan
routeType	The type of route you want to calculate.	Enum	0 - Practical (Default) 1 - Shortest 2 - Fastest
hwyOnly	Indicates whether to use highways only for routing. This setting is intended only for generating distances between cities or postal codes. The default is false for GET calls to route reports, which means local streets may be used in routing. For POST calls, the default is true.	boolean	True (Default for POST calls) False (Default for GET calls)
overrideClass	A comma separated list of class overrides. This allows you to select whether a truck with a 48' or shorter trailer should still adhere to routing for larger (53') trucks along the National Network. (U.S. Only) Note that 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	Sets whether to use miles or kilometers in distance and speed measurements.	Enum	0 - Miles (Default) 1 - Km
avoidTolls	Indicates whether or not to avoid tolls. This parameter has been deprecated. Use `tollRoads` instead.	boolean	True False (Default)
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. Available in `dataVersion` PCM34 and higher. Use `avoidTolls` for older versions.	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.*	A list of comma-separated countries. list of strings	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. *This parameter is for North America only. Available in PCM34 and higher.*	A list of comma-separated states. list of strings	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. *This parameter is for regions outside of North America. Available in PCM34 and higher.*	A list of comma-separated countries. list of strings	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. *This parameter is for North America only. Available in PCM34 and higher.*	A list of comma-separated states. list of strings	PA, CT
openBorders	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	Indicates whether or not to override truck restrictions pertaining to specific sizes and weights when generating a route.	boolean	True False (Default)
hazMat	Indicates the hazardous material type. Read more about hazmat routing.	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. Read more about hazmat routing.	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	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)
vehDimUnits	Vehicle dimension units	Enum	0 - English (Default) 1 - Metric
vehHeight	The height of the truck in feet and inches or meters depending on `vehDimUnits`. Valid range is between 5' and 15' in North America, or between 2 and 5 meters in Europe.	string	Read more about setting vehicle dimensions.
vehLength	The length of a straight truck/van or combined vehicle’s trailer in feet and inches or meters depending on `vehDimUnits`. You do not need to include the tractor's length in this value for a tractor/trailer. If you have tandem trailers that don't articulate (rigid connection) then it would be the combined length of the trailers. More than just a legal setting, `vehLength` is used to calculate turning radius using the maximum straight length to see if the driver can make the turn. Valid range is between 8' and 70' in North America, or between 5 and 25 meters in Europe.	string	Read more about setting vehicle dimensions.
vehWidth	The width of the truck in inches or meters depending on `vehDimUnits`. Valid range is between 60" and 102" in North America, or between 2 and 3 meters in Europe.	string	Read more about setting vehicle dimensions.
vehWeight	The weight of the truck in pounds or kilograms depending on `vehDimUnits`. Valid range is between 1500 and 156470 lbs in North America, or between 680.39 and 60000 kgs in Europe.	string	Read more about setting vehicle dimensions.
axles	The number of axles on the truck	Int	Acceptable values are 2 through 14 and the default value is 5
trkMaxWeightPerAxleGroup	The maximum weight per axle group in pounds or kilograms depending on `vehDimUnits`. Acceptable values are 800 to 45,000 pounds in North America and 1 tonne to 20 tonnes in Europe.	double	Read more about setting vehicle dimensions.
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)
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 USFed607LH - 0, USFed708LH - 1, CanadaCycle1 - 2, CanadaCycle2 - 3, California808 - 4, Texas707 - 5, USShortHaul - 6, Europe - 7
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 `dataVersion` Current, PCM_NA, and PCM29 and higher. 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	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	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
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.	Int	1
maintainHeading	When this option is set, a vehicle will attempt to avoid u-turns at intermediate stops and instead leave the stop in the same direction it entered it. When using the school bus vehicle profiles, this option will be automatically set to true if not supplied.	boolean	True False (Default)
profileId	The ID of the vehicle routing profile to be used in calculations. A vehicle routing profile is a preset collection of vehicle dimensions and other routing options that ensure the routing algorithm knows the type of vehicle being driven so it can generate a safe, efficient, and legal route.	Int	Default is null

Report Options

These parameters help customize the information returned in reports.

Data Element	Description	Data Type	Value/Example
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 RoutePath (Requires Maps License)
estimatedTimeOpts	Estimated time options allow you to select when you would like to depart from your origin or arrive at your destination. You must select one of three options for your arrival or departure: The current time and day; a day of the week and time of day; or a specific date and time of day. 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
inclTollData	Indicates whether or not toll data should be used.	boolean	True False (Default)
fuelUnits	Fuel Units.	Enum	0 - Gallons 1 - Liters
fuelEconLoad	The fuel efficiency (distance units per fuel units) when loaded. See default values for trip costs.	double	A decimal value such as 11.9
fuelEconEmpty	The fuel efficiency (distance units per fuel units) when empty. See default values for trip costs.	double	A decimal value such as 11.9
costPerFuelUnit	The cost per fuel unit of fuel. See default values for trip costs.	double	A decimal value such as 4.75
costGHG	Greenhouse gas emissions in pounds or kilograms of carbon dioxide (CO2) per gallon. See default values for trip costs.	double	A decimal value such as 22.4
costMaintLoad	The maintenance cost per distance unit when loaded. See default values for trip costs.	double	A decimal value such as .21
costMaintEmpty	The maintenance cost per distance unit when empty. See default values for trip costs.	double	A decimal value such as .21
costTimeLoad	The labor cost per hour when the vehicle is loaded. See default values for trip costs.	double	A decimal value such as 45.2
costTimeEmpty	The labor cost per hour when the vehicle is empty. See default values for trip costs.	double	A decimal value such as 45.2
stopCosts	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`
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	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	Indicates the toll discount plan to consider when calculating toll costs.	string	Default is none. Possible values are a comma-separated list of toll discount programs.
citeInt (Required when a geotunnel report is requested)	The cite interval to be used when generating a geotunnel report.	double	Anything>= 0.1
inclFerryDist	Indicates whether or not to include ferry distances in mileage calculations. (North America only)	boolean	True (Default) False
lang	The language to use in reports.	Enum	0 - ENUS (U.S. English) 1 - ENGB (Great Britain English) 2 - DE (German) 3 - FR (French) 4 - ES (Spanish) 5 - IT (Italian)
dataVersion	For users licensed for multiple data versions or datasets. Read more about setting the `dataVersion`. Note: In `PCM25` and earlier, latitude/longitude coordinates are returned as whole numbers. (i.e. "Lat": "40958188", "Lon": "-75163244") In `PCM26` and later, coordinates include the decimal point. (i.e. "Lat": "40.361617", "Lon": "-74.601469")	string	PCM18-PCMXX ("XX" is the most current version of PCMILER. Call /pcmversion to see the latest versions available.) (Detailed, Directions, Mileage and State reports are available for `dataVersion` PCM18 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)
routeId	routeId is used to identify the current report request.	string	NewYorkToLA
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

Report Types

Report Type	Description	PC*MILER Versions
`Mileage`	The Mileage Report provides the distance, time, and cost for each stop on a route. It can be set to retrieve distances in miles (default) or kilometers.	PCM18 and later
`Detailed`	The Detailed Report provides a comprehensive report for each leg of the route.	PCM18 and later
`CalcMiles`	The CalcMiles Report is used to calculate the distance of a route. It can be set to retrieve distances in miles (default) or kilometers.	PCM24 and later
`Directions`	The Directions Report provides turn-by-turn directions for a route.	PCM18 and later
`GeoTunnel`	The GeoTunnel Report provides a series of latitude/longitude points along a route.	PCM24 and later
`LeastCost`	The Comparison (LeastCost) Report provides a detailed comparison of the distance, time and costs associated with multiple possible routes between an origin and a destination.	PCM24 and later
`Road`	The Road Report provides a distance breakdown by road category for each leg of the route.	PCM20 and later
`State`	The State Report provides detailed mileage information for each state or country traveled through on the route.	PCM18 and later
`RoutePath`	The Route Path Report retrieves a series of geographic coordinates that make up a route. The route is generated using the parameters below.	PCM34 and later. Requires add-on license for access to Trimble Maps JavaScript.
`WeatherAlerts`	The Weather Alerts Report provides detailed descriptions of all alerts generated along the route.	PCM29 and Later

WEB SDK & APIs

INTERACTIVE MAPS

SOAP APIs (Web Services)

RESTful APIs (Web Services)

MOBILE SDK & APIs

COPILOT NAVIGATION