pynims 1.0.0

A Python package for interacting with the National Imagery Management System (NIMS)

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
• Swagger UI
• Source Code

---

Installation

Requires Python 3.10+.

From git

Choose SSH or HTTPS depending on your GitLab setup:

# SSH (if you have a GitLab SSH key configured)
pip install git+ssh://[e-mail]/wim/usgs-imagery/sdk/pynims.git

# HTTPS (prompts for GitLab username/password)
pip install git+https://code.usgs.gov/wim/usgs-imagery/sdk/pynims.git

Need to set up an SSH key? See the GitLab SSH key docs.

---

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/

You can provide your key in two ways:

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

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

# 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:

pynims --help
pynims download-images --help

---

Filtering

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

# 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 for full documentation, including the Python API, chaining examples, and all available filters.

---

Development

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.

---

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
• DISCLAIMER.md