Tidal predictions and extrema data. The tide height is the change of sea level relative to mean sea level caused by the Earth’s rotation and the gravitational pull of the Moon and the Sun; it is computed by a dedicated astronomical tide model, not by the weather forecast. Spire Tides data covers both historical and forecast periods, with data available from January 1, 1990 onwards, so one query can span past and future. The data grid resolution is 1/16° (approximately 6 km).
Endpoints¶
| Method | Endpoint | Description |
|---|---|---|
| GET | /tides/point | Get hourly tidal predictions at a point |
| GET | /tides/point/extrema | Get high/low tide times |
Tidal Predictions¶
GET /tides/pointRetrieve hourly tidal height predictions for a specific location. Returns tide height compared to mean sea level for up to a 10-day period. Unlike other endpoints, the tides endpoint can return both historical and forecast data in a single query.
Parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
lat | number | Yes | Latitude (-90 to 90) |
lon | number | Yes | Longitude (-180 to 180) |
start_datetime | string | No | ISO 8601 start time (default: now) |
forecast_hours | integer | No | Hours of data from start (default: 240 = 10 days) |
unit_system | string | No | si (default, metres) or us (feet) |
Example Request¶
curl -X GET \
'https://api.wx.spire.com/tides/point?lat=40.7&lon=-74.0&start_datetime=2024-01-15T00:00:00Z&forecast_hours=48' \
-H 'spire-api-key: YOUR_API_KEY'import requests
response = requests.get(
"https://api.wx.spire.com/tides/point",
params={
"lat": 40.7,
"lon": -74.0,
"start_datetime": "2024-01-15T00:00:00Z",
"forecast_hours": 48,
},
headers={"spire-api-key": "YOUR_API_KEY"},
)
data = response.json()const params = new URLSearchParams({
lat: "40.7",
lon: "-74.0",
start_datetime: "2024-01-15T00:00:00Z",
forecast_hours: "48",
});
const response = await fetch(
`https://api.wx.spire.com/tides/point?${params}`,
{ headers: { "spire-api-key": "YOUR_API_KEY" } }
);
const data = await response.json();Response¶
{
"meta": {
"unit_system": "si",
"units": "m",
"message": null
},
"data": [
{
"location": {
"coordinates": {
"lat": 40.7,
"lon": -74.0
}
},
"times": {
"valid_time": "2024-01-15T00:00:00"
},
"values": [
{
"tide_height": 0.45
}
]
},
{
"location": {
"coordinates": {
"lat": 40.7,
"lon": -74.0
}
},
"times": {
"valid_time": "2024-01-15T01:00:00"
},
"values": [
{
"tide_height": 0.62
}
]
}
]
}Tidal Extrema¶
GET /tides/point/extremaRetrieve high and low tide times and heights for a location, grouped by calendar day. Each day lists every high and every low tide that occurs in it (typically two of each; more where the tidal signal is mixed).
Parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
lat | number | Yes | Latitude (-90 to 90) |
lon | number | Yes | Longitude (-180 to 180) |
start_datetime | string | Yes | ISO 8601 start time |
end_datetime | string | Yes | ISO 8601 end time |
unit_system | string | No | si (default) or us |
Example Request¶
curl -X GET \
'https://api.wx.spire.com/tides/point/extrema?lat=40.7&lon=-74.0&start_datetime=2024-01-15T00:00:00&end_datetime=2024-01-17T00:00:00' \
-H 'spire-api-key: YOUR_API_KEY'import requests
response = requests.get(
"https://api.wx.spire.com/tides/point/extrema",
params={
"lat": 40.7,
"lon": -74.0,
"start_datetime": "2024-01-15T00:00:00",
"end_datetime": "2024-01-17T00:00:00",
},
headers={"spire-api-key": "YOUR_API_KEY"},
)
data = response.json()const params = new URLSearchParams({
lat: "40.7",
lon: "-74.0",
start_datetime: "2024-01-15T00:00:00",
end_datetime: "2024-01-17T00:00:00",
});
const response = await fetch(
`https://api.wx.spire.com/tides/point/extrema?${params}`,
{ headers: { "spire-api-key": "YOUR_API_KEY" } }
);
const data = await response.json();Response¶
The extrema response groups results by date. high and low are arrays, one entry per high or low tide in that day:
{
"meta": {
"unit_system": "si",
"units": "m",
"message": null
},
"data": [
{
"date": "2024-01-15",
"high": [
{
"time": "2024-01-15T03:24:00",
"values": {
"tide_height": 1.52
}
},
{
"time": "2024-01-15T15:48:00",
"values": {
"tide_height": 1.31
}
}
],
"low": [
{
"time": "2024-01-15T09:47:00",
"values": {
"tide_height": -0.35
}
},
{
"time": "2024-01-15T22:10:00",
"values": {
"tide_height": -0.52
}
}
]
}
]
}Units¶
| Unit System | Height Unit |
|---|---|
si | meters (m) |
us | feet (ft) |
Datum¶
Tidal heights are referenced to Mean Sea Level (MSL) by default. See also Tidal Datum.
Python Example¶
Plot tide predictions with extrema annotations:
import requests
import pandas as pd
import matplotlib.pyplot as plt
headers = {'spire-api-key': 'YOUR_API_KEY'}
# Get hourly tide predictions
response = requests.get(
'https://api.wx.spire.com/tides/point',
headers=headers,
params={
'lat': 40.7,
'lon': -74.0,
'start_datetime': '2024-01-15T00:00:00Z',
'forecast_hours': 168 # 7 days
}
)
data = response.json()['data']
df = pd.DataFrame([
{
'time': d['times']['valid_time'],
'height': d['values'][0]['tide_height']
}
for d in data
])
df['time'] = pd.to_datetime(df['time'])
# Get extrema for annotations
extrema_response = requests.get(
'https://api.wx.spire.com/tides/point/extrema',
headers=headers,
params={
'lat': 40.7,
'lon': -74.0,
'start_datetime': '2024-01-15T00:00:00Z',
'end_datetime': '2024-01-22T00:00:00Z'
}
)
extrema = extrema_response.json()['data']
# Plot
fig, ax = plt.subplots(figsize=(12, 5))
ax.plot(df['time'], df['height'], 'b-', linewidth=1)
ax.axhline(y=0, color='gray', linestyle='--', linewidth=0.5)
# Mark high/low tides (several per day)
for day in extrema:
for high in day['high']:
high_t = pd.to_datetime(high['time'])
high_h = high['values']['tide_height']
ax.scatter([high_t], [high_h], c='red', s=30, zorder=5)
for low in day['low']:
low_t = pd.to_datetime(low['time'])
low_h = low['values']['tide_height']
ax.scatter([low_t], [low_h], c='green', s=30, zorder=5)
ax.set_xlabel('Time')
ax.set_ylabel('Tide Height (m)')
ax.set_title('Tidal Predictions - New York Harbor')
plt.xticks(rotation=45)
plt.tight_layout()
plt.show()