Wildeye API

Python client and CLI for downloading time-series data from the Wildeye platform.

Quick Start

The fastest way to use the Wildeye CLI is with uvx (no installation required):

# Set your API token
export WILDEYE_API_TOKEN="your-token"

# Run any command directly
uvx --from "git+https://github.com/harryeslick/wildeye_api.git" wildeye --help
uvx --from "git+https://github.com/harryeslick/wildeye_api.git" wildeye sites list
uvx --from "git+https://github.com/harryeslick/wildeye_api.git" wildeye data download "Site Name" --start 2025-01-01 --end 2025-06-30

uvx automatically creates an isolated environment and runs the CLI without permanently installing anything.

Requirements

• Python 3.10 or newer
• WILDEYE_API_TOKEN environment variable with a valid API token
• For uvx: uv package manager

Installation

If you prefer to install the package permanently:

Using pip

# Install from GitHub
pip install "git+https://github.com/harryeslick/wildeye_api.git"

# Or clone locally and install
git clone https://github.com/harryeslick/wildeye_api.git
cd wildeyeAPI
pip install .

Using uv

# Install from GitHub
uv pip install "git+https://github.com/harryeslick/wildeye_api.git"

# Or clone and create a managed virtual environment
git clone https://github.com/harryeslick/wildeye_api.git
cd wildeyeAPI
uv sync

Common Workflow

With uvx (no installation)

export WILDEYE_API_TOKEN="your-token"

# Download measurements and metadata for a site into CSV files
uvx --from "git+https://github.com/harryeslick/wildeye_api.git" wildeye data download "Site Name" --start 2025-01-01 --end 2025-06-30

With installed package

export WILDEYE_API_TOKEN="your-token"

# Download measurements and metadata for a site into CSV files
wildeye data download "Site Name" --start 2025-01-01 --end 2025-06-30

• Defaults create <site>_<start>_<end>_data.csv and _metadata.csv
• Pass --data-file or --metadata-file to choose output filenames

Advanced Usage

CLI Commands

• Inspect available sites before downloading: wildeye sites list
• Fetch latest readings for a category: wildeye data latest "category-id"
• Export measurements for a device: wildeye devices data "device-id" --output readings.json

Python Client

• Use the Python client directly (requires installation):

  from wildeyeapi import WildeyeClient
  
  client = WildeyeClient()
  sites = client.get_sites()
  measurements = client.fetch_measurements_by_id(ids="input-id", start="2025-01-01", end="2025-06-30")

Further command reference lives in CLI_USAGE.md, and runnable examples are under examples/.