Historical Weather API
The Historical Weather API allows you to query weather conditions for historical timeframes beyond the recent 24-hour period. Use this endpoint to access detailed historical weather data for any custom date range, with full field customization and support for complex geometries.
For the last 24 hours only: Use the Recent History API instead.
Historical Archive Data Model
The historical archive is based on a reanalysis model that blends past short-range weather forecasts with observations through advanced data assimilation techniques. The historical archive data deviates from the recent historical data -7 days since it is based on a different observation data assimilation system that incorporates a larger set of final observational records.
Processing Time: Our reanalysis model takes between 7 to 90 days to calculate the data fields. Please see the historical data field availability for specific timing information.
Information
POST Method Required: Unlike other endpoints, the Historical Weather API uses POST method with request body to handle complex location geometries and field selections.
Endpoint Details
Base URL
https://api.tomorrow.io/v4/historical
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, GeoJSON geometry (Point, LineString, Polygon), or location string | "boston" or [42.3478, -71.0466] or GeoJSON geometry |
fields | Array<String> | Required | Array of weather data fields to retrieve with support for aggregation suffixes (Max, Min, Avg) | ["temperature", "humidity", "windSpeed"] |
timesteps | Array<String> | Required | Array of timestep intervals (1h for hourly, 1d for daily) | ["1h"] or ["1d"] |
startTime | String | Required | Historical timeline start time in ISO 8601 format | 2019-03-20T14:09:50Z |
endTime | String | Required | Historical timeline end time in ISO 8601 format | 2019-03-28T14:09:50Z |
units | String | Optional | Measurement units (metric or imperial) | metric |
timezone | String | Optional | IANA timezone name for response times | America/New_York |
Response Structure
The Historical Weather API returns a timeline-based JSON structure organized by the requested timesteps. The response contains only the fields you specify in your request.
Complete Response Hierarchy
Historical Weather API Response Structure
├── timelines/
│ ├── hourly[]/ (if "1h" timestep requested)
│ │ ├── time (ISO 8601 timestamp)
│ │ └── values/
│ │ └── [requested fields only]
│ │ ├── temperature (°C/°F)
│ │ ├── humidity (%)
│ │ ├── windSpeed (m/s or mph)
│ │ ├── precipitationIntensity (mm/h or in/h)
│ │ └── ... (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 Historical Weather API requires you to specify which fields to retrieve. You can choose from all available weather data fields and apply aggregation suffixes for daily data.
Common Hourly Fields
temperature
- Air temperaturetemperatureApparent
- Feels-like temperaturehumidity
- Relative humiditywindSpeed
- Wind speedwindDirection
- Wind directionprecipitationIntensity
- Precipitation ratecloudCover
- Cloud coverageweatherCode
- Weather condition code
Daily Aggregation Suffixes
fieldMax
- Maximum value for the dayfieldMin
- Minimum value for the dayfieldAvg
- Average value for the day- Examples:
temperatureMax
- Daily high temperaturetemperatureMin
- Daily low temperaturewindSpeedAvg
- Average wind speed
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 Weather (4 Hours)
Request
curl --request POST \
--url 'https://api.tomorrow.io/v4/historical?apikey=[API_KEY]' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"location": "boston",
"fields": [
"temperature",
"humidity",
"windSpeed",
"windDirection"
],
"timesteps": [
"1h"
],
"startTime": "2019-03-20T14:00:00Z",
"endTime": "2019-03-20T18:00:00Z",
"units": "metric"
}'
Response
{
"data": {
"timelines": [
{
"timestep": "1h",
"endTime": "2019-03-20T18:00:00Z",
"startTime": "2019-03-20T14:00:00Z",
"intervals": [
{
"startTime": "2019-03-20T14:00:00Z",
"values": {
"humidity": 88,
"temperature": 24.72,
"windDirection": 36.26,
"windSpeed": 1.16
}
},
{
"startTime": "2019-03-20T15:00:00Z",
"values": {
"humidity": 88,
"temperature": 24.75,
"windDirection": 22.82,
"windSpeed": 1.15
}
},
{
"startTime": "2019-03-20T16:00:00Z",
"values": {
"humidity": 87,
"temperature": 24.61,
"windDirection": 17.36,
"windSpeed": 1.12
}
},
{
"startTime": "2019-03-20T17:00:00Z",
"values": {
"humidity": 87,
"temperature": 24.39,
"windDirection": 18.96,
"windSpeed": 1.02
}
},
{
"startTime": "2019-03-20T18:00:00Z",
"values": {
"humidity": 86,
"temperature": 24.28,
"windDirection": 20.94,
"windSpeed": 0.52
}
}
]
}
]
}
}
Example 2: Coordinates Daily Weather (5 Days, Imperial Units)
Request
curl --request POST \
--url 'https://api.tomorrow.io/v4/historical?apikey=[API_KEY]' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"location": [
42.3478,
-71.0466
],
"fields": [
"temperatureMax",
"temperatureMin",
"precipitationIntensity"
],
"timesteps": [
"1d"
],
"startTime": "2019-03-20T00:00:00Z",
"endTime": "2019-03-25T00:00:00Z",
"units": "imperial"
}'
Response
{
"data": {
"timelines": [
{
"timestep": "1d",
"endTime": "2019-03-22T00:00:00Z",
"startTime": "2019-03-20T00:00:00Z",
"intervals": [
{
"startTime": "2019-03-20T00:00:00Z",
"values": {
"humidity": 80,
"temperatureMax": 46.77,
"temperatureMin": 23.93,
"windSpeed": 6.41
}
},
{
"startTime": "2019-03-21T00:00:00Z",
"values": {
"humidity": 99,
"temperatureMax": 44.57,
"temperatureMin": 34.29,
"windSpeed": 9.32
}
},
{
"startTime": "2019-03-22T00:00:00Z",
"values": {
"humidity": 100,
"temperatureMax": 36.39,
"temperatureMin": 32.95,
"windSpeed": 12.13
}
}
]
}
]
}
}