tidesatlas 0.1.0

Official Python SDK for TidesAtlas — worldwide tide predictions, weather & marine data API

TidesAtlas Python SDK

Official Python SDK for the TidesAtlas API -- worldwide tide predictions, weather, marine conditions, and astronomical data for 18,000+ stations across 188 countries.

Installation

pip install tidesatlas

Quick Start

from tidesatlas import TidesAtlas

client = TidesAtlas("your-api-key")

# Get tide predictions
tides = client.tides(port="san-francisco", days=3)
for extreme in tides["extremes"]:
    print(f"{extreme['type']}: {extreme['datetime']} -- {extreme['height_m']}m")

Authentication

Sign up at tidesatlas.com/api/register to get your API key. The SDK sends it via the X-API-Key header automatically.

client = TidesAtlas("your-api-key")

Methods

tides()

Get tide predictions (high/low times and heights) for a port or coordinates.

# By port slug
data = client.tides(port="brest", days=3, datum="LAT")

# By coordinates
data = client.tides(lat=48.39, lon=-4.49, days=3)

# For a specific date
data = client.tides(port="brest", date="2026-06-15", days=7)

Parameters:

• port -- Port slug (e.g. "san-francisco")
• lat, lon -- Latitude/longitude (alternative to port)
• days -- Number of days (default: 1)
• date -- Start date in YYYY-MM-DD format
• datum -- Tidal datum (e.g. "LAT", "MSL")

ports()

Search for tide stations by name or country.

# Search by name
results = client.ports(search="tokyo", limit=5)
for port in results["ports"]:
    print(port["name"], port["slug"], port["country"])

# Filter by country
results = client.ports(country="france", limit=20)

Parameters:

• search -- Search query string
• country -- Filter by country name
• limit -- Max results (default: 10)

countries()

List all countries that have tide stations.

data = client.countries()
for country in data["countries"]:
    print(f"{country['name']}: {country['station_count']} stations")

weather()

Get weather forecast for a port or coordinates.

data = client.weather(port="brest", days=5)

# By coordinates
data = client.weather(lat=48.39, lon=-4.49, days=3)

Parameters:

• port -- Port slug
• lat, lon -- Latitude/longitude (alternative to port)
• days -- Number of days (default: 3)

marine()

Get marine/ocean forecast including waves, swell, and sea conditions.

data = client.marine(port="brest", days=3)

# By coordinates
data = client.marine(lat=48.39, lon=-4.49)

Parameters:

• port -- Port slug
• lat, lon -- Latitude/longitude (alternative to port)
• days -- Number of days (default: 3)

astronomy()

Get sun and moon data (sunrise, sunset, moonrise, moonset, moon phase).

data = client.astronomy(port="brest")

# By coordinates
data = client.astronomy(lat=48.39, lon=-4.49, days=3)

Parameters:

• port -- Port slug
• lat, lon -- Latitude/longitude (alternative to port)
• days -- Number of days (default: 1)

conditions()

Get unified conditions combining weather, marine, and astronomy in a single call.

# All condition types
data = client.conditions(port="brest")

# Only weather and marine
data = client.conditions(port="brest", include="weather,marine")

# By coordinates
data = client.conditions(lat=48.39, lon=-4.49, days=2)

Parameters:

• port -- Port slug
• lat, lon -- Latitude/longitude (alternative to port)
• days -- Number of days (default: 1)
• include -- Comma-separated types (default: "weather,marine,astronomy")

history()

Get historical tide and weather data.

# Tide history
data = client.history(port="brest", days=30)

# Tide + weather history
data = client.history(port="brest", days=7, include="tides,weather")

# By coordinates
data = client.history(lat=48.39, lon=-4.49, days=14)

Parameters:

• port -- Port slug
• lat, lon -- Latitude/longitude (alternative to port)
• days -- Number of days (default: 7)
• include -- Comma-separated types (default: "tides")

Error Handling

The SDK raises TidesAtlasError for API errors, which includes the HTTP status code and error message from the API.

from tidesatlas import TidesAtlas, TidesAtlasError

client = TidesAtlas("your-api-key")

try:
    data = client.tides(port="nonexistent-port")
except TidesAtlasError as e:
    print(f"Error {e.status_code}: {e.message}")

Configuration

client = TidesAtlas(
    api_key="your-api-key",
    base_url="https://tidesatlas.com/api/v1",  # default
    timeout=30,                                  # seconds, default
)

Requirements

• Python 3.8+
• requests library

License

MIT -- see LICENSE for details.