Returns weather data for a single location and given day in the past

v1.0.0

Actual weather data for a single location and day in the past

The output contains actual weather data for each day up to 8 years in the past, and long-term statistics of selected weather variables aggregated over 40 years.

Location specification

The location of the weather data must be specified. There are two ways to do this:

Specify the GPS coordinates of the location using the parameters lat and lon.
OR specify the name of the place using the parameter place_id. To obtain the place_id for the location you want, please use endpoints /find_places_prefix (search by prefix) or /find_places (search by full name).

Note: For mountains, it is usually better to specify the place_id rather than the lat and lon. When you use place_id, you are guaranteed to receive data for the precise elevation of the peak. When you specify the coordinates, the elevation can be less precise.

Input

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      "description": "The UTC day of the data in the past. Specify in `YYYY-MM-DD` format, e.g. `2021-08-24`.\n"
    },
    "key": {
      "type": "string",
      "description": "Your unique API key. You can either specify it in this parameter, or set it in `X-API-Key` header."
    },
    "lat": {
      "type": "string",
      "description": "Latitude in format 12N, 12.3N, 12.3, or 13S, 13.2S, -13.4"
    },
    "lon": {
      "type": "string",
      "description": "Longitude in format 12E, 12.3E, 12.3, or 13W, 13.2W, -13.4"
    },
    "place_id": {
      "type": "string",
      "description": "Identifier of a place. To obtain the `place_id` for the location you want, please use endpoints `/find_places_prefix` (search by prefix) or `/find_places` (search by full name)."
    },
    "timezone": {
      "type": "string",
      "description": "Timezone to be used for the date fields. If not specified, local timezone of the location will be used.\nThe format is according to the tzinfo database, so values like `Europe/Prague` or `UTC` can be used.\nAlternatively you may use the value ``auto`` in which case the local timezone of the location is used.\nThe full list of valid timezone strings can be found [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List).\n"
    },
    "units": {
      "description": "Unit system to be used. The available values are:\n\n* `auto`: Select the system automatically, based on the forecast location.\n* `metric`: Metric (SI) units (`°C`, `mm/h`, `m/s`, `cm`, `km`, `hPa`).\n* `us`: Imperial units (`°F`, `in/h`, `mph`, `in`, `mi`, `Hg`).\n* `uk`: Same as ``metric``, except that visibility is in `miles` and wind speeds are in `mph`.\n* `ca`: Same as ``metric``, except that wind speeds are in `km/h` and pressure is in `kPa`.\n",
      "type": "object"
    }
  },
  "required": [
    "date"
  ],
  "additionalProperties": false
}

Output

{
  "type": "object",
  "required": [
    "data",
    "elevation",
    "lat",
    "lon",
    "statistics",
    "units"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "wind",
          "cloud_cover",
          "precipitation"
        ],
        "properties": {
          "cape": {
            "type": "integer",
            "description": "Convective available potential energy.\nUnit: J/kg"
          },
          "cloud_cover": {
            "type": "object",
            "properties": {
              "high": {
                "type": "integer",
                "description": "Percentage of sky covered by high clouds.\nUnit: %"
              },
              "low": {
                "type": "integer",
                "description": "Percentage of sky covered by low clouds.\nUnit: %"
              },
              "middle": {
                "type": "integer",
                "description": "Percentage of sky covered by middle clouds.\nUnit: %"
              },
              "total": {
                "type": "integer",
                "description": "Percentage of sky covered by clouds.\nUnit: %"
              }
            }
          },
          "date": {
            "type": "string",
            "format": "date-time",
            "description": "Datetime in YYYY-MM-DDTHH:MM:SS format."
          },
          "dew_point": {
            "type": "number",
            "description": "Units: metric = °C, us = °F, uk = °C, ca = °C"
          },
          "evaporation": {
            "type": "integer",
            "description": "Evaporation of liquid water into water vapor.\nUnit: mm/h"
          },
          "feels_like": {
            "type": "number",
            "description": "Feels like temperature.\nUnits: metric = °C, us = °F, uk = °C, ca = °C"
          },
          "humidity": {
            "type": "integer",
            "description": "Relative humidity.\nUnit: \\%"
          },
          "icon": {
            "type": "integer",
            "description": "Numeric identifier of the weather icon. The following values can appear:\n\n* 1 - Not available\n* 2 - Sunny\n* 3 - Mostly sunny\n* 4 - Partly sunny\n* 5 - Mostly cloudy\n* 6 - Cloudy\n* 7 - Overcast\n* 8 - Overcast with low clouds\n* 9 - Fog\n* 10 - Light rain\n* 11 - Rain\n* 12 - Possible rain\n* 13 - Rain shower\n* 14 - Thunderstorm\n* 15 - Local thunderstorms\n* 16 - Light snow\n* 17 - Snow\n* 18 - Possible snow\n* 19 - Snow shower\n* 20 - Rain and snow\n* 21 - Possible rain and snow\n* 22 - Rain and snow\n* 23 - Freezing rain\n* 24 - Possible freezing rain\n* 25 - Hail\n* 26 - Clear (night)\n* 27 - Mostly clear (night)\n* 28 - Partly clear (night)\n* 29 - Mostly cloudy (night)\n* 30 - Cloudy (night)\n* 31 - Overcast with low clouds (night)\n* 32 - Rain shower (night)\n* 33 - Local thunderstorms (night)\n* 34 - Snow shower (night)\n* 35 - Rain and snow (night)\n* 36 - Possible freezing rain (night)\n\nUnit: N/A"
          },
          "irradiance": {
            "type": "integer",
            "description": "Global downward short-wave radiation flux.\nUnit: W/m2"
          },
          "ozone": {
            "type": "integer",
            "description": "Total column of ozone.\nUnit: Dobson"
          },
          "precipitation": {
            "type": "object",
            "properties": {
              "total": {
                "type": "number",
                "description": "Total precipitation amount accumulated since last hour.\nUnits: metric = mm/h, us = inches per hour, uk = mm/h, ca = mm/h"
              },
              "type": {
                "type": "string",
                "format": "binary",
                "description": "Precipitation type, may be one of:\n\n* `none`, it there is no precipitation\n* `rain`\n* `snow`\n* `rain_snow`\n* `ice pellets`\n* `frozen rain`\n\nUnit: precipitation type"
              }
            }
          },
          "pressure": {
            "type": "number",
            "description": "Atmospheric pressure at mean sea level.\nUnits: metric = hPa, us = Hg, uk = hPa, ca = kPa"
          },
          "soil_temperature": {
            "type": "number",
            "description": "Units: metric = °C, us = °F, uk = °C, ca = °C"
          },
          "surface_temperature": {
            "type": "number",
            "description": "Units: metric = °C, us = °F, uk = °C, ca = °C"
          },
          "temperature": {
            "type": "number",
            "description": "Units: metric = °C, us = °F, uk = °C, ca = °C"
          },
          "weather": {
            "type": "string",
            "description": "String identifier of the weather icon, e.g. `light_rain`."
          },
          "wind": {
            "type": "object",
            "properties": {
              "angle": {
                "type": "integer",
                "description": "Wind direction in `N`, `NNE`, `NE`, ..., `NNW` format.\nUnit: deg"
              },
              "dir": {
                "type": "string",
                "format": "binary",
                "description": "Wind direction in `N`, `NNE`, `NE`, ..., `NNW` format.\nUnit: 16dir"
              },
              "gusts": {
                "type": "integer",
                "description": "Wind gust speed.\nUnits: metric = m/s, us = mph, uk = mph, ca = km/h"
              },
              "speed": {
                "type": "integer",
                "description": "Wind speed 10 metres above the ground.\nUnits: metric = m/s, us = mph, uk = mph, ca = km/h"
              }
            }
          },
          "wind_chill": {
            "type": "number",
            "description": "Windchill temperature.\nUnits: metric = °C, us = °F, uk = °C, ca = °C"
          }
        }
      }
    },
    "elevation": {
      "type": "integer",
      "description": "Elevation above sea level in metres (for units 'metric', 'uk', 'ca') or feet (for units 'us')"
    },
    "lat": {
      "type": "string",
      "description": "Latitude of the point, always in the format <float><N/S>, for example ``23.5S``"
    },
    "lon": {
      "type": "string",
      "description": "Longitude of the point, always in the format <float><E/W>, for example ``23.5W``"
    },
    "statistics": {
      "type": "object",
      "required": [
        "precipitation",
        "temperature",
        "wind"
      ],
      "properties": {
        "precipitation": {
          "type": "object",
          "properties": {
            "avg": {
              "type": "number",
              "description": "Long-term average daily precipitation amount.\nUnits: metric = mm/day, us = inches per day, uk = mm/day, ca = mm/day"
            },
            "probability": {
              "type": "integer",
              "description": "Long-term average precipitation probability.\nUnit: \\%"
            }
          }
        },
        "temperature": {
          "type": "object",
          "properties": {
            "avg": {
              "type": "number",
              "description": "Long-term temperature average.\nUnits: metric = °C, us = °F, uk = °C, ca = °C"
            },
            "avg_max": {
              "type": "number",
              "description": "Long-term daily maximum temperature average.\nUnits: metric = °C, us = °F, uk = °C, ca = °C"
            },
            "avg_min": {
              "type": "number",
              "description": "Long-term daily minimum temperature average.\nUnits: metric = °C, us = °F, uk = °C, ca = °C"
            },
            "record_max": {
              "type": "number",
              "description": "Historical daily maximum.\nUnits: metric = °C, us = °F, uk = °C, ca = °C"
            },
            "record_min": {
              "type": "number",
              "description": "Historical daily minimum temperature.\nUnits: metric = °C, us = °F, uk = °C, ca = °C"
            }
          }
        },
        "wind": {
          "type": "object",
          "properties": {
            "avg_angle": {
              "type": "number",
              "description": "Long-term average wind angle.\nUnit: deg"
            },
            "avg_dir": {
              "type": "string",
              "format": "binary",
              "description": "Long-term average wind direction in 'N', 'NNE', 'NE', ... 'NNW' format.\nUnit: 16dir"
            },
            "avg_speed": {
              "type": "number",
              "description": "Long-term average wind speed.\nUnits: metric = m/s, us = mph, uk = mph, ca = km/h"
            },
            "max_gust": {
              "type": "number",
              "description": "Historical daily maximum wind gust speed.\nUnits: metric = m/s, us = mph, uk = mph, ca = km/h"
            },
            "max_speed": {
              "type": "number",
              "description": "Historical daily maximum wind speed.\nUnits: metric = m/s, us = mph, uk = mph, ca = km/h"
            }
          }
        }
      }
    },
    "timezone": {
      "type": "string",
      "description": "Name of the timezone in format like 'Europe/London'. Available only when the place is specified through place ID."
    },
    "units": {
      "type": "string",
      "description": "Unit system (metric, uk, ca or us)"
    }
  }
}