--- title: "Hourly and daily weather forecast (up to 16 days, worldwide)" method: GET path: "/api/v2/weather/forecast" tags: ["Environment"] --- # Hourly and daily weather forecast (up to 16 days, worldwide) `GET /api/v2/weather/forecast` Sugra Weather forecast for any coordinate or city worldwide: hourly steps and daily aggregates up to 16 days ahead (and up to 92 past days for context), covering temperature, feels-like, humidity, dew point, precipitation with probability, rain, showers, snowfall, snow depth, WMO weather code, pressure, cloud cover by level, visibility, wind with gusts, UV index, daylight, sunshine, solar radiation, and reference evapotranspiration. National high-resolution weather models are blended into a global best match for every location. Units, timezone, and time format are configurable. Resolve any city by name with the optional country filter. ## Query parameters - `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). - `forecast_days` integer — Forecast horizon in days (1-16). - `past_days` integer — Also include this many past days (0-92). - `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 (e.g. 'Asia/Tokyo'), or 'auto' to resolve from the location. - `timeformat` string — Timestamp format: iso8601 | unixtime. - `language` string — Locale for the human condition text (13 supported). ## Response `200` Hourly and daily forecast with per-variable units and provenance. - EnvelopeWeatherForecastV2 - `data` WeatherForecastV2, 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` ForecastHourlyEntry[] — Hourly forecast steps. - `time` union — Step time (ISO 8601 local to the response timezone, or epoch seconds with timeformat=unixtime). - 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 (wind chill and humidity combined). - `precipitation_probability` number, nullable — Probability of precipitation, percent. - `precipitation` number, nullable — Total precipitation (rain + showers + snow water equivalent). - `rain` number, nullable — Large-scale rain. - `showers` number, nullable — Convective showers. - `snowfall` number, nullable — Snowfall amount. - `snow_depth` number, nullable — Snow depth on the ground, metres. - `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. - `visibility` number, nullable — Viewing distance, metres. - `wind_speed_10m` number, nullable — 10 m wind speed. - `wind_direction_10m` number, nullable — 10 m wind direction, meteorological degrees. - `wind_gusts_10m` number, nullable — 10 m wind gusts. - `uv_index` number, nullable — UV index. - `uv_index_clear_sky` number, nullable — UV index assuming clear sky. - `is_day` integer, nullable — 1 when the step is in daylight, 0 at night. - `cape` number, nullable — Convective available potential energy, J/kg. - `freezing_level_height` number, nullable — 0 degree Celsius level height, metres. - `condition` string, nullable — Human condition text for weather_code, localized via the language parameter (WEATHER-2.5). - `condition_icon` string, nullable — Design-system (Lucide) icon key, day/night variant chosen by is_day. - `daily` ForecastDailyEntry[] — Daily forecast entries. - `date` union — Day (ISO 8601 date local to the response timezone, or epoch seconds with timeformat=unixtime). - 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. - `uv_index_max` number, nullable — Daily maximum UV index. - `uv_index_clear_sky_max` number, nullable — Daily maximum clear-sky UV index. - `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. - `precipitation_probability_max` number, nullable — Daily maximum precipitation probability, percent. - `precipitation_probability_min` number, nullable — Daily minimum precipitation probability, percent. - `precipitation_probability_mean` number, nullable — Daily mean precipitation probability, percent. - `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. JSON body with a stable `code` distinguishing `missing_api_key` (no header sent) from `invalid_api_key` (header sent, key not accepted); any other 401 source carries the generic `unauthorized` with its detail as `reason`. Plus `hint`. `plan` is always null on 401 - an unauthenticated request has no plan; quota exhaustion is 429, not 401. - `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/versions/4c4530760ba1/schema)