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. 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.

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.