Fetch routes

A GET request to the /routes endpoint with the query parameters workspaceId and date retrieves a list of routes planned within a specific workspace on a given date in Routific. Below is an example of the response payload containing route data.

Request URL

get https://api.plan.routific.com/v2/routes?workspaceUuid={workspaceUuid}&date={yyyy-mm-dd}

Request Payload

//none

Sample Response Payload

{
  "items": [
    {
      "uuid": "246612f0-f160-4649-bb16-292ebaa43555",
      "name": "Route 11",
      "date": "2024-09-25",
      "driver": {
        "name": "John Doe"
      },
      "timeline": {
        "uri":"/v2/routes/246612f0-f160-4649-bb16-292ebaa43555/timeline"
      },
      "constraints": {
        "startTime": "08:00",
        "endTime":"18:00",
        "capacity": 10,
        "tags": [
          "refrigerated"
        ]
      },
      "status": "planned",
      "workspaceUuid": "a69eb360-5d69-4ca4-b348-141b15f3b0b4",
      "workingTimeInSeconds": 2700,
      "distanceInKilometers": 4991,
      "ordersCount": 3,
      "capacityUsed": 7
    }
  ],
  "nextCursor": "aWQ6MTA5OTc5NA"
}

The response includes high-level data for each route: route uuids, assigned driver, status, and the latest statistics. You can use the timeline.uri to make subsequent API calls to the /timeline endpoint to fetch more details for each route, including route sequences, ETAs, and planned vs actual timings.

Field	Type	Description
items	Array	Contains a list of routes matching the search criteria.
uuid	String	Unique identifier of the route.
name	String	Name of the route.
date	String	Date when the route is planned for. Format: YYYY-MM-DD.
driver.name	String	Name of the driver assigned to the route. A `null` value will be returned if no driver is assigned.
timeline.uri	String	The URI to access additional details about a route's timeline like the sequence of stops and their associated ETAs.
constraints.startTime	String	The configured start time of the route.
constraints.endTime	String	The configured end time of the route.
constraints.capacity	Integer	The maximum capacity of the route.
constraints.tags	Array	Tags assigned to the routes
status	String	Current status of the route. Possible values: planned, published, executing, and completed.
workspaceId	Integer	ID of the workspace where the route belongs.
workingTimeInSeconds	Integer	Total working time for the route in seconds.
distanceInKilometers	Integer	Total distance covered by the route in kilometers.
ordersCount	Integer	Number of orders assigned to the route.
capacityUsed	Integer	Total utilized capacity of the routes based on the orders assigned to the route.
nextCursor	String	The URL for the next page of results. If there are no more pages, this value is `null`.

📘
Is the working time planned or actual?
Its both, but it depends on the status of the route. Here's what you can expect based on the status of the route:
Planned and Published: For these two route states we return the planned working time based on our estimates of travel time, traffic information, etc.
Executing: We return an aggregate total working time that's a mix of both planned and actual times because when a route in being executed we only have the actual timings for the route that has already been completed.
Completed: We return the actual working time of the route based on the actual arrival and departure times of all the stops and events within the route.

Request URL

Request Payload

Sample Response Payload

📘Is the working time planned or actual?

📘
Is the working time planned or actual?