Overview

The Routes API allows you to ingest and manage multi-segment journeys, such as delivery routes, patrol paths, or other sequential activities. It supports complex multi-leg routes, real-time updates, and feed-based organization for efficient route management.

Endpoint

POST: https://api.tomorrow.io/v4/connect/routes/{feedId}

Path Parameters

Parameter	Type	Required	Description	Example
`feedId`	string	✅	Identifier for the feed to ingest route data into. Organizes routes in a feed by fleet, region, or route type.	`delivery-routes`

Request Body

Routes Request

The request body must contain a data array with one or more route objects.

Field	Type	Constraints	Description
`data`	`array<RouteItem>`	Max amount of items- 200	Array of route items to ingest

Route Item

Field	Type	Required	Description
`id`	string	✅	Unique route identifier.
`name`	string	✅	Human-readable route name.
`legs`	`array<Leg>`	✅	Route legs. Minimum of 1 leg.
`startTime`	string (date-time)	—	Start of validity period (defaults to current time).
`endTime`	string (date-time)	—	End of validity period (defaults to 1 day later).
`attributes`	object	—	Custom metadata for the route.

Leg

Field	Type	Required	Description
`id`	string	✅	Unique leg identifier.
`locations`	array	✅	GeoJSON locations (minimum of one item). Each location is one of two formats- (1)`{ "geojsonGeometry": { "type": "Feature", "geometry": <geom>, "properties": {} } }` (2)`{ "geojsonGeometry": <geom> }`
`start`	string (date-time)	—	Start of leg (defaults to current time).
`end`	string (date-time)	—	End of leg (defaults to 1 day later).
`attributes`	object (free-form)	—	Custom metadata for the leg.

Sample Request

{
  "data": [
    {
      "id": "route_123",
      "name": "Morning Delivery Route",
      "startTime": "2024-01-15T09:00:00Z",
      "endTime": "2024-01-15T17:00:00Z",
      "attributes": {
        "vehicle_type": "delivery_truck",
        "priority": "high",
        "estimated_duration": 480
      },
      "legs": [
        {
          "id": "leg1",
          "start": "2024-01-15T09:00:00Z",
          "end": "2024-01-15T10:00:00Z",
          "locations": [
            {
              "geojsonGeometry": {
                "type": "LineString",
                "coordinates": [
                  [-73.985, 40.748],
                  [-73.987, 40.749],
                  [-73.989, 40.750]
                ]
              }
            }
          ],
          "attributes": { "leg_type": "pickup" }
        },
        {
          "id": "leg2",
          "start": "2024-01-15T10:00:00Z",
          "end": "2024-01-15T11:00:00Z",
          "locations": [
            {
              "geojsonGeometry": {
                "type": "Feature",
                "geometry": {
                  "type": "Point",
                  "coordinates": [-73.990, 40.750]
                }
              }
            }
          ],
          "attributes": { "leg_type": "delivery", "packages": 3 }
        }
      ]
    }
  ]
}

Responses

Code	Description	Body
`200`	Routes ingested successfully	`{ "message": string, "timestamp": date-time }`
`400`	Bad request — invalid data format	—
`401`	Unauthorized — authentication required	—
`500`	Internal server error	—

Integration Details

Authentication: You must include a valid API key in the request. Contact your account manager to obtain credentials and integration access.
Feed ID: A feed is used to organize and manage groups of related routes within the Tomorrow.io platform. Before uploading any asset data via the API, a feed must be created in your account. Each feed acts as a dedicated layer through which assets are ingested, displayed, and managed.
Limitations: You can submit up to 200 routes per API request.
Attributes: Used to store custom metadata. Each attribute must include a key and a value.