API reference

Everything the pages do can be done from a program. Version 2, at https://api.tidewater.example/v2

Keys

Make a key under Account → Keys. A key may read, or read and write; give a program only what it needs.

Send it in the Authorization header of every call:

Shell
curl -H "Authorization: Bearer tw_live_4f9c…" https://api.tidewater.example/v2/stations

A key is a password. Keep it out of code you share; if one leaks, delete it under Account → Keys and it stops working at once.

Stations

GET /stations lists the stations the key may see. GET /stations/{id} gives one.

The answer

JSON
[  {    "id": "bergen-harbour",    "name": "Bergen harbour",    "place": { "lat": 60.3975, "lng": 5.3221 },    "measures": ["level", "temp", "salt"],    "lastHeard": "2026-05-14T08:10:00Z"  }]

Sending

POST /in/{station} takes numbers as form fields or as JSON. A time is optional: without one, it is the moment the call arrives.

Shell
curl -X POST https://tidewater.example/in/bergen-harbour \  -H "Content-Type: application/json" \  -d @reading.json

reading.json

JSON
{ "time": "2026-05-14T08:20:00Z", "level": 1.47, "temp": 8.3 }

The /in addresses need no key: the station’s address is its own secret. Make a new one under the station’s settings if it is shared by mistake.

Readings

GET /stations/{id}/readings gives what was measured, oldest first.

fromThe first time, ISO 8601A day ago
toThe last timeNow
everyOne value per 10m, 1h or 1d (the mean)Every reading
measureOne or more, with commasAll of them

In JavaScript

JavaScript
const answer = await fetch('https://api.tidewater.example/v2/stations/bergen-harbour/readings?every=1h', {  headers: { Authorization: 'Bearer ' + process.env.TIDEWATER_KEY },})const readings = await answer.json()

In Python

Python
import os, requestsanswer = requests.get(    'https://api.tidewater.example/v2/stations/bergen-harbour/readings',    params={'every': '1h'},    headers={'Authorization': 'Bearer ' + os.environ['TIDEWATER_KEY']},)readings = answer.json()

Errors and limits

Every error answers with a code and a sentence that says what to do about it.

400Something in the call is not as expectedRead the sentence in the answer
401No key, or one that was deletedSend a key that works
403The key may not do thisGive it write access, or use another
404No such stationCheck the id, letter by letter
429Too many callsWait the seconds in Retry-After

A key may make 1,000 calls an hour. Sending to /in is not counted: a station may send once a second.