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

Type Fields
Station id, name, lat, lon
Location exactly one of station_id or (lat, lon)
TideEvent time, height_m, kind ("high" / "low")
Point time, height_m
Observation time, height_m
Capabilities curve, observed — per location

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

Provider attributes

Attribute Meaning
slug, name identity; slugs are permanent
attribution, licence, licence_url show attribution wherever the data is shown; CC BY requires it
datum "LAT", "MLLW", "CD", …
coordinate_based True: no station list, query by lat/lon
min_refresh floor on how often to call get_events; days, not minutes
horizon how far ahead one fetch covers (90 d); fetch that, then stop
supports_curve, supports_observed provider can ever; check capabilities(loc) for a given location
observed_min_refresh floor for get_observed

Errors

All ProviderError subclasses. Nothing from aiohttp escapes.

Exception When
StationNotFound unknown station id, or a coordinate the provider doesn't cover
ProviderRateLimited HTTP 429
ProviderUnavailable anything else: down, timeout, unparseable. Has .status and .body for HTTP errors

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.

Project links

Data verified by PyPI on Sep 14, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for gerrowadat from gravatar.com gerrowadat

Credits

Author: Dave O'Connor

GitHub Statistics

Data verified by PyPI on Sep 14, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.12

Provides Extra

dev

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyopentides-0.1.0.tar.gz (327.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

pyopentides-0.1.0-py3-none-any.whl (16.1 kB view details)

Uploaded Python 3

File details

Details for the file pyopentides-0.1.0.tar.gz.

File metadata

  • Download URL: pyopentides-0.1.0.tar.gz
  • Upload date:
  • Size: 327.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyopentides-0.1.0.tar.gz
Algorithm Hash digest
SHA256 d7e82855ce3934fcbce77cb6824b0d0787dae0ff4098300789845111e1baabf3
MD5 d2f7e14d1489edc1616b3d876a673880
BLAKE2b-256 08295461f543db42b3d0497295e7946c37b32f94eaff2b9c6e861abbaacb1366

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyopentides-0.1.0.tar.gz:

Publisher: release-lib.yml on gerrowadat/open-tides

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyopentides-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: pyopentides-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 16.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyopentides-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 4f4838792548c888ee3d4cfa6d4b964368547c26f6962f90e8ac3695fc58f464
MD5 164d670844d79b744b2583744aa49f38
BLAKE2b-256 16e6d9c63a7498654be6f304ec89797fefc78b306d0e2d3e4ac380d03c067b37

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyopentides-0.1.0-py3-none-any.whl:

Publisher: release-lib.yml on gerrowadat/open-tides

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.2.0

2 files

This release

0.1.0 This release

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page