RESTful APIs

Route Path (POST)

Contents

The Route Path POST request retrieves a series of geographic coordinate points that make up a route. A Route Path can also be generated as one of the reports in our Route Reports API.

Requires a license for access to Trimble Maps JavaScript.

POST /route/routePath?dataset={dataset}

Resource URL

https://pcmiler.alk.com/apis/rest/v1.0/Service.svc/route/routePath?dataset={dataset}

Path Parameter

Path ParameterDefinitionRequired
datasetThe regional dataset. Possible value: Current (default), PCM_EU, PCM_OC, PCM_SA, PCM_AF, PCM_AS, PCM_ME, PCM_GT, PCM_WW, PCM_NA and PCM18-PCMXX (“XX” is the most current version of PC*MILER. Call /pcmversion to see the latest versions available.).N

Route Path Request Parameters

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

Stops is the only required parameter. 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 ElementDescriptionData TypeValue/Example
StopsStops can be entered as an address or as coordinates. 
string
See samples below for Address and Coords format.
AssetIdThe ID of the asset (device, vehicle or driver) associated with this request. 
string
abc1234
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

Route Options

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

Data ElementDescriptionData TypeValue/Example
profileNameThe 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.
VehicleTypeRestricts 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
ReduceResponsePointsIndicates whether to reduce the number of response points. 
boolean
True
False (Default)
RoutingTypeThe type of route you want to calculate. 
Enum
0 - Practical (Default)
1 - Shortest
2 - Fastest
HighwayOnlyIndicates 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)
ClassOverrides 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 Length is larger than 48' (e.g. 48.1') and/or Width is larger than 96" (e.g. 96.1"), then ClassOverrides is set to 3(National Network + FiftyThreeFoot) without an option to turn it off;
if Length is smaller than 48' and Width is smaller than 96", then ClassOverrides 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
DistanceUnitsSets whether to use miles or kilometers in distance and speed measurements. 
Enum
0 - Miles (Default)
1 - Km
TollDiscourageIndicates whether or not to avoid tolls. This parameter has been deprecated. Use TollRoads instead. 
boolean
True
False (Default)
TollRoadsIndicates whether or not to avoid toll roads when generating a route. If this parameter is specified, the value in TollDiscourage will be ignored. If this parameter is null, the value in TollDiscourage will be used. Available in dataVersion PCM34 and later. Use TollDiscourage for older versions. 
int
1 - Always Avoid
2 - Avoid if Possible
3 - Use
Default is null.
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 later. A list of comma-separated countries. 
list of strings
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 later.A list of comma-separated states. 
list of strings
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 later. A list of comma-separated countries. 
list of strings
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 later.A list of comma-separated states. 
list of strings
PA, CT
BordersOpenSets 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
OverrideRestrictIndicates whether or not to override truck restrictions pertaining to specific sizes and weights when generating a route. 
boolean
True
False (Default)
HazMatTypeIndicates 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
HazMatTypesAn 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
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
RouteOptimizationIndicates the method by which to optimize route stops. 
Enum
0 - None (Default)
1 - ThruAll
2 - DestinationFixed
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)
UnitsVehicle dimension units 
Enum
0 - English (Default)
1 - Metric
Height The height of the truck in feet and inches or meters depending on Units.
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.
Length The length of a straight truck/van or combined vehicle’s trailer in feet and inches or meters depending on Units. 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, Length 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.
Width The width of the truck in inches or meters depending on Units.
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.
Weight The weight of the truck in pounds or kilograms depending on Units.
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
MaxWeightPerAxleGroupThe maximum weight per axle group in pounds or kilograms depending on Units.
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)
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 DistanceUnits.
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 DistanceUnits parameter. Miles = feet, Kilometers = meters. Available for dataVersion Current, PCM_NA, and PCM29 and later. 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 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)
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. Set to [-1] to select all sets.List of comma separated IDs24,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
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
}
EstimatedTimeOptions 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. 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. DateOption must be set to 1 for this value to be used.

DayOfWeek - Day of the week, starting at 0-Sunday, 1-Monday, 2-Tuesday and so on. DateOption must be set to 2 for this value to be used.

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
   }
}
UseTrafficIndicates 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 (RoutingType) is set to Fastest. (Fastest routing is not recommended for trucks—autos and vans only.)

 
boolean
True
False (Default)
IncludeVehicleRestrictedCleanupPointsIndicates whether to return the path from the drivable road network to a stop located on a pedestrian only road. (This is usually the path the driver has walk to reach a stop on a vehicle-restricted road.) 
boolean
True
False (Default)

Route Path Response Parameters

Data ElementDescriptionData TypeValue/Example
TypeIndicates the type of response 
string
GeometryThe route points of the route that was runGeoJson Geometry
vehiclerestrictedcleanupgeometryList of coordinates that represents the path from the drivable road network to a stop located on a pedestrian only road. (This is usually the path the driver has walk to reach a stop on a vehicle-restricted road.) This path, if one exists, is only returned when includeVehicleRestrictedCleanupPoints is set to true in the request.GeoJson Geometry

Geometry

Data ElementDescriptionData TypeValue/Example
TypeIndicates the type of geometry 
string
Multistring (currently this is the only value)
CoordinatesA series of geographic coordinate points that make up a routeJson array of arrays

Sample POST Body 

{
  "Route": {
    "Stops": [
      {
        "Coords": {
          "Lat": "51.517749",
          "Lon": "-0.171839"
        },
        "Region": 4
      },
      {
        "Coords": {
          "Lat": "51.518264",
          "Lon": "-0.174080"
        },
        "Region": 4
      },
      {
        "Coords": {
          "Lat": "51.516322",
          "Lon": "-0.17543"
        },
        "Region": 4
      }
    ],
    "Options": {
      "BordersOpen": true,
      "DistanceUnits": 0,
      "HazMatType": 0,
      "HighwayOnly": false,
      "TruckCfg": {
        "Weight": "9000",
        "Axles": 6,
        "Units": 0,
        "LCV": false,
        "Width": "8'0"
      },
      "RouteOptimization": 0,
      "RoutingType": 0,
      "VehicleType": 0,
      "ClassOverrides": 3,
      "OverrideRestrict": false,
      "UseSideofStreet": false,
      }
      "ExtendedOptions":
      {
          "IncludeVehicleRestrictedCleanupPoints": true
      }
    }
  }

Sample Response 

{
  "type": "Feature",
  "geometry": {
    "type": "MultiLineString",
    "coordinates": [
      [
        [-0.171839, 51.517749],
        [-0.171799, 51.517723],
        [-0.17122, 51.51806],
        [-0.171, 51.51819],
        [-0.17112, 51.51821],
        [-0.17117, 51.51822],
        [-0.17121, 51.51822],
        [-0.17137, 51.51818],
        [-0.17143, 51.51817],
        [-0.17148, 51.51816],
        [-0.17194, 51.51809],
        [-0.17276, 51.51795],
        [-0.17383, 51.51776],
        [-0.173856, 51.517756]
      ],
      [
        [-0.173856, 51.517756],
        [-0.17529, 51.51751],
        [-0.17567, 51.51743],
        [-0.1758, 51.51738],
        [-0.17597, 51.51729],
        [-0.17624, 51.51715],
        [-0.17624, 51.51714],
        [-0.17624, 51.51713],
        [-0.17624, 51.51712],
        [-0.17611, 51.51703],
        [-0.17586, 51.51685],
        [-0.17583, 51.5168],
        [-0.17581, 51.51677],
        [-0.1758, 51.51674],
        [-0.1758, 51.5167],
        [-0.1758, 51.51666],
        [-0.17582, 51.51658],
        [-0.17581, 51.51656],
        [-0.1758, 51.51655],
        [-0.17575, 51.51651],
        [-0.175456, 51.516308],
        [-0.17543, 51.516322]
      ]
    ]
  },
  "TMinutes": 2,
  "TDistance": 0.356,
  "properties": null,
  "vehiclerestrictedcleanupgeometry": {
    "type": "MultiLineString",
    "coordinates": [
      [
        [-0.173856, 51.517756],
        [-0.17408, 51.518264]
      ],
      [
        [-0.17408, 51.518264],
        [-0.173856, 51.517756]
      ]
    ]
  }
}
Last updated May 11, 2023.
Contents