Route Geometry

Our /route and /derivedRoute resources include a number of functions that allow you to generate commercial vehicle routes (Route Path), determine the route that was taken using latitude/longitude pings (Derived Route), and consider possible routes by looking at the time and distance between a series of locations (Route Matrix and Drive Time Polygon).

Below are descriptions of the parameters shared across these functions.

Data ElementDescriptionData TypeValue/Example
StopsThe coordinates that make up the stops of the routeList of comma-separated long.lat pairs, separated by semi-colons-76.12345,42.12345
-76.12312,42.12312
-76.12456,42.12456
assetIdThe ID of the asset (device, vehicle or driver) associated with this request.
string
abc1234
PlaceIdThe 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
stopsAsViaPointsThe via points you create can be designated as stops or waypoints. The “waypoint” designation means that these locations were added only to guide the route along desired roads. Waypoints are treated like stops on the map (routes travel through the centroid of a waypoint town or city), but they don’t appear in the driving instructions in the Driver’s Directions Report and are marked as a “Via” in the Detailed route Report. Waypoints appear on the stop list as circles with a gray border.
When provided true, all stops between the first and last are as via points.
boolean
True/False
vehTypeThe vehicle type
Enum
0 - Truck
1 - LightTruck
2 - Auto
routingThe desired routing algorithm
Enum
0 - Practical
1 - Shortest
2 - Fastest
hwyOnlyIndicates whether to use highways only
boolean
True/False
useAvoidFavorsIndicates whether or not to use avoid favors while routing
boolean
True/False
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.
Enum
0 - None
1 - FiftyThreeFoot
2 - NationalNetwork
3 - NationalNetwork and FiftyThreeFoot
distUnitsDistance Units.
Enum
0 - Miles
1 - Km
tollAvoidIndicates whether or not to avoid tolls. This parameter has been deprecated. Use tollRoads instead.
boolean
True/False
tollRoadsIndicates whether or not to avoid toll roads when generating a route. If this parameter is specified, the value in tollAvoid will be ignored. If this parameter is null, the value in tollAvoid will be used.
int
1 - Always Avoid
2 - Avoid if Possible
3 - Use
Default is null.
bordersIndicates whether borders are open to travel.
boolean
True/False
avoidCountryA comma-separated list of ISO2 codes for countries that should be avoided when generating a route. Default is an empty list. This parameter is for regions outside of North America.
string
BE, LU
avoidStateA 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.
string
DE, RI
favorCountryA 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.
string
DE, FR
favorStateA 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.
string
PA, CT
ovrdRestrictIndicates whether or not to override truck
boolean
True/false
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
hazMatTypesAn 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
tunnelCategoryThe tunnel category to apply when generating a route. Europe Only
Enum
0 - None (Default)
1 - TunnelBCDE
2 - TunnelCDE
3 - TunnelDE
4 - TunnelE
tunnelCategoriesAn 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
routeOptIndicates the method by which to optimize route stops.
Enum
0 - None
1 - ThruAll
2 - DestinationFixed
langLanguage
Enum
0 - ENUS
1 - ENGB
2 - DE
3 - FR
4 - ES
5 - IT
hubRoutingIndicates whether or not to enable hub routing
boolean
True/False
vehDimUnitsVehicle dimension units
Enum
0 - English
1 - Metric
vehHeightThe height of the truck in feet and inches or meters depending on vehDimUnits.
Valid range is between 5' and 15' for English Unit, or between 1.524 and 5 meters for Metric Unit.
string
13'6" or 4.1148
vehLengthThe length of the truck in feet and inches or meters depending on vehDimUnits.
Valid range is between 8' and 70' for English Unit, or between 2.4384 and 28 meters for Metric Unit.
string
13'6" or 4.1148
vehWidthThe width of the truck in inches or meters depending on vehDimUnits.
Valid range is between 60" and 102" for English Unit, or between 1.524 and 3 meters for Metric Unit.
string
96" or 2.44
vehWeightThe weight of the truck in pounds or kilograms depending on vehDimUnits.
Valid range is between 1500 and 156470 lbs for English Unit, or between 680.39 and 60000 kgs for Metric Unit.
string
AxlesThe number of axles on the truck
Int
Acceptable values are 2 through 14 and the default value is 5
truckConfigThe truck style.
Enum
0 - None
1 - TwentyEightDoubleTrailer
2 - FortyStraightTruck
3 - FortyEightSemiTrailer
4 - FiftyThreeSemiTrailer
5 - FullSizeVan
6 - TwentySixStraightTruck
LCVIndicates whether the truck is a multi-trailer or longer combination vehicle.
boolean
True/False
useTrafficIndicates whether or not use traffic which is only used in conjunction with fastest routing.
boolean
True/False
estimatedTimeOptsEstimated time options affects routing only when roads have time based restrictions.
Format:
Depart(Arrive)|[DayOfWeek]|[TimeOfDay]
or Depart(Arrive)|[SpecificDateTime]|[TimeZone]
Supported time zones can be found here
string
Examples:
Depart|Monday|18:30
Arrive|2014-03-04T08:15:30|Local
hosEnabledIndicates whether or not to enable Hour of Service option.
boolean
True/False
hosRemDriveTimeUntilBreakThe available driving hours at origin before the driver needs to take a rest break.
double
The format is in seconds.
hosRemDriveTimeThe available driving hours at origin until the end of work day.
double
The format is in seconds.
hosRemOnDutyTimeThe available On-Duty hours available at origin until the end of work day.
double
The format is in seconds.
hosRuleTypeThe hours of service rule to use.
Enum
Valid values are 0 - USFed607LH, or 1 - USFed708LH for US Federal Long Haul rules.
hosRemCycleDutyTimeThe available Cycle time duty hours at origin until Cycle reset.
double
The format is in seconds.
sideOfStreetAdherenceHow strict to be in order to avoid the destination being on the opposite side of the street.
Enum
0 - off
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.
double
The format is in mph or kph based on distance units.
regionThe data region in which stop coordinates lie.
Enum
0 - Unknown
1 - AF
2 - AS
3 - EU
4 - NA(default)
5 - OC
6 - SA
7 - ME
datasetThe Regional dataset.
Enum
PCM_EU
PCM_OC
PCM_SA
PCM_ME
PCM_AS
PCM_AF
PCM_WW(Worldwide)
PCM_GT(GeoTrack)
Current(default)
PCM23-PCM33 (routePath only)
classOvrdtypeA comma-separated list of class overrides.
Enum
0 - None (Default)
1 - NationalNetwork
2 - FiftyThreeFoot
vehProfileIndicates the vehicle profile which is a preset collection of dimensions and routing options.
Enum
0 - None (Default)
1 - TwentyEightDoubleTrailer
2 - FortyStraightTruck
3 - FortyEightSemiTrailer
4 - FiftyThreeSemiTrailer
5 - FullSizeVan
6 - TwentySixStraightTruck
7 - ConventionalSchoolBus
8 - SmallSchoolBus
trkUnitsVehicle dimension units.
Enum
0 - English (Default)
1 - Metric
trkHeightThe height of the truck in feet and inches (English) or meters (Metric).
string
Maximum value is 13'6" or 4.1148 meters. Default is 13'6" in all regions except Europe, which is 12'6".
trkLengthThe length of the truck in feet and inches (English) or meters (Metric).
string
Maximum value is 53 feet or 16.1544 meters. Default is 48 feet in all regions except Europe, which is 54"1'.
trkWidthThe width of the truck in feet and inches (English) or meters (Metric).
string
This value may be 96" and below, 102" and above or 98". Default is 96" for all regions.
trkWeightThe weight of the truck in pounds (English) or kilograms (Metric).
string
Acceptable values can be up to 132,000 pounds or 59,874 kilos. The default value is 80,000 pounds for all regions.
trkAxlesIndicates the number of axles on the vehicle.
Int
Acceptable values are 2 through 14. Default is 5.
truckConfigIndicates the truck style.
Enum
0 - None (default)
1 - TwentyEightDoubleTrailer
2 - FortyStraightTruck
3 - FortyEightSemiTrailer
4 - FiftyThreeSemiTrailer
5 - FullSizeVan
6 - TwentySixStraightTruck
7 - ConventionalSchoolBus
8 - SmallSchoolBus
trkLCVIndicates whether the truck is a multi-trailer or longer combination vehicle.
boolean
True - Multi-trailer
False - Longer combination vehicle (Default)
afSetIDsApply the avoid/favor sets to the route.Int ArrayDefault is none, i.e. empty list.
afSetNamesApply the avoid/favor sets to the route.String ArrayDefault is none, i.e. empty list.
reduceResponsePointsIndicates whether to reduce the number of response points.
boolean
True
False (Default)
GET:
includeVehicleRestrictedCleanupPoints
POST:
"ExtendedOptions":
{
"IncludeVehicleRestrictedCleanupPoints": true
}
If a stop maps to a pedestrian only/vehicle restricted road, this value is used to separate the path coordinates that run from the valid road network to the lat/long of the stop. In these situations, the driver must exit the vehicle and walk to the destination. This value is not required, and it defaults to false. reduceResponsePoints must also be set to false to use this parameter.
boolean
True
False (Default)
elevLimitIndicates the elevation limit when generating a route. Elevation unit is specified in feet or meters.uint
ferryDiscourageIndicates whether or not to discourage the use of ferries when creating the route.
boolean
True
False (Default)
useSitesIndicates whether or not the route stops are on sites and to accordingly consider site gates.
boolean
True
False (Default)
includePLIDsInclude whether to include PLID metadata for the generated route.
boolean
True
False (Default)