---
title: Historical Weather APIs & Time-Series Analytics
version: 1.0.0
description: Retrieve historical weather conditions for a single past date, with records available from 1940 through the present. Returns daily aggregate figures (temperature max/min/mean, precipitation, wind speed and gusts, cloud cover, humidity, pressure, dew point) by default, or 24 hourly readings for that date when `precision=hourly` is passed, plus sunrise/sunset/moon-phase astronomy data on every response. Accepts a location as a city name or address, GPS coordinates via `lat`/`long`, or an IP address; when none of these is supplied the API geolocates the requesting client's IP address instead. `latitude`, `longitude`, and `elevation` in the location object are always returned as strings, never numbers. This endpoint accepts only a single `date` per request --- use the Time-Series Weather API for continuous multi-date ranges.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0/weather
paths: 1
operations: 1
schemas: 10
---

## Table of Contents

- [Historical Weather APIs & Time-Series Analytics v1.0.0](#historical-weather-apis-time-series-analytics-v100)
  - [Authentication](#authentication)
  - [Weather APIs](#weather-apis)
    - [getHistoricalData](#gethistoricaldata)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [HistoricalResponse](#historicalresponse)
    - [WeatherLocation](#weatherlocation)
    - [LocationByCoordinates](#locationbycoordinates)
    - [LocationByIP](#locationbyip)
    - [LocationByAddress](#locationbyaddress)
    - [HistoricalData](#historicaldata)
    - [HistoricalDaily](#historicaldaily)
    - [HistoricalHourly](#historicalhourly)
    - [Astronomy](#astronomy)
    - [ErrorResponse](#errorresponse)



# Historical Weather APIs & Time-Series Analytics v1.0.0

Retrieve historical weather conditions for a single past date, with records available from 1940 through the present. Returns daily aggregate figures (temperature max/min/mean, precipitation, wind speed and gusts, cloud cover, humidity, pressure, dew point) by default, or 24 hourly readings for that date when `precision=hourly` is passed, plus sunrise/sunset/moon-phase astronomy data on every response. Accepts a location as a city name or address, GPS coordinates via `lat`/`long`, or an IP address; when none of these is supplied the API geolocates the requesting client's IP address instead. `latitude`, `longitude`, and `elevation` in the location object are always returned as strings, never numbers. This endpoint accepts only a single `date` per request --- use the Time-Series Weather API for continuous multi-date ranges.

Base URLs:

* [https://api.apifreaks.com/v1.0/weather](https://api.apifreaks.com/v1.0/weather)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## Weather APIs

### getHistoricalData

`GET /historical`

*Retrieve historical weather conditions for a specific past date and location, coordinates, or IP address*

Return daily aggregate or hourly weather readings plus astronomy data for a single past date going back to 1940, resolved by city/address, GPS coordinates, or IP address.

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Format of the response. Possible values: json.|
|date|query|string(date)|true|Specific date for which to fetch weather data in YYYY-MM-DD format. Historical dates must be past dates only. Current or future dates are not allowed for historical data. Data available from 1940 onwards.|
|location|query|string|false|City name, place name, or full address to look up historical weather for. Ignored when lat/long is provided.|
|lat|query|number|false|Latitude of the location. Takes precedence over location and ip when more than one location parameter is supplied.|
|long|query|number|false|Longitude of the location. Must be provided together with lat.|
|ip|query|string|false|IPv4 or IPv6 address for location inference. Ignored when location or lat/long is provided; if none of location, lat/long, or ip is supplied, the requesting client's IP address is used instead.|
|precision|query|string|false|Precision of the returned historical data. Possible values: daily (aggregated daily figures), hourly (24 hourly readings for the date). Default: daily.|
|timezone|query|string|false|IANA timezone to render the astronomy time fields in, instead of the resolved location's own timezone. When set, sunrise/sunset/moonrise-type fields include the date (YYYY-MM-DD HH:MM) instead of only HH:MM.|

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|
|precision|daily|
|precision|hourly|

> Example responses

> Successful response

```json
{
  "location": {
    "location_string": "Lahore",
    "country_name": "Pakistan",
    "state_prov": "Punjab",
    "city": "Lahore",
    "locality": "",
    "latitude": "31.56568",
    "longitude": "74.31418",
    "elevation": "",
    "timezone": "Asia/Karachi",
    "timezone_abbreviation": "GMT+5"
  },
  "historical": {
    "daily": {
      "timestamp": "1940-10-10",
      "weather_code": 0,
      "temperature_2m_mean": 28.1,
      "temperature_2m_max": 37.9,
      "temperature_2m_min": 20.3,
      "apparent_temperature_mean": 25,
      "apparent_temperature_max": 36.5,
      "apparent_temperature_min": 16.8,
      "precipitation_sum": 0,
      "rain_sum": 0,
      "snowfall_sum": 0,
      "wind_speed_10m_max": 12.8,
      "wind_gusts_10m_max": 25.6,
      "wind_speed_10m_mean": 8.7,
      "wind_speed_10m_min": 3.9,
      "wind_gusts_10m_min": 9,
      "wind_gusts_10m_mean": 16.4,
      "wind_direction_10m_dominant": 80,
      "shortwave_radiation_sum": 20.09,
      "et0_fao_evapotranspiration_sum": 6.29,
      "cloud_cover_mean": 0,
      "dew_point_2m_mean": 0.1,
      "dew_point_2m_max": 5.5,
      "dew_point_2m_min": -3,
      "relative_humidity_2m_mean": 18,
      "relative_humidity_2m_max": 26,
      "relative_humidity_2m_min": 8,
      "pressure_msl_mean": 1010.2,
      "surface_pressure_mean": 986.1
    },
    "astronomy": {
      "date": "1940-10-10",
      "mid_night": "00:20",
      "night_end": "05:11",
      "sunrise": "06:30",
      "sunset": "18:08",
      "night_begin": "19:27",
      "sun_status": "-",
      "solar_noon": "12:19",
      "day_length": "11:38",
      "moon_phase": "WAXING_GIBBOUS",
      "moonrise": "14:40",
      "moonset": "01:07",
      "moon_status": "-"
    }
  }
}
```

```json
{
  "location": {
    "location_string": "Lahore",
    "country_name": "Pakistan",
    "state_prov": "Punjab",
    "city": "Lahore",
    "locality": "",
    "latitude": "31.56568",
    "longitude": "74.31418",
    "elevation": "",
    "timezone": "Asia/Karachi",
    "timezone_abbreviation": "GMT+5"
  },
  "historical": {
    "hourly": [
      {
        "timestamp": "2020-05-15T00:00",
        "temperature_2m": 22.7,
        "relative_humidity_2m": 79,
        "dew_point_2m": 18.9,
        "apparent_temperature": 25,
        "precipitation": 0,
        "rain": 0,
        "snowfall": 0,
        "weather_code": 1,
        "pressure_msl": 1007.9,
        "surface_pressure": 983.4,
        "cloud_cover": 30,
        "et0_fao_evapotranspiration": 0.01,
        "wind_speed_10m": 6.2,
        "wind_direction_10m": 280,
        "wind_gusts_10m": 9.4,
        "albedo": null,
        "shortwave_radiation": 0,
        "direct_radiation": 0,
        "diffuse_radiation": 0,
        "direct_normal_irradiance": 0,
        "global_tilted_irradiance": 0
      }
    ],
    "astronomy": {
      "date": "2020-05-15",
      "mid_night": "23:59",
      "night_end": "03:33",
      "sunrise": "05:04",
      "sunset": "18:54",
      "night_begin": "20:25",
      "sun_status": "-",
      "solar_noon": "11:59",
      "day_length": "13:49",
      "moon_phase": "LAST_QUARTER",
      "moonrise": "01:15",
      "moonset": "12:19",
      "moon_status": "-"
    }
  }
}
```

> Bad Request --- Missing/invalid date, missing/incomplete lat+long pair, coordinates out of range, invalid IP address, invalid precision, or invalid timezone

```json
{
  "error": "Invalid Param Exception",
  "message": "please pass correct parameters",
  "path": "/v1.0/weather/historical",
  "status": 400,
  "timestamp": "2026-07-24T11:34:39.124Z"
}
```

```json
{
  "timestamp": "2026-07-24T11:35:11.805Z",
  "status": 400,
  "message": "date must be in yyyy-mm-dd format",
  "error": "invalid-params",
  "path": "/v1.0/weather/historical"
}
```

```json
{
  "timestamp": "2026-07-24T11:34:39.625Z",
  "status": 400,
  "message": "date cannot be current or future date",
  "error": "params-exception-error",
  "path": "/v1.0/weather/historical"
}
```

```json
{
  "timestamp": "2026-07-24T11:34:41.411Z",
  "status": 400,
  "message": "Parameter 'startDate' is out of allowed range from 1940-01-01 to 2026-07-24",
  "error": "error",
  "path": "/v1.0/weather/historical"
}
```

```json
{
  "timestamp": "2026-07-24T11:34:54.240Z",
  "status": 400,
  "message": "Invalid latitude or longitude values. Latitude must be between -90 and 90, and longitude must be between -180 and 180",
  "error": "invalid-params",
  "path": "/v1.0/weather/historical"
}
```

```json
{
  "timestamp": "2026-07-24T11:34:55.197Z",
  "status": 400,
  "message": "Invalid IP address",
  "error": "invalid-params",
  "path": "/v1.0/weather/historical"
}
```

```json
{
  "timestamp": "2026-07-24T11:34:55.671Z",
  "status": 400,
  "message": "Invalid precision",
  "error": "invalid-params",
  "path": "/v1.0/weather/historical"
}
```

```json
{
  "timestamp": "2026-07-24T11:35:12.335Z",
  "status": 400,
  "message": "Check whether your input value is correct; timezone = NotATimezone",
  "error": "error",
  "path": "/v1.0/weather/historical"
}
```

> Not Found --- Location could not be resolved

```json
{
  "timestamp": "2026-07-24T11:34:53.747Z",
  "status": 404,
  "message": "Location not found",
  "error": "error",
  "path": "/v1.0/weather/historical"
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful response|[HistoricalResponse](#historicalresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request --- Missing/invalid date, missing/incomplete lat+long pair, coordinates out of range, invalid IP address, invalid precision, or invalid timezone|[ErrorResponse](#errorresponse)|
|404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not Found --- Location could not be resolved|[ErrorResponse](#errorresponse)|

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|404|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### HistoricalResponse

Historical weather response containing location data and historical weather data for the requested date.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|location|[WeatherLocation](#weatherlocation)|true|none|Location information. The shape of this object varies by lookup method.|
|historical|[HistoricalData](#historicaldata)|true|none|Historical weather data for the requested date, containing an astronomy block plus one of daily or hourly readings depending on the precision parameter. It is not keyed by date --- each request covers exactly one date.|

### WeatherLocation

Location information. The shape of this object varies by lookup method.

#### Properties

oneOf

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[LocationByCoordinates](#locationbycoordinates)|false|none|Location data when the target is specified by GPS coordinates (lat/long).|

xor

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[LocationByIP](#locationbyip)|false|none|Location data when the target is inferred from an IP address.|

xor

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[LocationByAddress](#locationbyaddress)|false|none|Location data when the target is specified by a city name or address string.|

### LocationByCoordinates

Location data when the target is specified by GPS coordinates (lat/long). country_name, state_prov, and city are omitted when the coordinates do not resolve to any political boundary (e.g. open ocean).

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|latitude|string|true|none|Geographic latitude coordinate in decimal degrees, ranging from -90 (South Pole) to +90 (North Pole). Returned as a string, not a number.|
|longitude|string|true|none|Geographic longitude coordinate in decimal degrees, ranging from -180 (West) to +180 (East). Returned as a string, not a number.|
|country_name|string|false|none|Full name of the country corresponding to the provided coordinates.|
|state_prov|string|false|none|State, province, or primary administrative division name for the location.|
|city|string|false|none|City or municipal area name associated with the coordinate location.|
|locality|string|false|none|Specific locality, neighborhood, district, or village name within the broader area.|
|elevation|string|false|none|Height above mean sea level in meters for the specified coordinates. Returned as a string, not a number; can be an empty string when unavailable.|
|timezone|string|true|none|IANA timezone database identifier for the location (e.g., America/New_York, Europe/London).|
|timezone_abbreviation|string|true|none|Abbreviated timezone representation based on current offset (e.g., EST, GMT, PST).|

### LocationByIP

Location data when the target is inferred from an IP address.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|continent_code|string|true|none|Two-letter continent code (e.g., NA for North America, EU for Europe, AS for Asia).|
|continent_name|string|true|none|Full name of the continent where the IP address is registered.|
|country_code2|string|true|none|ISO 3166-1 alpha-2 two-letter country code (e.g., US, GB, FR).|
|country_code3|string|true|none|ISO 3166-1 alpha-3 three-letter country code (e.g., USA, GBR, FRA).|
|country_name|string|true|none|Common name of the country associated with the IP address.|
|country_name_official|string|true|none|Official long-form country name as recognized internationally (e.g., United States of America).|
|is_eu|boolean|false|none|Boolean flag indicating whether the country is a member state of the European Union.|
|state_prov|string|true|none|State, province, or primary administrative division associated with the IP location.|
|state_code|string|false|none|ISO 3166-2 subdivision code for the state or province (e.g., CA for California).|
|district|string|false|none|District, county, or secondary administrative division within the region.|
|city|string|true|none|City or urban area name where the IP address is geographically registered.|
|zipcode|string|false|none|Postal code or ZIP code for the approximate location of the IP address.|
|latitude|string|true|none|Geographic latitude in decimal degrees for the IP geolocation, ranging from -90 to +90. Returned as a string, not a number.|
|longitude|string|true|none|Geographic longitude in decimal degrees for the IP geolocation, ranging from -180 to +180. Returned as a string, not a number.|
|locality|string|false|none|Specific locality, neighborhood, or small area designation within the city.|
|elevation|string|false|none|Elevation above mean sea level in meters for the IP geolocation. Returned as a string, not a number; can be an empty string when unavailable.|
|timezone|string|true|none|IANA timezone database identifier for the IP location (e.g., America/Chicago, Asia/Tokyo).|
|timezone_abbreviation|string|true|none|Current timezone abbreviation based on local offset (e.g., CST, JST, UTC).|

### LocationByAddress

Location data when the target is specified by a city name or address string.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|location_string|string|true|none|Original location query string as submitted, including full address or place name.|
|country_name|string|true|none|Resolved country name derived from the geocoded location query.|
|state_prov|string|true|none|State, province, or primary administrative division identified from the location.|
|city|string|true|none|City or municipal area name extracted from the geocoded location.|
|locality|string|false|none|Specific locality, neighborhood, suburb, or village within the geocoded area.|
|latitude|string|true|none|Geocoded latitude coordinate in decimal degrees, ranging from -90 to +90. Returned as a string, not a number.|
|longitude|string|true|none|Geocoded longitude coordinate in decimal degrees, ranging from -180 to +180. Returned as a string, not a number.|
|elevation|string|false|none|Elevation above mean sea level in meters at the geocoded coordinates. Returned as a string, not a number; can be an empty string when unavailable.|
|timezone|string|true|none|IANA timezone database identifier for the geocoded location (e.g., America/Los_Angeles).|
|timezone_abbreviation|string|true|none|Current timezone abbreviation for the location based on local offset (e.g., PDT, CET).|

### HistoricalData

Historical weather data for the requested date, containing an astronomy block plus one of daily or hourly readings depending on the precision parameter. It is not keyed by date --- each request covers exactly one date.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|daily|[HistoricalDaily](#historicaldaily)|false|none|Daily aggregate weather data for the requested day. Present when precision is daily (the default).|
|hourly|[[HistoricalHourly](#historicalhourly)]|false|none|Hourly weather readings for the requested day, one entry per hour (24 entries). Present when precision is hourly.|
|astronomy|[Astronomy](#astronomy)|true|none|Astronomical data for the requested day. Always present regardless of precision.|

### HistoricalDaily

Daily historical weather summary with temperature, precipitation, wind, and radiation statistics.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|timestamp|string(date)|true|none|The requested date in YYYY-MM-DD format.|
|weather_code|integer|true|none|WMO weather condition code representing the day's dominant conditions. Supported codes: 0 clear sky; 1, 2, 3 varying cloud cover; 45, 48 fog; 51, 53, 55 drizzle; 56, 57 freezing drizzle; 61, 63, 65 rain; 66, 67 freezing rain; 71, 73, 75 snowfall; 77 snow grains; 80, 81, 82 rain showers; 85, 86 snow showers; 95 thunderstorm; 96, 99 thunderstorm with hail.|
|temperature_2m_mean|number|true|none|Daily mean air temperature at 2 meters (°C).|
|temperature_2m_max|number|true|none|Daily maximum air temperature at 2 meters (°C).|
|temperature_2m_min|number|true|none|Daily minimum air temperature at 2 meters (°C).|
|apparent_temperature_mean|number|true|none|Daily mean perceived temperature (°C).|
|apparent_temperature_max|number|true|none|Daily maximum perceived temperature (°C).|
|apparent_temperature_min|number|true|none|Daily minimum perceived temperature (°C).|
|precipitation_sum|number|true|none|Total precipitation (mm).|
|rain_sum|number|true|none|Total rainfall (mm).|
|snowfall_sum|number|true|none|Total snowfall (cm).|
|wind_speed_10m_max|number|true|none|Maximum wind speed at 10 meters (km/h).|
|wind_gusts_10m_max|number|true|none|Maximum wind gusts at 10 meters (km/h).|
|wind_speed_10m_mean|number|true|none|Daily mean wind speed at 10 meters (km/h).|
|wind_speed_10m_min|number|true|none|Minimum wind speed at 10 meters (km/h).|
|wind_gusts_10m_min|number|true|none|Minimum wind gusts at 10 meters (km/h).|
|wind_gusts_10m_mean|number|true|none|Daily mean wind gusts at 10 meters (km/h).|
|wind_direction_10m_dominant|integer|true|none|Dominant wind direction at 10 meters (°).|
|shortwave_radiation_sum|number|true|none|Daily sum of shortwave solar radiation (MJ/m²).|
|et0_fao_evapotranspiration_sum|number|true|none|Daily sum of reference evapotranspiration (mm).|
|cloud_cover_mean|number|true|none|Daily mean cloud cover percentage (%).|
|dew_point_2m_mean|number|true|none|Daily mean dew point temperature at 2 meters (°C).|
|dew_point_2m_max|number|true|none|Daily maximum dew point temperature at 2 meters (°C).|
|dew_point_2m_min|number|true|none|Daily minimum dew point temperature at 2 meters (°C).|
|relative_humidity_2m_mean|number|true|none|Daily mean relative humidity at 2 meters (%).|
|relative_humidity_2m_max|integer|true|none|Daily maximum relative humidity at 2 meters (%).|
|relative_humidity_2m_min|integer|true|none|Daily minimum relative humidity at 2 meters (%).|
|pressure_msl_mean|number|true|none|Daily mean atmospheric pressure at mean sea level (hPa).|
|surface_pressure_mean|number|true|none|Daily mean surface pressure at ground level (hPa).|

##### Enumerated Values

|Property|Value|
|---|---|
|weather_code|0|
|weather_code|1|
|weather_code|2|
|weather_code|3|
|weather_code|45|
|weather_code|48|
|weather_code|51|
|weather_code|53|
|weather_code|55|
|weather_code|56|
|weather_code|57|
|weather_code|61|
|weather_code|63|
|weather_code|65|
|weather_code|66|
|weather_code|67|
|weather_code|71|
|weather_code|73|
|weather_code|75|
|weather_code|77|
|weather_code|80|
|weather_code|81|
|weather_code|82|
|weather_code|85|
|weather_code|86|
|weather_code|95|
|weather_code|96|
|weather_code|99|

### HistoricalHourly

Hourly historical weather reading with temperature, precipitation, and wind data.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|timestamp|string|true|none|Local timestamp for this hourly reading, in `YYYY-MM-DDTHH:mm` format — not full ISO 8601 (no seconds, no timezone offset/`Z`).|
|temperature_2m|number|true|none|Air temperature at 2 meters (°C).|
|relative_humidity_2m|number|true|none|Relative humidity at 2 meters (%).|
|dew_point_2m|number|true|none|Dew point temperature at 2 meters (°C).|
|apparent_temperature|number|true|none|Perceived temperature (°C).|
|precipitation|number|true|none|Total precipitation in this hour (mm).|
|rain|number|true|none|Rainfall in this hour (mm).|
|snowfall|number|true|none|Snowfall in this hour (cm).|
|weather_code|integer|true|none|WMO weather condition code representing conditions during this hour. Supported codes: 0 clear sky; 1, 2, 3 varying cloud cover; 45, 48 fog; 51, 53, 55 drizzle; 56, 57 freezing drizzle; 61, 63, 65 rain; 66, 67 freezing rain; 71, 73, 75 snowfall; 77 snow grains; 80, 81, 82 rain showers; 85, 86 snow showers; 95 thunderstorm; 96, 99 thunderstorm with hail.|
|pressure_msl|number|true|none|Atmospheric pressure at mean sea level (hPa).|
|surface_pressure|number|true|none|Atmospheric pressure at ground level (hPa).|
|cloud_cover|number|true|none|Cloud cover percentage (%).|
|et0_fao_evapotranspiration|number|true|none|Hourly reference evapotranspiration (mm).|
|wind_speed_10m|number|true|none|Wind speed at 10 meters (km/h).|
|wind_direction_10m|integer|true|none|Wind direction at 10 meters (°).|
|wind_gusts_10m|number|true|none|Wind gusts at 10 meters (km/h).|
|albedo|number|true|none|Reflectivity of the Earth's surface. Currently always returned as null.|
|shortwave_radiation|number|true|none|Incoming shortwave solar radiation (W/m²).|
|direct_radiation|number|true|none|Direct solar radiation (W/m²).|
|diffuse_radiation|number|true|none|Diffuse solar radiation (W/m²).|
|direct_normal_irradiance|number|true|none|Direct solar irradiance (W/m²).|
|global_tilted_irradiance|number|true|none|Total solar irradiance on a tilted surface (W/m²).|

##### Enumerated Values

|Property|Value|
|---|---|
|weather_code|0|
|weather_code|1|
|weather_code|2|
|weather_code|3|
|weather_code|45|
|weather_code|48|
|weather_code|51|
|weather_code|53|
|weather_code|55|
|weather_code|56|
|weather_code|57|
|weather_code|61|
|weather_code|63|
|weather_code|65|
|weather_code|66|
|weather_code|67|
|weather_code|71|
|weather_code|73|
|weather_code|75|
|weather_code|77|
|weather_code|80|
|weather_code|81|
|weather_code|82|
|weather_code|85|
|weather_code|86|
|weather_code|95|
|weather_code|96|
|weather_code|99|

### Astronomy

Astronomical data including sunrise, sunset, solar noon, day length, moon phase, and moon times. Time fields are HH:MM by default; when the timezone query parameter is set, they include the date as well (YYYY-MM-DD HH:MM).

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|date|string(date)|true|none|Calendar date in YYYY-MM-DD format for the astronomical data.|
|mid_night|string|true|none|Time of true solar midnight in HH:MM format.|
|night_end|string|true|none|Time when astronomical twilight ends and dawn begins in HH:MM format.|
|sunrise|string|true|none|Time when the Sun becomes visible above the horizon in HH:MM format.|
|solar_noon|string|true|none|Time when the Sun reaches its highest point in the sky in HH:MM format.|
|sunset|string|true|none|Time when the Sun disappears below the horizon in HH:MM format.|
|night_begin|string|true|none|Time when astronomical twilight begins and night starts in HH:MM format.|
|day_length|string|true|none|Total duration of daylight in HH:MM format.|
|sun_status|string|true|none|Current position of the Sun relative to the horizon (above_horizon, below_horizon, or -).|
|moon_phase|string|true|none|Current lunar phase (NEW_MOON, WAXING_CRESCENT, FULL_MOON, WANING_GIBBOUS, etc.).|
|moonrise|string|true|none|Time when the Moon becomes visible above the horizon in HH:MM format.|
|moonset|string|true|none|Time when the Moon disappears below the horizon in HH:MM format.|
|moon_status|string|true|none|Current visibility status of the Moon (visible, not_visible, or -).|

### ErrorResponse

Standard error envelope returned by the API on failed requests.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type.|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path that produced the error.|
|status|integer|false|none|HTTP status code returned with the error.|
|timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|