# API reference

The Tidepool API returns predictions as JSON. It is free for up to 1,000 requests a day per IP address.

> [!NOTE]
> All times are in the station's local time zone unless you pass `tz=utc`.

## Endpoints

| Method | Path | Returns |
| :--- | :--- | :--- |
| `GET` | `/v2/stations?q=` | Stations matching a name, ID or ZIP |
| `GET` | `/v2/stations/{id}` | One station with its harmonic constants |
| `GET` | `/v2/predictions/{id}` | High and low water for a date range |

## Predictions

```bash
curl "https://api.tidepool.example/v2/predictions/9414290?from=2026-11-10&days=1"
```

```json
{
  "station": "9414290",
  "name": "San Francisco",
  "datum": "MLLW",
  "units": "ft",
  "turns": [
    { "time": "2026-11-10T02:23", "type": "H", "height": 5.6 },
    { "time": "2026-11-10T07:40", "type": "L", "height": 3.5 },
    { "time": "2026-11-10T12:58", "type": "H", "height": 5.6 },
    { "time": "2026-11-10T20:01", "type": "L", "height": 0.4 }
  ]
}
```

### Parameters

| Name | Type | Default | Notes |
| --- | --- | --- | --- |
| `from` | date | today | `YYYY-MM-DD` |
| `days` | integer | `7` | 1 to 31 |
| `units` | string | `ft` | `ft` or `m` |
| `tz` | string | `local` | `local` or `utc` |

## Errors

```text
HTTP/1.1 404 Not Found
Content-Type: application/json

{ "error": "unknown_station", "message": "No station 99999." }
```

> [!WARNING]
> Predictions are not for navigation. Use official charts and local notices.

## Client example

```python
import requests

r = requests.get("https://api.tidepool.example/v2/predictions/9414290", params={"days": 1})
for turn in r.json()["turns"]:
    print(turn["time"], turn["type"], turn["height"])
```