Repository navigation
Releases
v0.4.0
Adds forecast_15minutely() for /api/v1/forecast/15minutely: up to 12 steps of 15 minutes, returned as FifteenMinuteForecast. With dataset="full" each step also carries the precipitation type and snow rate.
observation_latest(precipitation="latest") asks the station for its latest precipitation accumulations (prec=1). They arrive in Observation.precipitation as ObservedPrecipitation items, one per period the station reports (1h, 3h, 6h, 12h or 24h).
observation_latest(precipitation="hourly") asks for the past day's one-hour accumulations (prec=2). They arrive in Observation.hourly_precipitation as ObservedHourlyPrecipitation items with endtime, accum and prectype (rain, sleet, snow, hail, icing or undefined), and Observation.latest_hourly_precipitation returns the most recent hour. A station can skip hours, so the list can hold fewer than 24 items.
Without the option, the request and the result are unchanged, except that both lists are empty.
current(), observation_latest(), forecast_hourly(), forecast_daily() and forecast_15minutely() take a keyword-only rounding. The API rounds most values to whole numbers by default; rounding=0 returns decimals, for example a wind speed of 4.53 m/s instead of 5. Leaving it out sends nothing, so the API's default applies as before.
forecast_daily(dataset="full", ensemble=True) asks for the ensemble percentiles (ensemble=1). Each DailyForecast then carries max_temp_ensemble and min_temp_ensemble (keys p000, p025, p050, p075, p100) and precip_accum_ensemble (keys p010 to p090). Either parameter alone returns none of them.
On HTTP 429 rate_limited, the client waits the Retry-After time, if it is 5 seconds or less, and sends the request once more. A burst of 16 parallel requests on a Freemium key (10 per second) now succeeds: 6 of them wait 1 second. Other 429s, such as daily_quota_exceeded, raise straight away. ForecaRateLimitError gains error and retry_after.
Adds forecast_3hourly() for /api/v1/forecast/3hourly: up to 113 steps of 3 hours (14 days), returned as HourlyForecast. Precipitation and snow accumulate over the three hours ending at each step. It takes periods, dataset and rounding like forecast_hourly().
forecast_minutely() now returns a MinutelyForecastList, a list that also carries the response's resolution: 1 (minutes) where the forecast is a radar nowcast, 60 elsewhere. It is still a list, so existing code keeps working.
A legacy API key gets HTTP 403 with only {"message": "Product unavailable"} for a product missing from its plan. That now raises ForecaProductUnavailableError, like the current body, instead of ForecaAuthError.
v0.3.0
Adds ForecaProductUnavailableError, raised when the API answers 403 {"error": "product_unavailable"}: the key is valid, but its plan does not include the product, for example air quality.
That response used to raise ForecaAuthError, so a client took a good key for a rejected one. A 401, and a 403 with any other body, still raise ForecaAuthError. The new error subclasses ForecaError, not ForecaAuthError; code that caught ForecaAuthError for this case should catch ForecaProductUnavailableError.
v0.2.2
Narrows two percentage fields to int.
precipProb and cloudiness are whole numbers in every response: measured over 290 forecast steps across five climates, with no fractional value. thunderProb is not (46 of those 290 were fractional), so it stays a float.
Home Assistant's Forecast TypedDict declares precipitation_probability and cloud_coverage as int, so this lets an integration pass both straight through instead of rounding them on the way in.
v0.2.1
Fixes a day's request count and closes the last unvalidated request path.
UsageDay.hitswas always empty, sohits_on(date)reported no requests however many an account had made. A day in the monthly breakdown carries its total only underapis, with no top-levelhits, and the client read the field that is never there. The count is now summed fromapis, falls back to a top-levelhitsif one is present, and isNonewhen neither is — never a misleading zero.usage_month(month)interpolated the month into the request path without validation, so a caller could reach an arbitrary path on the API host with their own key attached. OnlyYYYY-MMis accepted now, matching how a location is already handled.
The test payloads for these endpoints are copies of real API responses; the hand-written ones they replace are what hid the first bug.
v0.2.0
Adds three endpoints to the client.
observation_latest(location)— latest measurements from the nearest reporting weather station, including its name, distance and elevation. The API returns stations nearest first.forecast_minutely(location)— one-minute precipitation rates for the next hour, radar-based in Europe and continental USA.usage_month(month)— the account's request total for a month with a per-day breakdown, plushits_on(date)for a single day.
Also hardens the location argument: only coordinates or a numeric location id are accepted, so a location can no longer alter the request path or query parameters.
v0.1.0
First release of pyforeca, an async Python client for the Foreca Weather API.
Endpoints: location lookup, current conditions, hourly and daily forecasts, and hourly and daily air quality. Typed dataclass models tolerant of new API fields, a weather symbol-code parser, and typed exceptions for auth, rate-limit and connection errors.
Get an API key by creating a free account at https://developer.foreca.com