TidesAtlas API
Access worldwide tide data for 3,000+ stations across 112 countries via a simple REST API. Real-time predictions powered by the TICON-4 harmonic engine.
Authentication
All requests require an API key. Two methods available:
Option 1 — Header (recommended)
# Via X-API-Key header
curl -H "X-API-Key: YOUR_KEY" https://tidesatlas.com/api/v1/tides?port=aberdeen-abe-gbr-bodc
curl -H "X-API-Key: YOUR_KEY" https://tidesatlas.com/api/v1/tides?port=aberdeen-abe-gbr-bodc
Option 2 — Query parameter
# Via api_key parameter
curl https://tidesatlas.com/api/v1/tides?port=aberdeen-abe-gbr-bodc&api_key=YOUR_KEY
curl https://tidesatlas.com/api/v1/tides?port=aberdeen-abe-gbr-bodc&api_key=YOUR_KEY
Base URL
https://tidesatlas.com/api/v1/
Endpoints
GET
/api/v1/tides
Returns tide times and heights (high and low water) for any station worldwide.
| Parameter | Type | Description |
|---|---|---|
port | string | Station slug (e.g. aberdeen-abe-gbr-bodc). Use /ports to search. |
lat | float | Latitude (alternative to port). Returns nearest station. |
lon | float | Longitude (used with lat). |
date | YYYY-MM-DD | Start date (default: today). |
days | int | Number of days, 1-14 (default: 1). |
# By station name
GET /api/v1/tides?port=aberdeen-abe-gbr-bodc&date=2026-03-02&days=3
# By coordinates (nearest station)
GET /api/v1/tides?lat=57.14&lon=-2.08&date=2026-03-02
Response
{
"port": {
"name": "Aberdeen",
"slug": "aberdeen-abe-gbr-bodc",
"lat": 57.14,
"lon": -2.08,
"timezone": "Europe/London",
"country": "United Kingdom",
"region": "Scotland"
},
"date": "2026-03-02",
"days": 3,
"count": 12,
"extremes": [
{
"datetime": "2026-03-02T04:23:00+00:00",
"timestamp": 1772525000,
"height_m": 3.82,
"type": "high"
},
{
"datetime": "2026-03-02T10:41:00+00:00",
"timestamp": 1772547660,
"height_m": 0.94,
"type": "low"
},
...
]
}
GET
/api/v1/ports
Search and list available tide stations worldwide.
| Parameter | Type | Description |
|---|---|---|
search | string | Search by name (e.g. aberdeen). |
country | string | Filter by country slug (e.g. united-kingdom). |
limit | int | Max results, 1-500 (default: 50). |
GET /api/v1/ports?search=aberdeen
GET /api/v1/ports?country=united-kingdom&limit=100
Response
{
"count": 2,
"ports": [
{
"name": "Aberdeen",
"slug": "aberdeen-abe-gbr-bodc",
"lat": 57.14,
"lon": -2.08,
"timezone": "Europe/London",
"country": "United Kingdom",
"country_slug": "united-kingdom",
"region": "Scotland"
},
...
]
}
GET
/api/v1/countries
List all countries with available tide stations.
GET /api/v1/countries
Response
{
"count": 112,
"countries": [
{ "name": "United Kingdom", "slug": "united-kingdom", "code_iso": "GB", "station_count": 238 },
{ "name": "United States", "slug": "united-states", "code_iso": "US", "station_count": 156 },
...
]
}
Rate Limiting
Every response includes rate limiting headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Total daily limit |
X-RateLimit-Remaining | Remaining requests today |
X-RateLimit-Reset | Unix timestamp for reset (midnight UTC) |
Pricing Plans
| Plan | Price | Daily limit | Use case |
|---|---|---|---|
| Free | $0 | 100 requests | Development / testing |
| Starter | $9 / month | 1,000 requests | Small projects |
| Pro | $49 / month | 10,000 requests | Production |
Error Codes
| Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid or missing parameter |
| 401 | Missing or invalid API key |
| 403 | Account deactivated |
| 404 | Endpoint or station not found |
| 429 | Daily rate limit exceeded |
Error format
{
"error": true,
"message": "Description of the problem",
"status": 400
}
Code Examples
cURL
# Tides in Aberdeen for 3 days
curl -H "X-API-Key: YOUR_KEY" \
"https://tidesatlas.com/api/v1/tides?port=aberdeen-abe-gbr-bodc&date=2026-03-02&days=3"
JavaScript (fetch)
const response = await fetch(
'https://tidesatlas.com/api/v1/tides?port=aberdeen-abe-gbr-bodc&days=3',
{ headers: { 'X-API-Key': 'YOUR_KEY' } }
);
const data = await response.json();
console.log(data.extremes);
Python
import requests
response = requests.get(
'https://tidesatlas.com/api/v1/tides',
params={'port': 'aberdeen-abe-gbr-bodc', 'days': 3},
headers={'X-API-Key': 'YOUR_KEY'}
)
data = response.json()
print(data['extremes'])
PHP
$ch = curl_init('https://tidesatlas.com/api/v1/tides?port=aberdeen-abe-gbr-bodc&days=3');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: YOUR_KEY']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);