Metadata-Version: 2.4
Name: satnogs-network-api
Version: 0.1.1
Summary: Python client wrapper for the SatNOGS Network Observation API
Author: Dominic
License-Expression: AGPL-3.0-only
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Requires-Dist: pydantic>=1.10.0
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"

# satnogs-network-observation-api-client

[![PyPI](https://img.shields.io/pypi/v/satnogs-network-api)](https://pypi.org/project/satnogs-network-api/)

Python client wrapper for the [SatNOGS Network](https://network.satnogs.org) Observation API.

Provides typed access to satellite observations, ground stations, and transmitters with lazy cursor-based pagination.

- **Source API:** [SatNOGS Network GitLab](https://gitlab.com/librespacefoundation/satnogs/satnogs-network)
- **Repository:** [GitHub](https://github.com/dbstreif/satnogs-network-observation-api-client)
- **PyPI:** [satnogs-network-api](https://pypi.org/project/satnogs-network-api/)

## Installation

### From PyPI (recommended)

```bash
pip install satnogs-network-api
```

### From source

```bash
pip install .
```

### Using Make

```bash
make venv               # Create .venv, install deps
make wheel              # Build a wheel (creates venv if needed)
make test               # Run unit tests (mocked, no network)
make test-integration   # Run integration tests (hits live API)
make clean              # Remove build artifacts
```

### For development

```bash
pip install -e ".[dev]"
```

## Quick Start

```python
from satnogs_network_api import SatnogsNetworkClient

# Anonymous (60 observation requests/hour)
client = SatnogsNetworkClient()

# Authenticated (240 observation requests/hour)
client = SatnogsNetworkClient(token="your-api-token")

for obs in client.observations.list(status="good", norad_cat_id=25544):
    print(obs.id, obs.transmitter_mode, obs.observation_frequency)
```

## Rate Limits

All endpoints are publicly accessible without authentication. Providing a token increases the observation rate limit.

| Endpoint | Anonymous | Authenticated |
|---|---|---|
| Observations | 60/hour | 240/hour |
| Stations | 256/hour | — |
| Transmitters | No known limit | — |

The client automatically retries once on 429 (Too Many Requests), respecting the `Retry-After` header.

## API Reference

See [API.md](API.md) for complete documentation of all wrapper functions with usage examples.

## Usage Guide

See [GUIDE.md](GUIDE.md) for solutions to common problems like filtering observations by satellite class (amateur, cubesat, weather, etc.) using the SatNOGS DB API alongside this wrapper.

## AI Transparency

This project was built with the assistance of Claude (Anthropic). AI was used for code generation, documentation, and test authoring. All AI-assisted commits are tagged with a `Co-Authored-By` trailer in the commit message. A human reviewed and directed all changes.

## License

AGPL-3.0
