Historical Climate Normals API
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
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
apikey | String | Required | Your Tomorrow.io API key | YOUR_API_KEY |
Request Body Parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
location | String | [Number, Number] | GeoJSON | Required | ID 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 |
fields | Array<String> | Required | Array of climate data fields to retrieve. See historical data fields reference for available climate normal fields. | ["temperatureAvg", "precipitationAccumulationSum"] |
timesteps | Array<String> | Required | Array of timestep intervals. Currently support the "1d" time step only. | ["1d"] |
startDate | String | Required | Start 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" |
endDate | String | Required | End 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" |
units | String | Optional | Units 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
{
"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
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
{
"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 --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
{
"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
}
}
]
}
]
}
}