tide-prediction

Tidal prediction library for French Atlantic and English Channel ports. Computes high/low water times, heights, tidal coefficients, and full height curves — all from a fast Rust core exposed via Python bindings.

Disclaimer

This library is provided AS IS, without warranty of any kind. It is not intended for navigation, maritime safety, or any use where inaccurate predictions could cause harm to persons, property, or the environment. Predictions are produced from a simplified 13-constituent harmonic model and do not account for meteorological effects (storm surge, wind, barometric pressure) or exceptional astronomical events. Typical residual RMSE is 0.10–0.25 m; local error may be larger.

For official tidal predictions in France, refer to the SHOM. The author disclaims all liability arising from the use of this software. By using this library you do so at your own risk and sole responsibility.

Installation

pip install tide-prediction

The package is imported as import tide (not tide_prediction).

Quick start

import tide

# Predict a full day
pred = tide.predict_day("FR-BREST", "2024-06-15")

from datetime import datetime, timezone

for e in pred.extremes:
    kind = "HW" if e.is_high_water else "LW"
    coef = f"  coef={e.coefficient}" if e.coefficient else ""
    dt = datetime.fromtimestamp(e.time, tz=timezone.utc).strftime("%H:%M")
    print(f"{kind}  {dt}  {e.height:.2f} m{coef}")

# HW  00:26  4.83 m  coef=39
# LW  06:41  2.40 m
# HW  13:07  4.80 m  coef=42
# LW  19:07  2.61 m

API

tide.predict_day(port_id, date) → DayPrediction

Returns high/low water extremes and a 10-minute height curve for a single day.

• port_id — port identifier (e.g. "FR-BREST")
• date — date string "YYYY-MM-DD" (UTC)

tide.predict_range(port_id, from_date, to_date) → list[DayPrediction]

Same as predict_day over a date range (inclusive).

tide.height_at(port_id, timestamp) → float

Instantaneous water height in metres at a given Unix UTC timestamp.

from datetime import datetime, timezone

ts = int(datetime(2024, 6, 15, 12, 0, tzinfo=timezone.utc).timestamp())
h = tide.height_at("FR-BREST", ts)
print(f"{h:.3f} m")  # 4.607 m

Port discovery

# List all available ports
ports = tide.list_ports()

# Search by name
results = tide.search_ports("saint")

# Get a specific port
port = tide.get_port("FR-BREST")
print(port.name, port.latitude, port.longitude)

Data model

DayPrediction
├── port_id        str
├── date           str          "YYYY-MM-DD"
├── extremes       list[TidalExtreme]
│   ├── time           int      Unix timestamp UTC
│   ├── height         float    metres
│   ├── is_high_water  bool
│   └── coefficient    int|None 20–120, Atlantic/Channel HW only
└── heights        list[HeightPoint]
    ├── timestamp   int          every 10 minutes
    └── height      float        metres

Available ports

Tidal coefficients

Coefficients (20–120) are computed for Atlantic and English Channel high waters relative to the Brest reference tidal range, following the French SHOM convention. They are only available for high water (is_high_water = True) at ports on the Atlantic/Channel coast.

Requirements

• Python ≥ 3.8
• Currently tested on Linux x86-64 (manylinux). macOS and Windows wheels may be added in future releases.