Weather on Routes API
This endpoint takes the common output response of popular navigation service APIs (such as Google Maps and Mapbox) as legs (each represented by a location and the duration within that route segment), the startTime for the trip and the timestep in which the developer is interested to sample the conditions.
The result will be a collection of intervals specifying min/max/avg values throughout the route, with consideration to the context (time spent in each leg).
Note: Due to the size of the body, this endpoint does not work properly on our documentation website.
Endpoint Details
Weather on Routes
https://api.tomorrow.io/v4/routeHTTP Method
POST - This endpoint requires a POST request with JSON body containing route data.
Key Features
- • Accepts route data from popular navigation APIs
- • Returns weather intervals for each route segment
- • Considers time spent in each leg for accurate weather sampling
- • Supports multiple weather data fields
- • Customizable time intervals and units
How It Works
Input Processing
The API processes route data from navigation services, extracting geometry and duration information for each leg of your journey.
Weather Sampling
Weather conditions are sampled at specified time intervals, considering the time spent traveling through each route segment.
Contextual Analysis
The system accounts for travel speed and time spent in each location to provide accurate weather conditions for your specific journey timing.
Structured Output
Returns organized weather intervals for each leg, making it easy to understand conditions throughout your entire route.
Legs
A route is mainly defined by a set of legs, each with the geometry that defines it (Point, Polyline or Polygon) and the expected travel duration within it (in minutes).
Legs Structure Example
[
{
"duration": 54,
"location": {
"type": "LineString",
"coordinates": [
[-6.80897, 62.00000],
[-6.8047, 62.00069],
[-6.7996, 62.00181],
[-6.80149, 62.00293],
[-6.80207, 62.00349],
[-6.80226, 62.00375],
[-6.80237, 62.00414]
]
}
},
{
"location": {
"type": "LineString",
"coordinates": [
[100.0, 0.0],
[101.0, 0.0],
[101.0, 1.0],
[100.0, 1.0],
[100.0, 0.0]
]
},
"duration": 8
}
]Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
legs | Array<Object> | Required | Collection of route segments, each represented as a pair of location object and a duration (in minutes). Each leg must contain geometry (Point, Polyline or Polygon) and expected travel duration within it. | [{"duration":10,"location":{"type":"LineString","coordinates":[[...]]}}] |
fields | Array<String> | Required | Selected fields from our data layers (polygon/polyline default to Max, if no suffix is specified). Common fields include precipitationIntensity, temperature, windSpeed, humidity. | ["precipitationIntensity"] |
startTime | String | Optional | Start time in ISO 8601 format "2019-03-20T14:09:50Z" (defaults to now). This is when the journey begins. | 2024-01-15T14:09:50Z |
timestep | String | Optional | Timestep of the route: "5m", "10m", "15m", "30m", "60m". Determines the frequency of weather data points along the route. | 5m |
units | String | Optional | Unit system of the field values, either "metric" or "imperial" (defaults to metric). | metric |
timezone | String | Optional | Timezone of time values, according to IANA Timezone Names (defaults to UTC). | UTC |
apikey | String | Required | Your Tomorrow.io API key for authentication. | YOUR_API_KEY |
Examples
cURL Request
curl --location 'https://api.tomorrow.io/v4/route?units=metric&apikey=YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept-Encoding: deflate, gzip, br' \
--data '{
"startTime": "2024-01-15T14:09:50Z",
"legs": [
{
"duration": 10,
"location": {
"type": "LineString",
"coordinates": [
[34.78187, 32.08528],
[34.78182, 32.08529],
[34.78172, 32.08531],
[34.78164, 32.08531],
[34.78152, 32.08534],
[34.7809, 32.08549]
]
}
},
{
"duration": 5,
"location": {
"type": "LineString",
"coordinates": [
[34.7809, 32.08549],
[34.78098, 32.08583],
[34.78105, 32.08614],
[34.78117, 32.08684],
[34.78121, 32.08705],
[34.78135, 32.08769],
[34.78149, 32.08832]
]
}
}
],
"fields": ["precipitationIntensity"],
"timestep": "5m",
"units": "metric",
"timezone": "UTC"
}'Postman Pre-request Script
// Postman Pre-request Script Example
var moment = require('moment');
var now = moment.utc();
var startTime = moment.utc(now).add(60, 'minutes').toISOString();
var fields = ["precipitationIntensity"];
var timestep = "5m";
var legs = [
{
"duration": 10,
"location": {
"coordinates": [
[34.78187, 32.08528],
[34.78182, 32.08529],
[34.78172, 32.08531],
[34.78164, 32.08531],
[34.78152, 32.08534],
[34.7809, 32.08549]
],
"type": "LineString"
}
},
{
"duration": 5,
"location": {
"coordinates": [
[34.7809, 32.08549],
[34.78098, 32.08583],
[34.78105, 32.08614],
[34.78117, 32.08684],
[34.78121, 32.08705],
[34.78135, 32.08769],
[34.78149, 32.08832]
],
"type": "LineString"
}
}
];
var units = "metric";
var timezone = "UTC";
var body = {
startTime,
legs,
fields,
timestep,
units,
timezone
};
pm.environment.set('body', JSON.stringify(body));Response Format
The API returns weather intervals for each leg of your route, with timestamps and weather values at the specified timestep intervals.
Example Response
{
"data": {
"route": {
"startTime": "2024-01-15T15:09:50Z",
"legs": [
{
"duration": 10,
"location": {
"type": "LineString",
"coordinates": [
[
34.78187,
32.08528
],
[
34.78182,
32.08529
],
[
34.78172,
32.08531
],
[
34.78164,
32.08531
],
[
34.78152,
32.08534
],
[
34.7809,
32.08549
]
]
},
"intervals": [
{
"startTime": "2024-01-15T15:09:50Z",
"values": {
"precipitationIntensity": 0.12
}
},
{
"startTime": "2024-01-15T15:14:50Z",
"values": {
"precipitationIntensity": 0.08
}
},
{
"startTime": "2024-01-15T15:19:50Z",
"values": {
"precipitationIntensity": 0
}
}
]
},
{
"duration": 5,
"location": {
"type": "LineString",
"coordinates": [
[
34.7809,
32.08549
],
[
34.78098,
32.08583
],
[
34.78105,
32.08614
],
[
34.78117,
32.08684
],
[
34.78121,
32.08705
],
[
34.78135,
32.08769
],
[
34.78149,
32.08832
]
]
},
"intervals": [
{
"startTime": "2024-01-15T15:09:50Z",
"values": {
"precipitationIntensity": 0
}
},
{
"startTime": "2024-01-15T15:14:50Z",
"values": {
"precipitationIntensity": 0.03
}
}
]
}
]
}
}
}