--- title: "Historical weather from 1940 (hourly and daily, worldwide)" method: GET path: "/api/v2/weather/history" tags: ["Environment"] --- # Historical weather from 1940 (hourly and daily, worldwide) `GET /api/v2/weather/history` Sugra Weather history for any coordinate or city worldwide, from 1940-01-01 to the recent past: daily aggregates (temperature and feels-like min/max/mean, sunrise/sunset, daylight and sunshine duration, precipitation sums and hours, wind maxima and dominant direction, solar radiation, reference evapotranspiration, WMO weather code) plus full hourly steps for ranges up to a year. Reanalysis-backed for every location on Earth. Units, timezone, and time format are configurable; resolve any city by name with the optional country filter. Ranges up to 10 years per request. ## Query parameters - `start_date` string, required — Range start, YYYY-MM-DD (1940-01-01 or later). - `end_date` string, required — Range end, YYYY-MM-DD (inclusive). - `latitude` number, nullable — Latitude (-90 to 90). - `longitude` number, nullable — Longitude (-180 to 180). - `lat` number, nullable — Latitude alias (same as latitude). - `lon` number, nullable — Longitude alias (same as longitude). - `city` string, nullable — City name (alternative to lat/lon), resolved globally. - `country` string, nullable — Country name or ISO-2 code (narrows the city match). - `temperature_unit` string — Temperature unit: celsius | fahrenheit. - `wind_speed_unit` string — Wind speed unit: kmh | ms | mph | kn. - `precipitation_unit` string — Precipitation unit: mm | inch. - `timezone` string — IANA timezone for timestamps, or 'auto'. - `timeformat` string — Timestamp format: iso8601 | unixtime. - `language` string — Locale for the human condition text (13 supported). ## Response `200` Daily (and hourly for ranges up to a year) archive with units and provenance. - EnvelopeWeatherHistoryV2 - `data` WeatherHistoryV2, required - `latitude` number, nullable — Grid-cell latitude the response is computed for. - `longitude` number, nullable — Grid-cell longitude the response is computed for. - `elevation` number, nullable — Grid-cell elevation, metres. - `timezone` string, nullable — Response timezone (IANA), resolved when 'auto'. - `timezone_abbreviation` string, nullable — Timezone abbreviation. - `utc_offset_seconds` integer, nullable — UTC offset of the response timezone, seconds. - `resolved_location` ResolvedLocation — What the global geocoder resolved a city query to. Null when lat/lon were given directly. - `name` string, nullable — Resolved place name. - `latitude` number, nullable — Resolved latitude, decimal degrees. - `longitude` number, nullable — Resolved longitude, decimal degrees. - `country` string, nullable — Country name. - `country_code` string, nullable — ISO 3166-1 alpha-2 country code. - `admin1` string, nullable — First-level administrative division. - `timezone` string, nullable — IANA timezone of the resolved place. - `population` integer, nullable — Population of the resolved place, when known. - `units` ForecastUnits — Unit label for every returned variable, keyed by variable name (echoes the requested unit system). - `hourly` object — Units for each hourly variable. - `daily` object — Units for each daily variable. - `hourly` HistoryHourlyEntry[] — Hourly archive steps. Included only for ranges up to 366 days - longer spans are daily-only (see hourly_note). - `time` union — Step time (ISO 8601 local to the response timezone, or epoch seconds). - integer - string - `temperature_2m` number, nullable — 2 m air temperature. - `relative_humidity_2m` number, nullable — 2 m relative humidity, percent. - `dew_point_2m` number, nullable — 2 m dew point temperature. - `apparent_temperature` number, nullable — Feels-like temperature. - `precipitation` number, nullable — Total precipitation. - `rain` number, nullable — Rain. - `showers` number, nullable — Convective showers. - `snowfall` number, nullable — Snowfall amount. - `snow_depth` number, nullable — Snow depth on the ground, metres (era-dependent). - `weather_code` integer, nullable — WMO weather interpretation code (0-99). - `pressure_msl` number, nullable — Mean sea-level pressure, hPa. - `surface_pressure` number, nullable — Surface pressure, hPa. - `cloud_cover` number, nullable — Total cloud cover, percent. - `cloud_cover_low` number, nullable — Low-level cloud cover, percent. - `cloud_cover_mid` number, nullable — Mid-level cloud cover, percent. - `cloud_cover_high` number, nullable — High-level cloud cover, percent. - `wind_speed_10m` number, nullable — 10 m wind speed. - `wind_direction_10m` number, nullable — 10 m wind direction, degrees. - `wind_gusts_10m` number, nullable — 10 m wind gusts. - `is_day` integer, nullable — 1 when the step is in daylight, 0 at night. - `sunshine_duration` number, nullable — Sunshine duration within the hour, seconds. - `shortwave_radiation` number, nullable — Shortwave solar radiation, W/m2. - `et0_fao_evapotranspiration` number, nullable — FAO-56 reference evapotranspiration. - `condition` string, nullable — Human condition text for weather_code, localized. - `condition_icon` string, nullable — Design-system (Lucide) icon key, day/night variant. - `hourly_note` string, nullable — Set when hourly was excluded because the range exceeds 366 days. - `daily` HistoryDailyEntry[] — Daily archive entries. - `date` union — Day (ISO 8601 date local to the response timezone, or epoch seconds). - integer - string - `weather_code` integer, nullable — Most significant WMO weather code of the day. - `temperature_2m_max` number, nullable — Daily maximum 2 m temperature. - `temperature_2m_min` number, nullable — Daily minimum 2 m temperature. - `temperature_2m_mean` number, nullable — Daily mean 2 m temperature. - `apparent_temperature_max` number, nullable — Daily maximum feels-like temperature. - `apparent_temperature_min` number, nullable — Daily minimum feels-like temperature. - `apparent_temperature_mean` number, nullable — Daily mean feels-like temperature. - `sunrise` union — Sunrise time. - integer - string - `sunset` union — Sunset time. - integer - string - `daylight_duration` number, nullable — Daylight duration, seconds. - `sunshine_duration` number, nullable — Sunshine duration, seconds. - `precipitation_sum` number, nullable — Daily precipitation sum. - `rain_sum` number, nullable — Daily rain sum. - `showers_sum` number, nullable — Daily showers sum. - `snowfall_sum` number, nullable — Daily snowfall sum. - `precipitation_hours` number, nullable — Hours with precipitation. - `wind_speed_10m_max` number, nullable — Daily maximum 10 m wind speed. - `wind_gusts_10m_max` number, nullable — Daily maximum 10 m wind gusts. - `wind_direction_10m_dominant` number, nullable — Dominant 10 m wind direction, degrees. - `shortwave_radiation_sum` number, nullable — Daily shortwave solar radiation sum, MJ/m2. - `et0_fao_evapotranspiration` number, nullable — Daily FAO-56 reference evapotranspiration, mm. - `condition` string, nullable — Human condition text for the day's weather_code, localized. - `condition_icon` string, nullable — Design-system (Lucide) icon key (day variant). - `provenance` WeatherV2Provenance — Per-section provenance: which engine produced this data block and under what licence. - `source` string, required — Machine source key. - `product` string, required — Sugra product surface this block belongs to. - `models` string, required — Model selection mode: national high-resolution models blended into a global best match for every coordinate. - `licence` string, required — Upstream data licence. - `attribution` string, required — Licence-mandated attribution string. - `generationtime_ms` number, nullable — Engine generation time for this response, ms. - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope. - `endpoint` string, required — Requested endpoint path. - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request. - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced. - `provider` string, required — API name and version. - `source` string, nullable — Identifier of the primary upstream source used for this response. - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response. - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data. - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried. - `cached` boolean, nullable — True when this response was served from the internal cache. - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data. ## Other responses - `401` — Missing or invalid `x-api-key` header. - `422` — Validation Error - `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window. - `503` — Upstream source is temporarily unavailable. Retry after a short delay. --- [API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/revisions/dcf7427e6897/schema)