Add weather to Trimble Maps Routes

This tool can be used to add weather forecast data to a Trimble Maps Route.

Trimble Route Endpoint

POST /route[?depart_time=YYYYmmdd.HHMM]

This endpoint accepts “application/json” requests with a body that contains a JSON response object from the Trimble Maps Route API that with both report types:

  "__type": "RoutePathReport:http://pcmiler.alk.com/APIs/v1.0"
  "__type": "DirectionsReport:http://pcmiler.alk.com/APIs/v1.0"

This will return a JSON response with the following structure with a data point for each waypoint in the RoutePathReport. Times are matched to the DirectionsReport leg estimated times:

{
  routes:[
    {
      points: "...", // encoded polyline
      valid_times: [...],
      rt: [...],
      rc: [...],
      t: [...],
      wspd: [...],
      wdir: [...],
      snod: [...],
      prate: [...],
    }
  ]
}

The valid_times variable is a list of UTC timestamps (seconds since epoch) that represents the best time estimate of arrival at waypoint given the information in the Trimble Maps response.

The points variable is a polyline encoded string Google Maps polyline information. This can be decoded to a list of lat/lon points that will match the lat/lon points in the RoutePathReport.

# pip install polyline
from polyline.codec import PolylineCodec

c = PolylineCodec()
points = c.decode(points_str)

Example

Download the file res.json and issue the following curl command from a terminal:

curl -H "Content-Type: application/json" -d "@res.json" https://routecast.acmeaom.com/route > route_forecast.json

Route From Points

A route is most simply a list of [lat, lon, time]. This endpoint can be used to query a route using a JSON array of [lat,lon,time] arrays where the time value in the array is time from departure so the first point should start at time 0. depart_time is an optional query parameter in the format YYYYmmdd.HHMM UTC, default value is current time.

POST /route_from_points[?depart_time=YYYYmmdd.HHMM]

Example

import json
import requests

my_route = [
  [40.272097,-105.556849,0],
  [40.275028,-105.564764,2800],
  [40.270215,-105.578737,5600],
  [40.268147,-105.587308,7800],
  [40.267442,-105.611906,9200]
]

url = "https://routecast.acmeaom.com/route_from_points"

response = requests.post(url, json = my_route)

route_fcst = response.json()

route_data = route_fcst['routes'][0] #currently only a single route is returned in the "routes" list

for i in range(len(my_route)):
    temperature = route_fcst['routes'][0]['t'][i]
    point_time_str = route_fcst['routes'][0]['valid_time_str'][i]
    print(f"temperature will be {temperature} C when you arrive at point {my_route[i][:2]} at {point_time_str}")

With a current time of Wed 03 Aug 2022 18:27:08 UTC you should see the following output:

temperature will be 17.6678 C when you arrive at point [40.272097, -105.556849] at 20220803 18:27:00
temperature will be 18.319 C when you arrive at point [40.275028, -105.564764] at 20220803 19:13:40
temperature will be 18.7466 C when you arrive at point [40.270215, -105.578737] at 20220803 20:00:20
temperature will be 17.6446 C when you arrive at point [40.268147, -105.587308] at 20220803 20:37:00
temperature will be 11.2602 C when you arrive at point [40.267442, -105.611906] at 20220803 21:00:20

Route from cached driving directions route

If you’ve used /driving_route to lookup a route, you can submit this route object to /route_from_route for a forecast lookup.

#get the driving directions and encoded points string with this URL
url = "https://routecast.acmeaom.com/driving_route?origin=41.5,-105.1&destination=36.1,-96.4&simplify=1.0"

response = requests.get(url)
route_data = response.json()

#This is the raw Azure Maps driving direction response
route_obj = route_data['route']

#POST the route_obj from Azure Maps
route_url = "https://routecast.acmeaom.com/route_from_route?departTime=20230113.1200"
response = requests.post(route_url, json=route_obj)

forecast_data = response.json()['routes'][0]

/driving_route will return an object with the following structure:

{
  'points':..., //polyline encoded lat/lon points
  'route':..., //Azure maps route object
  'session_id':... //session id to reference this route in later calls
}

Error codes from /driving_route:

Route from session

When you make a call to /driving_route a session with the origin/destination will be saved. You can use the session_id to get updates to the route without passing around the route object with the following endpoint:

/route_from_session?session_id={session_id}

Example

url = "https://routecast.acmeaom.com/driving_route?origin=41.5,-105.1&destination=36.1,-96.4"

response = requests.get(url)
route_data = response.json()

sess_id = route_data['session_id']

#Use the session id to get a route forecast
route_url = f"https://routecast.acmeaom.com/route_from_session?session_id={sess_id}"
response = requests.get(route_url)

forecast_data = response.json()['routes'][0]

Azure maps adjusts route estimates based on current traffic conditions. You can use the session id to get an updated route status based on a current position and optionally save this new current position as the starting point for your session:

/route_status?session_id={session_id}&current_point={lat,lon}[&update_session=true]&[route_through=true]

This will use the destination saved in the session with the current_point as the start point and return the Azure maps route summary data as follows:

{
  'arrivalTime': '2023-06-29T10:30:47-05:00',
  'departureTime': '2023-06-28T23:41:33-06:00',
  'lengthInMeters': 1168096,
  'trafficDelayInSeconds': 0,
  'trafficLengthInMeters': 0, 
  'travelTimeInSeconds': 35355
}

/route_status and /route_from_session will return 403 if the session id is no longer valid.

If update_session is included then the session will be updated with current_point as the origin for subsequent calls to /route_from_session. By default update_session is not included, the session will not be updated.

If route_through is included the route will attempt to match the exact route that is stored in the session by routing through a selection of way points. By default route_through is not included and the route will be queried with only current_point to the destination in the session and the resulting route may be different than the route saved in the session.

Data Dictionary

Road Condition Types