Metadata-Version: 2.4
Name: pynims
Version: 1.1.0
Summary: A Python package for interacting with the National Imagery Management System (NIMS)
Project-URL: Homepage, https://code.usgs.gov/WiM/usgs-imagery/sdk/pynims
Author-email: Keegan Johnson <keeganejohnson@usgs.gov>
License: CC0-1.0
License-File: LICENSE.md
Keywords: backend,download,images,nims,upload
Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: httpx<0.29,>=0.28
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pytz
Requires-Dist: typer<0.25.0,>=0.10.0
Description-Content-Type: text/markdown

# PyNIMS

Python client and CLI (command-line interface) for the USGS NIMS (National Imagery Management System) API. Use it to query camera metadata, list and download imagery, and construct image URLs — from Python scripts or the command line.

- [API Documentation](https://api.waterdata.usgs.gov/docs/nims/)
- [Swagger UI](https://api.waterdata.usgs.gov/nims/v0/docs)
- [Source Code](https://code.usgs.gov/WiM/usgs-imagery/sdk/pynims)

---

## Installation

Requires **Python 3.10+**.

```bash
pip install pynims
```

---

## API Key

The NIMS API works without a key, but unauthenticated requests are rate-limited. **We strongly recommend signing up for a free API key:**

👉 [https://api.waterdata.usgs.gov/signup/](https://api.waterdata.usgs.gov/signup/)

You can provide your key in two ways:

```python
# Option 1: Constructor parameter
client = NIMSClient(api_key="your-key-here")

# Option 2: Environment variable
# export NIMS_API_KEY=your-key-here
client = NIMSClient()  # picks up NIMS_API_KEY automatically
```

If no key is found, the client will issue a warning but continue to work.

---

## Python API

Use the Python API in your scripts or an interactive Python session (e.g., `python`, IPython, or a Jupyter notebook). The typical workflow is: find cameras → list images → download or get URLs.

```python
from pynims import NIMSClient

with NIMSClient(api_key="your-key-here") as client:
    # 1. Find cameras at a site (omit site_id to get all cameras)
    cameras = client.get_cameras(site_id="05366800")
    cam_id = cameras[0]["camId"]

    # 2. List images for a time range
    images = client.get_image_list(cam_id, start="2023-06-01", end="2023-06-02")

    # 3. Construct image URLs (full, thumb, or small)
    urls = client.get_image_urls(images)                      # full-size
    thumb_urls = client.get_image_urls(images, size="thumb")  # thumbnails

    # 4. Or download directly
    client.download_image(images[0])                      # full-size
    client.download_image(images[0], size="small")        # 720px

    # 5. Quick access to timelapse and newest image
    timelapse = client.get_timelapse_url(cam_id)
    newest = client.get_newest_image_url(cam_id)
```

---

## CLI

After installing, the `pynims` command is available in your terminal. Run these commands from any command prompt (Terminal on macOS/Linux, Command Prompt or PowerShell on Windows).

```bash
# Check version
pynims --version

# List all camera IDs
pynims cameras

# List cameras at a site, or with full details / JSON output
pynims cameras --site-id 05366800
pynims cameras --full
pynims cameras --json

# Get details for a single camera
pynims camera CAM_ID

# List images (prints to stdout by default)
pynims image-list CAM_ID --start=2023-06-01 --end=2023-06-10
pynims image-list CAM_ID --start=2023-06-01 --end=2023-06-10 --json
pynims image-list CAM_ID --start=2023-06-01 --end=2023-06-10 --save-dir=./out

# Download images
pynims download-images CAM_ID --start=2023-06-01 --end=2023-06-10 --api-key=your-key
pynims download-images CAM_ID --start=2023-06-01 --end=2023-06-10 --size=thumb
pynims download-images --image-list-file=images.json
```

Use `--help` on any command for details:

```bash
pynims --help
pynims download-images --help
```

---

## Filtering

Filter image lists by time of day, season, date range, and more — from Python or the CLI.

```bash
# Daytime summer images
pynims image-list CAM1 --start 2023-01-01 --end 2023-12-31 --hours 8-17 --months 6,7,8

# Download one image per day
pynims download-images CAM1 --start 2023-06-01 --end 2023-06-30 --interval 24h
```

See the [Filtering Guide](docs/filtering.md) for full documentation, including the Python API, chaining examples, and all available filters.

---

## Development

```bash
git clone https://code.usgs.gov/WiM/usgs-imagery/sdk/pynims.git
cd pynims

# Using pip
python -m venv .venv
source .venv/bin/activate   # macOS/Linux
pip install -e ".[dev]"

# Or using uv
uv sync

# Run tests
pytest

# Lint / format
ruff check .
ruff format .
```

---

## Suggested Citation

Johnson, K.E., 2026, PyNIMS: Python client and CLI for the USGS NIMS API (v1.0.0), U.S. Geological Survey Software Release, https://doi.org/10.5066/P13FBPDN.

---

## Releases

A newer version of this software may be available. See [all releases](https://code.usgs.gov/WiM/usgs-imagery/sdk/pynims/-/releases).

---

## Use of Artificial Intelligence

AI-assisted coding tools were used during development, specifically Kiro CLI (multiple versions). All code was reviewed, tested, and validated by the author to ensure correctness and reproducibility.

---

## License and Disclaimer

- [LICENSE.md](LICENSE.md)
- [DISCLAIMER.md](DISCLAIMER.md)
