Tomorrow.io's Historical Climate Normals API provides comprehensive climate normals data, offering valuable insights into long-term climate trends and patterns. Climate Normals calculates and presents data for the period between 2000 and 2020.

Reference: https://docs.tomorrow.io/reference/historical-normals

Endpoint Details

Base URL (POST)

https://api.tomorrow.io/v4/historical/normals

Key Features

  • 20-Year Averages: Statistical weather data averaged over the period 2000-2020
  • Daily Aggregation: Climate normals with daily temporal resolution
  • Statistical Averages: Provides climate normal averages calculated across the 20-year period
  • Global Coverage: Available worldwide with high-resolution data
  • Date Range Queries: Request data for specific calendar date ranges

Data Period

Climate normals are calculated from weather data spanning 2000-2020 (20 years). The API returns statistical aggregations for each calendar day requested, representing the long-term average conditions for that specific date across all years in the period.

Request Parameters

URL Parameters

ParameterTypeRequiredDescriptionExample
apikeyStringRequiredYour Tomorrow.io API keyYOUR_API_KEY

Request Body Parameters

ParameterTypeRequiredDescriptionExample
locationString | [Number, Number] | GeoJSONRequiredID of a pre-defined location, GeoJSON geometry, or lat/long array. For polygon/polyline locations, defaults to Max values if suffix not specified."42.3478, -71.0466" or [42.3478, -71.0466] or GeoJSON
fieldsArray<String>RequiredArray of climate data fields to retrieve. See historical data fields reference for available climate normal fields.["temperatureAvg", "precipitationAccumulationSum"]
timestepsArray<String>RequiredArray of timestep intervals. Currently support the "1d" time step only.["1d"]
startDateStringRequiredStart date in MM-DD format. Climate normals only support "MM-DD" datetime format and is limited to 365 days. Data aggregated from 2000 to 2020."01-01"
endDateStringRequiredEnd date in MM-DD format. Climate normals only support "MM-DD" datetime format and is limited to 365 days. Data aggregated from 2000 to 2020."01-02"
unitsStringOptionalUnits for the response data (metric or imperial). Defaults to metric.metric

Example Request Body

Request Body Example

Example request body for getting climate normals

Response

JSON Request Body
{
  "location": "42.3478, -71.0466",
  "fields": [
    "temperatureAvg"
  ],
  "timesteps": [
    "1d"
  ],
  "startDate": "01-01",
  "endDate": "01-02",
  "units": "metric"
}

Response Structure

Response Format

The API returns climate normals data with average values for each requested field and date. Each field contains the statistical average calculated from the 20-year period (2000-2020).

Complete Response Hierarchy

API Response StructureTEXT
Tomorrow.io Climate Normals API Response
├── data/
│   └── timelines/
│       └── [timeline]/
│           ├── timestep ("1d")
│           ├── startDate (MM-DD format)
│           ├── endDate (MM-DD format)
│           └── intervals/
│               └── [interval]/
│                   ├── startDate (MM-DD format)
│                   └── values/
│                       ├── [requested field 1] (average value)
│                       ├── [requested field 2] (average value)
│                       └── ... (all requested fields)

Timeline Structure

  • timestep: Always "1d" (daily)
  • startDate/endDate: MM-DD format dates
  • intervals: Array of daily data points
  • values: Climate normal averages

Data Fields

  • • Only requested fields are returned
  • • Values are 20-year averages (2000-2020)
  • • Single numeric values (not complex objects)
  • • See historical data fields reference

Example Response

Climate Normals Response

Example response showing temperature averages for climate normals

Response

JSON Response
{
  "data": {
    "timelines": [
      {
        "timestep": "1d",
        "startDate": "01-01",
        "endDate": "01-02",
        "intervals": [
          {
            "startDate": "01-01",
            "values": {
              "temperatureAvg": -0.1
            }
          },
          {
            "startDate": "01-02",
            "values": {
              "temperatureAvg": -0.7
            }
          }
        ]
      }
    ]
  }
}

Usage & Limitations

Supported Features

  • Daily timesteps only: Currently supports "1d" time step
  • Multiple location formats: Pre-defined locations, GeoJSON geometry, or lat/long arrays
  • Multiple fields per request: Selected fields from historical data layers
  • MM-DD date format: Climate normals only support "MM-DD" datetime format
  • Metric and imperial units: Unit system support for field values

Limitations

  • Maximum 365 days per request: Date range limited to 365 days
  • Only daily timesteps: No hourly data available, only "1d" supported
  • Fixed data period: Climate normals aggregates data from 2000 to 2020 (cannot be customized)
  • MM-DD format only: Date format must be MM-DD without year specification
  • Polygon/polyline defaults: Default to Max values if suffix not specified

Use Cases

  • Climate Analysis: Long-term climate pattern analysis and research
  • Agricultural Planning: Crop planning based on historical climate averages
  • Infrastructure Design: Building and infrastructure planning considering climate norms
  • Baseline Comparisons: Comparing current conditions against historical averages
  • Risk Assessment: Climate risk evaluation for insurance and planning purposes

Examples

Boston Temperature Averages

Get climate normal temperature data for Boston, Massachusetts for the first two days of January:

cURL Request

Complete cURL command for fetching climate normals

Request

cURL Command
curl --request POST \
     --url 'https://api.tomorrow.io/v4/historical/normals?apikey=YOUR_API_KEY' \
     --compressed \
     --header 'Accept-Encoding: gzip, deflate' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "location": "42.3478, -71.0466",
  "fields": [
    "temperatureAvg"
  ],
  "timesteps": [
    "1d"
  ],
  "startDate": "01-01",
  "endDate": "01-02",
  "units": "metric"
}'

Response

JSON Response
{
  "data": {
    "timelines": [
      {
        "timestep": "1d",
        "startDate": "01-01",
        "endDate": "01-02",
        "intervals": [
          {
            "startDate": "01-01",
            "values": {
              "temperatureAvg": -0.1
            }
          },
          {
            "startDate": "01-02",
            "values": {
              "temperatureAvg": -0.7
            }
          }
        ]
      }
    ]
  }
}