Skip to main content

Route Comparison

The Route Comparison APIs can help you plan routes by considering the time and distance between a series of locations. Below are descriptions of the parameters shared across these functions.

profileName
Data ElementDescriptionData TypeValue/Example
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
stopsAsViaPoints The 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 treated as via points.

boolean
True
False (Default)
vehType
POST: VehicleType
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
routeType
POST: RoutingType
The type of route you want to calculate.
Enum
0 - Practical (Default)
1 - Shortest
2 - Fastest
hwyOnly
POST: HighwayOnly
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, 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)
avoidFavorsIndicates whether to use Route Modifiers (roads to avoid or favor) when generating a routing
boolean
True
False (Default)
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
POST: DistanceUnits
Sets whether to use miles or kilometers in distance and speed measurements.
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. Available in dataVersion PCM34 and higher. Use avoidTolls for older versions.
int
1 - Always Avoid
2 - Avoid if Possible
3 - Use
Default is null.
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
avoidCountryA 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
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. Available in PCM34 and higher.
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. Available in PCM34 and higher.
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. Available in PCM34 and higher.
string
PA, CT
overrideRestrict
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. 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
routeOpt
POST: RouteOptimization
Indicates the method by which to optimize route stops.
Enum
0 - None (Default)
1 - ThruAll
2 - DestinationFixed
langLanguage
Enum
0 - 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.
boolean
True
False (Default)
vehDimUnits
POST: Units
Vehicle dimension units
Enum
0 - English (Default)
1 - Metric
vehHeight
POST: Height
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
POST: Length
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
POST: Width
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
POST: Weight
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.
axlesThe number of axles on the truck
Int
Acceptable values are 2 through 14 and the default value is 5
trkMaxWeightPerAxleGroup
POST: MaxWeightPerAxleGroup
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.
LCVIndicates whether the truck is a multi-trailer or longer combination vehicle.
boolean
True
False (Default)
estimatedTimeOpts Estimated 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
(Default is none)
hosEnabledIndicates whether or not to enable Hour of Service option.
boolean
True
False (Default)
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 USFed607LH - 0, USFed708LH - 1, CanadaCycle1 - 2, CanadaCycle2 - 3, California808 - 4, Texas707 - 5, USShortHaul - 6, Europe - 7
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 (Default)
1- Minimal
2 - Moderate
3 - Average
4 - Strict
5 - Adhere
6 - StronglyAdhere
useCrossStreetTurnAvoidanceWhen 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).
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. 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
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-PCMXX ("XX" is the most current version of PC*MILER. Call /pcmversion to see the latest versions available. RoutePath only.)
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.
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 IDs24,133,204
afSetNames
POST: 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
reduceResponsePointsIndicates whether to reduce the number of response points.
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
ferryDiscourageIndicates 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)
includePLIDsWhether to include PLID metadata for the generated route. A PLID is a road link's primary ID coded in the map data.
boolean
True
False (Default)
Last updated April 7, 2022.