pyforeca

Async Python client for the Foreca Weather API — current conditions, hourly and daily forecasts, air quality and location lookup, with typed models and aiohttp under the hood.

Getting an API key

Create a free account at developer.foreca.com, pick a plan, and copy your key from My API. The Freemium plan is free for non-commercial use (hobbyist, student, and research projects); commercial use, a larger quota, or the rest of Foreca's weather products need a paid plan.

Install

pip install pyforeca

Usage

import asyncio
from pyforeca import ForecaApiClient, format_location

async def main() -> None:
    async with ForecaApiClient("YOUR_API_KEY") as client:
        location = format_location(lon=24.94, lat=60.17)

        current = await client.current(location)
        print(current.temperature, current.symbol_phrase)

        daily = await client.forecast_daily(location, periods=7)
        hourly = await client.forecast_hourly(location, periods=24)
        air_quality = await client.air_quality_hourly(location, periods=1)

asyncio.run(main())

Pass an existing aiohttp.ClientSession as session= to share one with your application; the client then leaves closing it to you.

location is "longitude,latitude" (longitude first) or a Foreca location id. The API rounds most values to whole numbers; pass rounding=0 to current, observation_latest and the forecast calls for decimals. With precipitation="latest", observation_latest also returns the station's latest precipitation accumulations; with precipitation="hourly", the past day's one-hour accumulations, each with its precipitation type. With dataset="full" and ensemble=True, forecast_daily also returns the ensemble percentiles of each day's maximum and minimum temperature and precipitation accumulation. forecast_minutely returns a list whose resolution is 1 (minutes) where the forecast is a radar nowcast and 60 elsewhere. Symbol.parse("d421") decodes weather symbol codes; see the symbol reference.

Errors: ForecaAuthError (key rejected), ForecaProductUnavailableError (the key is valid but its plan lacks the product), ForecaRateLimitError (HTTP 429), ForecaConnectionError (network/timeout), all subclasses of ForecaError. When the per-second limit answers 429 with a Retry-After of up to 5 seconds, the client waits that long and retries once before raising ForecaRateLimitError; its error and retry_after attributes carry the API's error code and wait time.

Attribution

Applications displaying Foreca data must attribute Foreca — see the logo and attribution requirements.

Development

python3 -m venv .venv && .venv/bin/pip install -e . pytest pytest-asyncio
.venv/bin/pytest

Maintained by Foreca in the foreca-dev organization. Released under the MIT License.