Metadata-Version: 2.4
Name: az511-client
Version: 0.1.1
Summary: Python client for the Arizona 511 traveler information API
Author: Joel B
License-Expression: MIT
Project-URL: Homepage, https://github.com/joelrberry/az511-client
Project-URL: Bug Tracker, https://github.com/joelrberry/az511-client/issues
Keywords: arizona,511,traffic,transportation,api,client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: eval_type_backport>=0.1.3; python_version < "3.10"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: responses>=0.25.0; extra == "dev"
Dynamic: license-file

# az511-client

[![PyPI version](https://img.shields.io/pypi/v/az511-client.svg)](https://pypi.org/project/az511-client/)
[![Python versions](https://img.shields.io/pypi/pyversions/az511-client.svg)](https://pypi.org/project/az511-client/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Python client for the [Arizona 511 traveler information API](https://www.az511.com/developers/doc).

## Installation

```bash
pip install az511-client
```

## Quick Start

```python
from az511 import AZ511Client

client = AZ511Client(api_key="your_key_here")

cameras = client.get_cameras()
for cam in cameras:
    print(cam.roadway, cam.location, cam.latitude, cam.longitude)
    for view in cam.views:
        print("  ", view.url)
```

## Authentication

Get a free API key at <https://www.az511.com/my511/register>.

Pass it explicitly or set the `AZ511_API_KEY` environment variable:

```bash
export AZ511_API_KEY=your_key_here
```

```python
# reads AZ511_API_KEY automatically from the environment
client = AZ511Client()
```

A `.env` file in the working directory is also supported (via `python-dotenv`):

```
AZ511_API_KEY=your_key_here
```

## Available Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `get_cameras()` | `list[Camera]` | All traffic cameras |
| `get_weather_stations()` | `list[WeatherStation]` | All roadside weather stations |
| `get_alerts()` | `list[Alert]` | Active traveler alerts |
| `get_rest_areas()` | `list[RestArea]` | Rest area status and amenities |
| `get_events()` | `list[Event]` | Active traffic events and roadwork |
| `get_message_boards()` | `list[MessageBoard]` | Variable message signs (VMS) |
| `get_wzdx()` | `WZDxFeatureCollection` | Work zone data (GeoJSON, WZDx 4.x) |

All model classes are importable from `az511.models`:

```python
from az511.models import (
    Camera, CameraView,
    WeatherStation,
    Alert,
    RestArea,
    Event, EventRestrictions,
    MessageBoard,
    WZDxFeatureCollection, WZDxFeature, WZDxProperties,
)
```

## Error Handling

```python
from az511 import AZ511Client
from az511.exceptions import AuthError, RateLimitError, APIError

client = AZ511Client()

try:
    events = client.get_events()
except AuthError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limit hit — wait 60 seconds and retry")
except APIError as e:
    print(f"API error {e.status_code}: {e}")
```

## Rate Limits

The AZ511 API allows **10 requests per 60 seconds**. Exceeding this raises
`RateLimitError` (HTTP 429). The client does not throttle automatically —
callers are responsible for pacing requests.

## Development

```bash
git clone https://github.com/joelrberry/az511-client
cd az511-client
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS/Linux
pip install -e ".[dev]"
cp .env.example .env            # add your AZ511_API_KEY
pytest
```

## License

MIT — see [LICENSE](LICENSE).
