Alternate Route Report
Contents
The Alternate Route Report calculates a primary route path and up to three alternate routes between specified stops. You can compare routes by distance, time, and tolls to determine the optimal route. This report can be used independently or combined with the Weather Impact Report to factor weather conditions into route selection.
POST /route/routeReports
Resource URL
https://pcmiler.alk.com/apis/rest/v1.0/Service.svc/route/routeReports
Prerequisites & Limits
- Your PC*Miler API key must have the Alternate Routes premium add-on enabled. To include weather, you must also be licensed for Weather Impact (Hyperlocal Weather). Contact us to learn more.
- Maximum of three alternate routes.
When also calling for a Weather Impact Report:
- A departure date/time within the next 7 days is required. Use the
EstimatedTimeOptionsobject to set a departure date/time. dataVersionmust beCurrentor you will receive an error.Currentis the default setting so best practice is to not set adataVersionwhen calling an Alternate Route report.- Currently only supports U.S. customary units—inches, miles, miles-per-hour (mph), and degrees Fahrenheit.
Use Cases
The service supports both pre-trip planning and back-office decision-making. You can pick a route based on a combination of:
- Distance, time, and toll costs
- Driving conditions
- Weather risk (with Weather included)
Concepts
The Alternate Routes Report works like any other POST Route Report, but you must include:
- A
RoutePathReportTypein theReportTypesarray. (You can also add theWeatherImpactReportType, and other reports likeMileageReportType, but they are not required.) - An
AlternateRouteOptionsobject that tells the system how to create alternate routes. - A
WaypointConfigobject. Waypoints are points along the route that help shape where alternate routes can go. For example, they might be rest stops, company depots, or other approved places to drive through. You can choose one or both of these waypoint settings:IncludeBaseWaypointsuses waypoints from the Trimble database.Waypointsuses a list of waypoints you send with the API call.
How weather influences route selection
The AlternateRouteOptions object includes a MaxWeatherRisk field that filters alternate routes based on weather conditions.
- If it is not set (null or 0): All three alternates are returned with no weather filtering.
- When
MaxWeatherRiskis set (greater than 0):- If your main route has no weather risk: Alternates are returned if they have no weather risk or their risk is at or below
MaxWeatherRisk. - If your main route has weather risk: Alternates are returned if they have no weather risk or their risk is at or below your main route’s risk level.
- If your main route has no weather risk: Alternates are returned if they have no weather risk or their risk is at or below
AlternateRouteOptions
| Parameter | Type | Description | Required? | Example |
|---|---|---|---|---|
AlternateRouteOptions
| Object | An object that sets options for alternate route calculation. | Required to return alternate routes. | See sample JSON below. |
AlternateRouteOptions > Enabled
| Boolean | Enables or disables alternate route calculation. | Default = true (if included; if omitted, false)
| true
|
AlternateRouteOptions > Type
| Enum (Integer) | Specifies the type of alternate route calculation. | Required if Enabled = true; 0 = WaypointInjection
| 0 is currently the only available option.
|
AlternateRouteOptions > WaypointConfig
| Object | The waypoints used to calculate alternate routes. | Required when Type = 0 - WaypointInjection
| Required |
AlternateRouteOptions > DistanceDeltaThreshold
| Object | The percentage distance required for a route to be considered an alternate. | Optional - (Defaults are 0.01 for MinPercentage and 0.2 for MaxPercentage) | See below. |
AlternateRouteOptions > MaxAlternates
| Number | Maximum number of alternate routes to return (up to 3 per leg.) | No - (Default is 3) | 3
|
AlternateRouteOptions > MaxWeatherRisk
| Number | Weather risk level to consider when finding alternate routes. Weather Risk is a 0-10 scale; alternates are only considered if the primary route is at the set risk level or higher. If this value is not set (null or 0), no weather-based filtering is applied. | No - (Default is null) | 4
|
AlternateRouteOptions > IncludeWeatherSummary
| Boolean | Whether to include a weather summary list in the response. Even when included, the summary can be an empty array when there is no weather impacting that route. | No - (Default is false) | false
|
AlternateRouteOptions.Type Enum
| Value | Type | Description | Required? | Example |
|---|---|---|---|---|
WaypointInjection
| 0 (0-based enum) | Waypoints are used to shape alternate routes. | Yes | Currently only 0 - WaypointInjection is supported.
|
WaypointConfig Object
| Parameter | Type | Description | Required? | Example |
|---|---|---|---|---|
WaypointConfig
| Object | Configuration object that defines waypoints used to shape alternate routes. | Yes (conditional) | Required if Type = 0 - WaypointInjection
|
WaypointConfig > IncludeBaseWaypoints
| Boolean | Determines whether to include waypoints from the Trimble database when calculating alternate routes. | Optional | true
|
WaypointConfig > Waypoints
| Array of StopLocation | A list of waypoints you send with the API call. These are points along the route that help shape where alternate routes can go (e.g., approved rest stops, company locations, or other safe places). | Optional | See sample JSON below |
DistanceDeltaThreshold
| Parameter | Type | Description | Required? | Example |
|---|---|---|---|---|
DistanceDeltaThreshold
| Object | Entered a percentage, using the parameters below. | Optional | Values for MinPercentage and MaxPercentage.
|
DistanceDeltaThreshold > MinPercentage
| Number | Minimum percentage difference in distance required for a route to be considered an alternate. (Default is 0.01, which is 1 percent)
| Yes if MaxPercentage is provided.
| 0.0025 |
DistanceDeltaThreshold > MaxPercentage
| Number | Maximum percentage difference in distance allowed for a route to be considered an alternate. (Default is 0.2, which is 20 percent)
| Yes, if MinPercentage is provided.
| 0.9 |
Sample AlternateRouteOptions Object
"AlternateRouteOptions": {
"Enabled": true,
"Type": 0,
"DistanceDeltaThreshold": {
"MinPercentage": 0.01,
"MaxPercentage": 0.20
},
"WaypointConfig": {
"IncludeBaseWaypoints": true,
"Waypoints": [
{
"Coords": {
"Lat": 40.123706,
"Lon": -74.711641
},
"Label": "BORDENTOWN,NJ/ (ROUNEW04)",
"Region": 4
},
{
"Coords": {
"Lat": 41.000000,
"Lon": -75.500000
},
"Label": "PA Test Waypoint",
"Region": 4
}
]
},
"MaxAlternates": 3,
"MaxWeatherRisk": 4
}
Sample Request Body
This example calls an Alternate Routes Report that takes weather into account with a WeatherImpactReportType.
{
"ReportRoutes": [
{
"RouteId": "8345190",
"Stops": [
{
"Coords": {
"Lat": 40.918727,
"Lon": -76.078611
},
"Address": {
"StreetAddress": "100 Green Mountain Road",
"City": "Hazle Township",
"State": "PA",
"Zip": "18202",
"County": "Luzerne",
"Country": "United States"
},
"Region": 4,
"Label": "G US DSV HAZLE TOWNSHIP",
"ID": "30422729"
},
{
"Coords": {
"Lat": 36.9356,
"Lon": -86.5042
},
"Address": {
"StreetAddress": "487 Central Avenue",
"City": "Bowling Green",
"State": "KY",
"Zip": "42101",
"County": "Warren",
"Country": "United States"
},
"Region": 4,
"Label": "G US DHL BOWLING GREEN OPTI",
"ID": "30422730"
}
],
"Options": {
"AFSetIDs": [-1],
"BordersOpen": true,
"HighwayOnly": false,
"ProfileName": "Heavy Duty Doubles",
"UseSites": true
},
"AssetId": "241928",
"ReportingOptions": {
"UseTraffic": true,
"EstimatedTimeOptions": {
"ETAETD": 1,
"DateOption": 1,
"DateAndTime": {
"Timestamp": "2026-01-28T17:59:00+00:00"
}
}
},
"AlternateRouteOptions": {
"Enabled": true,
"Type": 0,
"DistanceDeltaThreshold": {
"MinPercentage": 0.01,
"MaxPercentage": 0.20
},
"WaypointConfig": {
"IncludeBaseWaypoints": true,
"Waypoints": [
{
"Coords": {
"Lat": 40.123706,
"Lon": -74.711641
},
"Label": "BORDENTOWN,NJ/ (ROUNEW04)",
"Region": 4
},
{
"Coords": {
"Lat": 41.000000,
"Lon": -75.500000
},
"Label": "PA Test Waypoint",
"Region": 4
}
]
},
"MaxAlternates": 3,
"MaxWeatherRisk": 4
},
"ReportTypes": [
{
"__type": "RoutePathReportType:http://pcmiler.alk.com/APIs/v1.0",
"TimeInSeconds": null,
"IncludeDetails": null
},
{
"__type": "WeatherImpactReportType:http://pcmiler.alk.com/APIs/v1.0",
"TimeInSeconds": null,
"IncludeDetails": true
}
]
}
]
}
Sample Response
The primary route path is returned in a Route Path Report, while alternate routes are provided in an Alternate Routes Report containing an array of Route Path Reports for each alternate. The coordinate arrays have been shortened in this example for readability.
In AlternateRoutes, distances are in miles, and duration is in seconds.
[
{
"__type": "RoutePathReport:http://pcmiler.alk.com/APIs/v1.0",
"type": "Feature",
"RouteID": "8345190",
"geometry": {
"type": "MultiLineString",
"coordinates": [
[
[
-76.074042,
40.917385
],
[
-76.073734,
40.916412
],
[
-76.07607,
40.915988
],
// Additional GPS coordinates for primary route
]
]
},
"TMinutes": 708,
"AssetId": "241928",
"TDistance": 769.679,
"properties": null
},
{
"__type": "WeatherImpactReport:http://pcmiler.alk.com/APIs/v1.0",
"SlowdownSummary": 0,
"RouteID": "8345190",
"DistanceUOM": "miles",
"TemperatureUOM": "fahrenheit",
"AssetId": "241928",
"PrecipitationUOM": null,
"WeatherSummary": [],
"WeatherImpact": [],
"WeatherAlertReferences": []
},
{
"__type": "AlternateRoutesReport:http://pcmiler.alk.com/APIs/v1.0",
"PrimaryRouteId": "8345190",
"RouteID": "8345190",
"AlternateRoutes": [
{
"RouteID": null,
"GeneratedByMethod": "WaypointInjection",
"Waypoints": null,
"DeltaFromPrimary": {
"Distance": {
"Absolute": 7.9560000000000173,
"Percentage": 1.0336776760181865
},
"Duration": {
"Absolute": 480,
"Percentage": 1.1299435028248588
}
},
"RouteReports": [
{
"__type": "RoutePathReport:http://pcmiler.alk.com/APIs/v1.0",
"type": "Feature",
"RouteID": "8345190",
"geometry": {
"type": "MultiLineString",
"coordinates": [
[
[
-76.074042,
40.917385
],
[
-76.073734,
40.916412
],
[
-76.07607,
40.915988
],
// Additional GPS coordinates for alternate Route 1
]
]
},
"TMinutes": 716,
"AssetId": "241928",
"TDistance": 777.635,
"properties": null
},
{
"__type": "WeatherImpactReport:http://pcmiler.alk.com/APIs/v1.0",
"SlowdownSummary": 0,
"RouteID": "8345190",
"DistanceUOM": "miles",
"TemperatureUOM": "fahrenheit",
"AssetId": "241928",
"PrecipitationUOM": null,
"WeatherSummary": [],
"WeatherImpact": [],
"WeatherAlertReferences": []
}
],
"LegID": 0
},
{
"RouteID": null,
"GeneratedByMethod": "WaypointInjection",
"Waypoints": null,
"DeltaFromPrimary": {
"Distance": {
"Absolute": 9.1470000000000482,
"Percentage": 1.1884175091174436
},
"Duration": {
"Absolute": 720,
"Percentage": 1.6949152542372881
}
},
"RouteReports": [
{
"__type": "RoutePathReport:http://pcmiler.alk.com/APIs/v1.0",
"type": "Feature",
"RouteID": "8345190",
"geometry": {
"type": "MultiLineString",
"coordinates": [
[
[
-76.074042,
40.917385
],
[
-76.073734,
40.916412
],
[
-76.07607,
40.915988
],
// Additional GPS coordinates for alternate Route 2
},
"TMinutes": 720,
"AssetId": "241928",
"TDistance": 778.826,
"properties": null
},
{
"__type": "WeatherImpactReport:http://pcmiler.alk.com/APIs/v1.0",
"SlowdownSummary": 0,
"RouteID": "8345190",
"DistanceUOM": "miles",
"TemperatureUOM": "fahrenheit",
"AssetId": "241928",
"PrecipitationUOM": null,
"WeatherSummary": [],
"WeatherImpact": [],
"WeatherAlertReferences": []
}
],
"LegID": 0
},
{
"RouteID": null,
"GeneratedByMethod": "WaypointInjection",
"Waypoints": null,
"DeltaFromPrimary": {
"Distance": {
"Absolute": 8.8300000000000409,
"Percentage": 1.1472315082001772
},
"Duration": {
"Absolute": 540,
"Percentage": 1.2711864406779663
}
},
"RouteReports": [
{
"__type": "RoutePathReport:http://pcmiler.alk.com/APIs/v1.0",
"type": "Feature",
"RouteID": "8345190",
"geometry": {
"type": "MultiLineString",
"coordinates": [
[
[
-76.074042,
40.917385
],
[
-76.073734,
40.916412
],
[
-76.07607,
40.915988
],
// Additional GPS coordinates for alternate Route 3
},
"TMinutes": 717,
"AssetId": "241928",
"TDistance": 778.509,
"properties": null
},
{
"__type": "WeatherImpactReport:http://pcmiler.alk.com/APIs/v1.0",
"SlowdownSummary": 0,
"RouteID": "8345190",
"DistanceUOM": "miles",
"TemperatureUOM": "fahrenheit",
"AssetId": "241928",
"PrecipitationUOM": null,
"WeatherSummary": [],
"WeatherImpact": [],
"WeatherAlertReferences": []
}
],
"LegID": 0
}
]
}
]