Metadata-Version: 2.4
Name: tidesatlas
Version: 0.1.0
Summary: Official Python SDK for TidesAtlas — worldwide tide predictions, weather & marine data API
Author-email: TidesAtlas <hello@tidesatlas.com>
License: MIT
Project-URL: Homepage, https://tidesatlas.com/api/docs
Project-URL: Repository, https://github.com/TidesAtlas/tidesatlas-python
Project-URL: Documentation, https://tidesatlas.com/api/docs
Project-URL: Bug Tracker, https://github.com/TidesAtlas/tidesatlas-python/issues
Keywords: tides,weather,ocean,marine,api,forecast,waves,moon,astronomy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.20
Dynamic: license-file

# TidesAtlas Python SDK

Official Python SDK for the [TidesAtlas API](https://tidesatlas.com/api/docs) -- worldwide tide predictions, weather, marine conditions, and astronomical data for 18,000+ stations across 188 countries.

## Installation

```bash
pip install tidesatlas
```

## Quick Start

```python
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](https://tidesatlas.com/api/register) to get your API key. The SDK sends it via the `X-API-Key` header automatically.

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

## Methods

### tides()

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

```python
# 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.

```python
# 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.

```python
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.

```python
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.

```python
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).

```python
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.

```python
# 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.

```python
# 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.

```python
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

```python
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](LICENSE) for details.
