Custom Road Speeds

The Routing APIs calculate Estimated Travel Time (ETT) and the corresponding Estimated Time of Arrival (ETA) using the speed of travel on roads along the planned route. These road speeds are set one of three ways:

• Default Trimble Maps road speeds. Each road class has two average road speed parameters assigned to it, one for rural roads and one for urban roads.
• Live and historical traffic. If you are licensed for traffic data, the APIs use a combination of live and historical road speeds depending on whether you set your departure time to “now” or a later time.
• Custom road speeds. These are speeds that you assign to each road class based on your fleet’s needs. If you are also licensed for traffic, and UseTraffic is set to true, custom road speeds will only be used as a cap. That is, if a road speed you set is below the historical or real-time traffic speed, that lower speed will be used in ETA calculations. Setting a governorSpeedLimit (maximum) speed will also override any custom road speeds.

Setting Custom Road Speeds

Custom road speeds are set one of two ways:

• Using the Road Speeds API, which is described on this page.
• Adding a CustomRoadSpeeds object to the POST body in Routing API calls.

Prerequisites

The Road Speeds API requires a Trimble Maps API key for access, and an application that calls RESTful APIs.

Use Cases

Custom road speeds created with this API are connected to your account. They are applied to Routing API calls when you have the CustRdSpeeds (GET requests) or UseCustomRoadSpeeds (POST requests) parameter set to True. That parameter defaults to False.

Sample GET Request with CustRdSpeeds=true

pcmiler.alk.com/apis/rest/v1.0/Service.svc/route/routeReports?dataVersion=PCM_NA&stops=-78.63930985932636,42.885606645714695;-72.885401,42.019265&reports=mileage&vehType=Truck&CustRdSpeeds=true

Sample POST Request with “UseCustomRoadSpeeds”: true

{
    "ReportRoutes": [
        {
            "ReportingOptions": {
                "UseCustomRoadSpeeds": true
            },
            "ReportTypes": [
                {
                    "__type": "MileageReportType:http://pcmiler.alk.com/APIs/v1.0",
                    "THoursWithSeconds": false
                }
            ],
            "RouteId": null,
            "Stops": [
                {
                    "Coords": {
                        "Lat": 42.885606645714695,
                        "Lon": -78.63930985932636
                    }
                },
                {
                    "Coords": {
                        "Lat": 42.019265,
                        "Lon": -72.885401
                    }
                }
            ],
            "Options": {
                "VehicleType": 0,
                "HighwayOnly": false
            }
        }
    ]
}

Concepts

The following parameters can be set in Road Speeds API calls.

Getting Started

Authentication

To authenticate calls to the Road Speeds API, you must request a JSON Web Token (JWT) by calling the Trimble identify service with your apiKey. Attach the jwt_token to an Authorization HTTP header in the form of Bearer {jwt_token} for all subsequent API calls.

Sample curl request to the identity service

curl --location --request POST 'https://api.trimblemaps.com/identity/v1/token' \
--header 'Content-Type: application/json' \
--data-raw '{
	"apiKey": "{Trimble API Key}"
}'

Sample response

{
    "token": "{jwt_token}",
    "tokenType": "Bearer",
    "expires": "2023-10-11T17:46:05.8597318Z"
}

Setting Road Speeds

Resource URL: https://api.trimblemaps.com/roadspeed/v1/speed

With the JWT, you can call the POST endpoint to assign road speeds for each road class. Speeds can be assigned for each roadCategory for a particular jurisdiction. Road speed values cannot be less than 3 mph or 5 km/h. The sample below shows how to set speeds in mph for rural roads in the state of New Jersey.

Sample Request POST Body

{
  "roadSpeeds": [
    {
      "roadCategory": 1,
      "speed": 50,
      "jurisdiction": "NJ"
    },
        {
      "roadCategory": 3,
      "speed": 45,
      "jurisdiction": "NJ"
    },
        {
      "roadCategory": 4,
      "speed": 40,
      "jurisdiction": "NJ"
    },
        {
      "roadCategory": 5,
      "speed": 30,
      "jurisdiction": "NJ"
    }
  ],
  "abbreviationFormat": 0,
  "roadSpeedsVehicleType": 0,
  "region": 4,
  "units": 0
}

Once the request is successfully processed, the new road speeds will be applied to future Routing API calls from your account when the UseCustomRoadSpeeds parameter is set to True.

Getting Road Speeds

With the GET endpoint, you can retrieve the existing road speed settings for your account. You can also view the default speeds for a jurisdiction by setting the defaultSpeeds parameter set to True.