pyopentides

Tide predictions from official national hydrographic sources. One contract, many providers. Pure Python, aiohttp, no Home Assistant dependency.

Providers: Marine Institute (Ireland), NOAA CO-OPS (United States), Kartverket (Norway), DMI (Denmark, Greenland, Faroe Islands). Details, datums and licences: providers.md.

Install

pip install pyopentides

Python ≥ 3.12.

Usage

import asyncio
from datetime import UTC, datetime, timedelta

import aiohttp

from pyopentides import Location
from pyopentides.providers import PROVIDERS


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        provider = PROVIDERS["marine_ie"](session, version="my-app/1.0")

        stations = await provider.list_stations()          # None if coordinate_based
        dublin = next(s for s in stations if s.id == "Dublin_Port")
        loc = Location(station_id=dublin.id)

        now = datetime.now(UTC)
        events = await provider.get_events(loc, now, now + timedelta(days=7))
        for e in events:
            print(e.time.isoformat(), e.kind, f"{e.height_m:.2f} m {provider.datum}")

        caps = await provider.capabilities(loc)
        if caps.curve:
            curve = await provider.get_curve(loc, now, now + timedelta(hours=48))
        if caps.observed:
            obs = await provider.get_observed(loc)

        print(provider.attribution)


asyncio.run(main())

Coordinate-based provider:

provider = PROVIDERS["kartverket"](session)
loc = Location(lat=58.974, lon=5.730)          # Stavanger
events = await provider.get_events(loc, start, end)

What you get back

All times are timezone-aware UTC. All heights are metres, relative to the provider's declared datum. Never converted.

Guarantees on get_events and get_curve: sorted ascending, no duplicate times, nothing outside [start, end]. Events alternate high/low.

Provider attributes

Errors

All ProviderError subclasses. Nothing from aiohttp escapes.

Politeness

The library does not rate-limit or cache. You must:

• Call get_events at most once per min_refresh per location, and fetch horizon ahead so that's enough.
• Persist the result. Predictions don't change; there is no reason to re-fetch on restart.
• Pass a version string; it goes into the User-Agent (open_tides/<version> (+https://github.com/gerrowadat/open-tides)).

These are shared public services run by hydrographic offices. See api-landscape.md for what each one asks of clients.

Adding a provider

adding-a-provider.md.

Licence

MIT. Data is under each provider's own licence.