Tides - Spire Weather API Documentation

Tidal predictions and extrema data. Spire Tides data covers both historical and forecast periods, with data available from January 1, 1990 through December 31, 2025. 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/point

Retrieve 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) or `us`

Example Request¶

Shell

Python

Node.js

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",
    "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/extrema

Retrieve high and low tide times and heights for a location, summarized by day. Each day includes the highest and lowest tide within that calendar day.

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¶

Shell

Python

Node.js

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, with each entry containing the high and low tide for that day:

{
  "meta": {
    "unit_system": "si",
    "message": null
  },
  "data": [
    {
      "date": "2024-01-15",
      "high": {
        "time": "2024-01-15T03:24:00",
        "values": {
          "tide_height": 1.52
        }
      },
      "low": {
        "time": "2024-01-15T09:47:00",
        "values": {
          "tide_height": -0.35
        }
      }
    },
    {
      "date": "2024-01-16",
      "high": {
        "time": "2024-01-16T04:12:00",
        "values": {
          "tide_height": 1.48
        }
      },
      "low": {
        "time": "2024-01-16T10:35:00",
        "values": {
          "tide_height": -0.41
        }
      }
    }
  ]
}

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
for day in extrema:
    high_t = pd.to_datetime(day['high']['time'])
    high_h = day['high']['values']['tide_height']
    ax.scatter([high_t], [high_h], c='red', s=30, zorder=5)

    low_t = pd.to_datetime(day['low']['time'])
    low_h = day['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()