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)

ParameterTypeRequiredDescriptionExample
apikeyStringRequiredYour Tomorrow.io API key for authenticationYOUR_API_KEY

Body Parameters (JSON)

ParameterTypeRequiredDescriptionExample
locationString | [Number, Number] | GeoJSONRequiredLocation as coordinates, GeoJSON geometry (Point, LineString, Polygon), or location string"boston" or [42.3478, -71.0466] or GeoJSON geometry
fieldsArray<String>RequiredArray of weather data fields to retrieve with support for aggregation suffixes (Max, Min, Avg)["temperature", "humidity", "windSpeed"]
timestepsArray<String>RequiredArray of timestep intervals (1h for hourly, 1d for daily)["1h"] or ["1d"]
startTimeStringRequiredHistorical timeline start time in ISO 8601 format2019-03-20T14:09:50Z
endTimeStringRequiredHistorical timeline end time in ISO 8601 format2019-03-28T14:09:50Z
unitsStringOptionalMeasurement units (metric or imperial)metric
timezoneStringOptionalIANA timezone name for response timesAmerica/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

API Response StructureTEXT
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 temperature
  • temperatureApparent - Feels-like temperature
  • humidity - Relative humidity
  • windSpeed - Wind speed
  • windDirection - Wind direction
  • precipitationIntensity - Precipitation rate
  • cloudCover - Cloud coverage
  • weatherCode - Weather condition code

Daily Aggregation Suffixes

  • fieldMax - Maximum value for the day
  • fieldMin - Minimum value for the day
  • fieldAvg - Average value for the day
  • Examples:
  • temperatureMax - Daily high temperature
  • temperatureMin - Daily low temperature
  • windSpeedAvg - 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
            }
          }
        ]
      }
    ]
  }
}