Tomorrow.io LLM-Friendly Weather API Documentation

The Weather Timelines API is the most powerful and flexible endpoint, allowing you to create customized weather data timelines with specific fields, timesteps, and time ranges. It supports both simple coordinates and complex GeoJSON geometries for advanced spatial queries.

Reference: https://docs.tomorrow.io/reference/weather-timelines

Premium Feature

Advanced Geometries: Supports Point, LineString, and Polygon geometries with field aggregation (Max, Min, Avg) for spatial weather analysis. Premium feature for polygon/polyline queries.

Endpoint Details

Base URL

https://api.tomorrow.io/v4/timelines

Method: POST | Authentication: API Key (query parameter)

Parameters

Query Parameters (URL)

Parameter	Type	Required	Description	Example
`apikey`	String	Required	Your Tomorrow.io API key for authentication	`YOUR_API_KEY`

Body Parameters (JSON)

Parameter	Type	Required	Description	Example
`location`	String \| [Number, Number] \| GeoJSON	Required	Location as coordinates, address, or GeoJSON geometry (Point, LineString, Polygon) for spatial queries	`"42.3478, -71.0466" or "boston" or GeoJSON object`
`fields`	Array<String>	Required	Array of weather data fields to include in response with support for aggregation suffixes (Max, Min, Avg)	`["temperature", "precipitationIntensity", "windSpeed"]`
`timesteps`	Array<String>	Required	Array of timestep intervals: 1m, 5m, 15m, 30m, 1h, 1d, or current for precise temporal control	`["1h"] or ["1h", "1d"]`
`startTime`	String	Optional	Timeline start time as ISO 8601 string or relative time (now, nowMinus1d)	`"now" or "2023-06-10T00:00:00Z"`
`endTime`	String	Optional	Timeline end time as ISO 8601 string or relative time (nowPlus6h, nowPlus1d)	`"nowPlus6h" or "2023-06-17T00:00:00Z"`
`units`	String	Optional	Units for measurements (metric or imperial)	`"metric"`
`timezone`	String	Optional	IANA timezone name for response times	`"America/New_York"`
`dailyStartHour`	Number	Optional	Hour when daily aggregation starts (0-23)	`6`

Response Structure

The Weather Timelines API returns a flexible JSON structure organized by timesteps. The response contains only the fields you specify in your request, organized by the requested time intervals.

Complete Response Hierarchy

API Response StructureTEXT
Weather Timelines API Response Structure
├── data/
│   └── timelines/
│       ├── minutely[]/ (if minute timesteps requested)
│       │   ├── time (ISO 8601 timestamp)
│       │   └── values/
│       │       └── [requested fields only]
│       │           ├── temperature (°C/°F)
│       │           ├── precipitationIntensity (mm/h or in/h)
│       │           └── ... (other requested fields)
│       │
│       ├── hourly[]/ (if "1h" timestep requested)
│       │   ├── time (ISO 8601 timestamp)
│       │   └── values/
│       │       └── [requested fields only]
│       │           ├── temperature (°C/°F)
│       │           ├── humidity (%)
│       │           ├── windSpeed (m/s or mph)
│       │           └── ... (other requested fields)
│       │
│       └── daily[]/ (if "1d" timestep requested)
│           ├── time (ISO 8601 timestamp)
│           └── values/
│               └── [requested fields with aggregation]
│                   ├── temperatureMax (°C/°F)
│                   ├── temperatureMin (°C/°F)
│                   ├── temperatureAvg (°C/°F)
│                   └── ... (other requested fields)
│
└── location/
    ├── lat (latitude coordinate)
    ├── lon (longitude coordinate)
    └── name (location name, if applicable)

Data Fields

The Weather Timelines API requires you to specify which fields to retrieve. You can choose from all available weather data fields and apply aggregation suffixes for polygon/polyline queries.

Common Timeline Fields

temperature - Air temperature
temperatureApparent - Feels-like temperature
humidity - Relative humidity
windSpeed - Wind speed
windDirection - Wind direction
precipitationIntensity - Precipitation rate
cloudCover - Cloud coverage
weatherCode - Weather condition code

Spatial Aggregation

For Polygon/Polyline:
fieldMax - Maximum value in area
fieldMin - Minimum value in area
fieldAvg - Average value in area
Examples:
temperatureMax - Highest temp in polygon
temperatureMin - Lowest temp in polygon
windSpeedAvg - Average wind in area

Complete Field Reference

For a complete list of available weather data fields and their specifications, see the Core Data Fields reference.

Examples

Example 1: Boston Hourly Timeline (6 Hours)

Request

curl --request POST \
  --url 'https://api.tomorrow.io/v4/timelines?apikey=[API_KEY]' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
  "location": "42.3478, -71.0466",
  "fields": [
    "temperature"
  ],
  "units": "metric",
  "timesteps": [
    "1h"
  ],
  "startTime": "now",
  "endTime": "nowPlus6h",
  "dailyStartHour": 6
}'

Response

{
  "data": {
    "timelines": [
      {
        "timestep": "1h",
        "endTime": "2025-06-08T17:00:00Z",
        "startTime": "2025-06-08T11:00:00Z",
        "intervals": [
          {
            "startTime": "2025-06-08T11:00:00Z",
            "values": {
              "temperature": 17.2
            }
          },
          {
            "startTime": "2025-06-08T12:00:00Z",
            "values": {
              "temperature": 18
            }
          },
          {
            "startTime": "2025-06-08T13:00:00Z",
            "values": {
              "temperature": 19
            }
          },
          {
            "startTime": "2025-06-08T14:00:00Z",
            "values": {
              "temperature": 19.8
            }
          },
          {
            "startTime": "2025-06-08T15:00:00Z",
            "values": {
              "temperature": 19.8
            }
          },
          {
            "startTime": "2025-06-08T16:00:00Z",
            "values": {
              "temperature": 19.2
            }
          },
          {
            "startTime": "2025-06-08T17:00:00Z",
            "values": {
              "temperature": 19
            }
          }
        ]
      }
    ]
  }
}

Example 2: Manhattan Polygon Daily Timeline (3 Days)

Request

curl --request POST \
  --url 'https://api.tomorrow.io/v4/timelines?apikey=[API_KEY]' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
  "location": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -73.981,
          40.764
        ],
        [
          -73.958,
          40.764
        ],
        [
          -73.958,
          40.8
        ],
        [
          -73.981,
          40.8
        ],
        [
          -73.981,
          40.764
        ]
      ]
    ]
  },
  "fields": [
    "temperatureMax",
    "temperatureMin",
    "temperatureAvg"
  ],
  "units": "metric",
  "timesteps": [
    "1d"
  ],
  "startTime": "now",
  "endTime": "nowPlus3d"
}'

Response

{
  "data": {
    "timelines": [
      {
        "timestep": "1d",
        "endTime": "2025-06-11T10:00:00Z",
        "startTime": "2025-06-08T10:00:00Z",
        "intervals": [
          {
            "startTime": "2025-06-08T10:00:00Z",
            "values": {
              "temperatureAvg": 18.7,
              "temperatureMax": 23.9,
              "temperatureMin": 15.1
            }
          },
          {
            "startTime": "2025-06-09T10:00:00Z",
            "values": {
              "temperatureAvg": 16.9,
              "temperatureMax": 21,
              "temperatureMin": 15
            }
          },
          {
            "startTime": "2025-06-10T10:00:00Z",
            "values": {
              "temperatureAvg": 25,
              "temperatureMax": 30,
              "temperatureMin": 20
            }
          },
          {
            "startTime": "2025-06-11T10:00:00Z",
            "values": {
              "temperatureAvg": 26.2,
              "temperatureMax": 30,
              "temperatureMin": 20
            }
          }
        ]
      }
    ]
  }
}