REST API · contract 2026-07-09

Tide API reference

Perigee serves NOAA station metadata, harmonic tide predictions, observed water levels, marine conditions, forecasts, and local astronomy as a versioned JSON API. Public coastal-data reads work without a key. Each response keeps provenance, freshness, datum, units, time zone, and unavailable fields explicit.

OpenAPI 3.1 JSON Try the playground Connect with MCP

Choose the product before the endpoint

Start with the right resource

Find the right station

GET /api/v1/stations

Search by name or state. Add type=tidepredictions when the job requires high and low tide predictions.

Read predicted tides

GET /api/v1/stations/{id}/predictions

Request high/low events or interval predictions with an explicit datum and bounded time window.

Read observed water

GET /api/v1/stations/{id}/water-levels

Fetch measured water levels separately from astronomical predictions so the two are never conflated.

Calculate local sky events

GET /api/v1/astronomy

Return sunrise, twilight, solar position, moon phase, moonrise, and moonset for coordinates and dates.

48-hour Boston high / low prediction example

curl "https://perigeetides.com/api/v1/stations/8443970/predictions?interval=hilo&hours=48&datum=MLLW"

Generated from the production contract

REST operations

These 13 operations come from the same OpenAPI document used by SDK and route-contract tests. PUBLIC reads do not require a key; KEY operations require the documented scope.

Download the contract

Stations

3 operations

Stations REST operations
Method	Path	Purpose	Access
GET	`/api/v1/stations`	Search the NOAA station directory	PUBLIC
GET	`/api/v1/stations/nearest`	Find stations nearest a coordinate	PUBLIC
GET	`/api/v1/stations/{id}`	Get station metadata, products, datums, and flood levels	PUBLIC

Observations

4 operations

Observations REST operations
Method	Path	Purpose	Access
GET	`/api/v1/stations/{id}/predictions`	Get high/low or interval tide predictions	PUBLIC
GET	`/api/v1/stations/{id}/water-levels`	Get observed water levels	PUBLIC
GET	`/api/v1/stations/{id}/conditions`	Get latest water, wind, temperature, and pressure readings	PUBLIC
GET	`/api/v1/stations/{id}/forecast`	Get NWS wind and marine forecast context	PUBLIC

Astronomy

1 operation

Astronomy REST operations
Method	Path	Purpose	Access
GET	`/api/v1/astronomy`	Calculate sun and moon details for a coordinate	PUBLIC

Decisions

4 operations

Decisions REST operations
Method	Path	Purpose	Access
POST	`/api/v1/decisions/trip-health`	Get one explainable Trip Health planning read	PUBLIC
POST	`/api/v1/decisions/best-window`	Rank 2–12 candidate local windows	KEY
POST	`/api/v1/decisions/evaluate-rules`	Evaluate deterministic rules against a fresh planning decision	KEY
POST	`/api/v1/decisions/material-change`	Compare a prior decision summary with current inputs	KEY

Platform

1 operation

Platform REST operations
Method	Path	Purpose	Access
GET	`/api/developer/status`	Get API, MCP, and upstream provider status	PUBLIC

Interpretation contract

Keep unlike coastal data separate

Prediction is not observation

Predictions estimate the astronomical tide. Observed water levels can also reflect wind, pressure, river flow, waves, and surge.

Tide height is not current speed

High and low water describe vertical level. Flood, ebb, maximum current, and slack require current-station data.

Datum, units, and local time travel with the value

Keep the station datum, measurement unit, station ID, time zone, and source timestamp with every result.

Missing stays missing

A provider timeout or unavailable product is not a favorable condition. Narrow the answer and report the absent input.

Authentication, quota, and errors

Public reads

Anonymous requests use the published IP limit. A free key raises capacity without changing the underlying coastal-data meaning.

Scoped keys

Send Authorization: Bearer or x-api-key. Keep keys on a server, never in a public browser bundle.

Fail closed

A 429 includes retry guidance. A 503 means Perigee could not safely complete the upstream or quota step; do not invent data.