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.

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:
Latest release

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.2.0.tar.gz (345.9 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.2.0-py3-none-any.whl (18.6 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for pyopentides-0.2.0.tar.gz
Algorithm Hash digest
SHA256 e080dc7bb1c200853a86d90b4916bdd9ec11e492b12dbfce5b9d834eceb02e28
MD5 6486ff4a20293cfb888a007847df7e90
BLAKE2b-256 f081292f8a9e62428f661effd11cb30a3fe8fcab441d85910fe0d3fa35b28a85

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyopentides-0.2.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.2.0-py3-none-any.whl.

File metadata

  • Download URL: pyopentides-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 18.6 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.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 573cc92459a6e770b9a7e7c4772a80ca618d736bc8155e18c9e28e7022be5c9c
MD5 1689ebf04351bfad2de95fb05db37675
BLAKE2b-256 1b4df2201f8a38a56c220e33261d22974a7e8967b98809d54fb356538cc96346

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyopentides-0.2.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

This release

0.2.0 This release

2 files

0.1.0

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