RESTful APIs

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 EstimatedTimeOptions object to set a departure date/time.
  • dataVersion must be Current or you will receive an error. Current is the default setting so best practice is to not set a dataVersion when 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 RoutePathReportType in the ReportTypes array. (You can also add the WeatherImpactReportType, and other reports like MileageReportType, but they are not required.)
  • An AlternateRouteOptions object that tells the system how to create alternate routes.
  • A WaypointConfig object. 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:
    • IncludeBaseWaypoints uses waypoints from the Trimble database.
    • Waypoints uses a list of waypoints you send with the API call.

Waypoints on a map
A map visualization of how waypoints shape alternate routes between two stops—S (green circle) and 2 (blue circle). This example factors weather conditions into route selection, and the three alternate route paths avoid some or all of the predicted bad weather along the primary route. Fleets can use the Alternate Route Report to compare routes based on distance, time, toll costs, and weather conditions, and choose the safest and most efficient path for a trip.

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 MaxWeatherRisk is 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.

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
            }
        ]
    }
]
Last updated July 9, 2026.
API Endpoint:
AWS Azure
Contents