---
updatedAt: 2025-06-04T20:42:21.000Z
agentTools:
  projectIndex: https://docs.tomorrow.io/llms.txt
---

# Retrieve Historical Weather

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "tomorrowio-api",
    "version": "4.0.1"
  },
  "servers": [
    {
      "url": "https://api.tomorrow.io/v4"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "query",
        "name": "apikey"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/historical": {
      "post": {
        "summary": "Retrieve Historical Weather",
        "description": "",
        "operationId": "retrieve-historical-timelines",
        "parameters": [
          {
            "name": "Accept-Encoding",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "default": "gzip, deflate"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "location",
                  "fields",
                  "timesteps",
                  "startTime",
                  "endTime"
                ],
                "properties": {
                  "location": {
                    "type": "string",
                    "description": "ID of a pre-defined location, GeoJSON geometry or lat long array - see [formats](https://docs.tomorrow.io/reference/api-formats#locations)",
                    "default": "42.3478, -71.0466",
                    "format": "json"
                  },
                  "fields": {
                    "type": "array",
                    "description": "Selected fields from our data layers (polygon/polyline default to Max, if not suffix is not specified) - see [Historical Data Layers](https://docs.tomorrow.io/reference/historical)",
                    "default": [
                      "temperature"
                    ],
                    "items": {
                      "type": "string"
                    }
                  },
                  "timesteps": {
                    "type": "array",
                    "description": "Timesteps of the historical: \"1h\" or \"1d\" (defaults to \"1h\"). \"1d\" timesteps will default select the Max value of the fields. Only 1 timestep can be requested in each API call",
                    "default": [
                      "1h"
                    ],
                    "items": {
                      "type": "string"
                    }
                  },
                  "startTime": {
                    "type": "string",
                    "description": "Start time can be \"nowMinus`X`m/h/d\" or ISO 8601 format \"2019-03-20T14:09:50Z\".",
                    "default": "2019-03-20T14:09:50Z"
                  },
                  "endTime": {
                    "type": "string",
                    "description": "End time can be \"nowMinus`X`m/h/d\" or ISO 8601 format \"2019-03-20T14:09:50Z\".",
                    "default": "2019-03-28T14:09:50Z"
                  },
                  "units": {
                    "type": "string",
                    "description": "Unit system of the field values, either \"metric\" or \"imperial\" - see [Field Descriptors](https://docs.tomorrow.io/reference/weather-data-layers#field-descriptors)",
                    "default": "metric"
                  },
                  "timezone": {
                    "type": "string",
                    "description": "The timezone parameter displays the response datetime in the requested timezone. The timezone parameter is not affecting the request startTime and endTime. If you like to request data at a specific timezone, please add the timezone (in ISO 8601 format) to the startTime and endTime parameters. Timezone of time values, according to IANA Timezone Names (defaults to UTC) - see [Formats](https://docs.tomorrow.io/reference/api-formats#timezone)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"data\": {\n        \"timelines\": [\n            {\n                \"timestep\": \"1d\",\n                \"endTime\": \"2017-08-28T07:00:00-04:00\",\n                \"startTime\": \"2017-08-13T07:00:00-04:00\",\n                \"intervals\": [\n                    {\n                        \"startTime\": \"2017-08-13T07:00:00-04:00\",\n                        \"values\": {\n                            \"humidity\": 86.19,\n                            \"temperature\": 89.53,\n                            \"precipitationAccumulation\": 0,\n                            \"windSpeed\": 17,\n                            \"windSpeed100\": 22.35\n                        }\n                    },\n                    {\n                        \"startTime\": \"2017-08-14T07:00:00-04:00\",\n                        \"values\": {\n                            \"humidity\": 84.83,\n                            \"temperature\": 89.25,\n                            \"precipitationAccumulation\": 0,\n                            \"windSpeed\": 18.13,\n                            \"windSpeed100\": 23.24\n                        }\n                    },\n                  {...},\n                    {\n                        \"startTime\": \"2017-08-28T07:00:00-04:00\",\n                        \"values\": {\n                            \"humidity\": 90.11,\n                            \"temperature\": 71.77,\n                            \"precipitationAccumulation\": 0.07,\n                            \"windSpeed\": 21.36,\n                            \"windSpeed100\": 31.58\n                        }\n                    }\n                ]\n            }\n        ]\n    }\n}"
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```