Metadata-Version: 2.4
Name: vancam
Version: 0.1.0
Summary: CLI for the Vancam camera spatial search API
Author: DD
License: MIT License
        
        Copyright (c) 2026 DD
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://vancam.ai
Project-URL: Repository, https://github.com/shughestr/vancam-cli
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: python-dotenv>=1.0.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: responses>=0.25.0; extra == "test"
Dynamic: license-file

# Vancam CLI

**Real-world observation for AI agents.**

Command-line client for the Vancam camera spatial search API
(`api.vancam.ai`), giving developers and AI agents instant access to
**1M+ live public cameras across 100+ countries** — the same backend used
by the [MCP server](https://github.com/shughestr/mcp-vancam) and the
[vancam.ai](https://vancam.ai) web app.

Instead of relying on outdated web pages or user reports, Vancam provides
fresh visual evidence from the physical world, letting AI systems answer
location-based questions with confidence.

```
vancam REST API
   ├── vancam-mcp     (MCP server)
   ├── vancam-cli     (this project)
   ├── SDKs           (future)
   └── vancam.ai      (web app)
```

## Install

```bash
pip install vancam
```

## Setup

No setup required to try it — defaults to a shared, public key if
`VANCAM_API_KEY` isn't set. That's **one key used by every anonymous
caller**, so its 1 req/s / 500 requests/month limit is a collective pool
shared across all of them, not 500 each. For a limit that's yours alone
(5 req/s, 500 requests/month, not shared), get a free personal key from your
account dashboard at [vancam.ai/account](https://vancam.ai/account):

```bash
cp .env.example .env
# edit .env, or export VANCAM_API_KEY directly
```

## Usage

```bash
# N nearest cameras to a point
vancam nearest --lat 49.2827 --lon -123.1207 --limit 5

# Cameras within a radius (km)
vancam radius --lat 49.2827 --lon -123.1207 --radius 1

# Cameras along a route
vancam route --origin-lat 49.2827 --origin-lon -123.1207 \
             --dest-lat 49.2965 --dest-lon -123.0884 --buffer 100

# Cameras in a bounding box
vancam bounds --min-lat 49.2 --min-lon -123.2 --max-lat 49.3 --max-lon -123.0

# Single camera by ID
vancam get 30145

# Live image
vancam image 30145                    # prints the image URL
vancam image 30145 -o camera.jpg      # downloads it
```

All commands print JSON to stdout (`--compact` for single-line output),
so this composes with `jq`:

```bash
vancam nearest --lat 49.2827 --lon -123.1207 --limit 1 | jq '.cameras[0].image_url'
```

## Options

- `--api-key` — override `VANCAM_API_KEY`
- `--compact` — compact JSON instead of pretty-printed

## Use Cases

- Verify road and traffic conditions
- Monitor infrastructure and public spaces
- Check border crossings and transportation hubs
- Build AI agents with real-world awareness
- Power MCP servers, automation, and LLM applications

## Learn More

- **Website:** https://vancam.ai
- **API:** https://vancam.ai/api
- **MCP Server:** https://github.com/shughestr/mcp-vancam
