vancam 0.1.0__tar.gz

vancam-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

vancam-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+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

vancam-0.1.0/README.md

@@ -0,0 +1,91 @@
+# 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

vancam-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "vancam"
+version = "0.1.0"
+description = "CLI for the Vancam camera spatial search API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {file = "LICENSE"}
+authors = [
+    {name = "DD"},
+]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.31.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://vancam.ai"
+Repository = "https://github.com/shughestr/vancam-cli"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0.0",
+    "responses>=0.25.0",
+]
+
+[project.scripts]
+vancam = "vancam_cli.cli:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["vancam_cli*"]

vancam-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vancam-0.1.0/tests/test_cli.py

@@ -0,0 +1,97 @@
+import json
+
+import responses
+
+from vancam_cli.cli import main
+from vancam_cli.client import DEFAULT_BASE_URL
+
+CAMERAS_URL = f"{DEFAULT_BASE_URL}/cameras/cameras"
+
+
+@responses.activate
+def test_nearest_prints_pretty_json(capsys):
+    responses.add(responses.GET, CAMERAS_URL, json={"cameras": [1, 2]}, status=200)
+
+    rc = main(["--api-key", "k", "nearest", "--lat", "1.0", "--lon", "2.0"])
+
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert json.loads(out) == {"cameras": [1, 2]}
+    assert "\n" in out.strip()
+
+
+@responses.activate
+def test_compact_flag_produces_single_line(capsys):
+    responses.add(responses.GET, CAMERAS_URL, json={"cameras": [1, 2]}, status=200)
+
+    rc = main(["--api-key", "k", "--compact", "nearest", "--lat", "1.0", "--lon", "2.0"])
+
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert out.strip() == '{"cameras":[1,2]}'
+
+
+@responses.activate
+def test_compact_flag_works_after_subcommand(capsys):
+    responses.add(responses.GET, CAMERAS_URL, json={"cameras": []}, status=200)
+
+    rc = main(["nearest", "--api-key", "k", "--lat", "1.0", "--lon", "2.0", "--compact"])
+
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert out.strip() == '{"cameras":[]}'
+
+
+@responses.activate
+def test_get_command(capsys):
+    responses.add(responses.GET, CAMERAS_URL, json={"asset_id": "30145"}, status=200)
+
+    rc = main(["--api-key", "k", "get", "30145"])
+
+    assert rc == 0
+    assert json.loads(capsys.readouterr().out) == {"asset_id": "30145"}
+
+
+@responses.activate
+def test_image_command_prints_url(capsys):
+    rc = main(["--api-key", "k", "image", "30145"])
+
+    assert rc == 0
+    out = json.loads(capsys.readouterr().out)
+    assert out == {"image_url": f"{DEFAULT_BASE_URL}/api?asset_id=30145"}
+
+
+@responses.activate
+def test_image_command_saves_to_file(tmp_path, capsys):
+    responses.add(
+        responses.GET,
+        f"{DEFAULT_BASE_URL}/api",
+        body=b"fake-image-bytes",
+        status=200,
+    )
+    dest = tmp_path / "camera.jpg"
+
+    rc = main(["--api-key", "k", "image", "30145", "-o", str(dest)])
+
+    assert rc == 0
+    assert dest.read_bytes() == b"fake-image-bytes"
+    assert "Saved to" in capsys.readouterr().err
+
+
+@responses.activate
+def test_api_error_prints_to_stderr_and_returns_1(capsys):
+    responses.add(responses.GET, CAMERAS_URL, status=403)
+
+    rc = main(["--api-key", "k", "nearest", "--lat", "1.0", "--lon", "2.0"])
+
+    assert rc == 1
+    err = capsys.readouterr().err
+    assert "403" in err
+
+
+def test_missing_required_args_exits_nonzero():
+    try:
+        main(["nearest", "--lat", "1.0"])
+        assert False, "expected SystemExit for missing required --lon"
+    except SystemExit as e:
+        assert e.code != 0

vancam-0.1.0/tests/test_client.py

@@ -0,0 +1,174 @@
+import pytest
+import responses
+import requests
+
+from vancam_cli.client import (
+    ANONYMOUS_SHARED_API_KEY,
+    DEFAULT_BASE_URL,
+    MAX_LIMIT,
+    VancamAPIError,
+    VancamClient,
+)
+
+
+def test_defaults_to_anonymous_shared_key(monkeypatch):
+    monkeypatch.delenv("VANCAM_API_KEY", raising=False)
+    client = VancamClient()
+    assert client.api_key == ANONYMOUS_SHARED_API_KEY
+
+
+def test_env_var_overrides_anonymous_key(monkeypatch):
+    monkeypatch.setenv("VANCAM_API_KEY", "env-key")
+    client = VancamClient()
+    assert client.api_key == "env-key"
+
+
+def test_explicit_api_key_wins_over_env(monkeypatch):
+    monkeypatch.setenv("VANCAM_API_KEY", "env-key")
+    client = VancamClient(api_key="explicit-key")
+    assert client.api_key == "explicit-key"
+
+
+def test_headers_include_api_key():
+    client = VancamClient(api_key="abc123")
+    assert client._headers() == {"x-api-key": "abc123"}
+
+
+def test_headers_empty_without_api_key():
+    # api_key="" falls through the `or` fallback in __init__ to the shared
+    # key, so the only way to reach a truly empty key is to set it directly.
+    client = VancamClient(api_key="k")
+    client.api_key = ""
+    assert client._headers() == {}
+
+
+@responses.activate
+def test_radius_hits_expected_endpoint_and_params():
+    responses.add(
+        responses.GET,
+        f"{DEFAULT_BASE_URL}/cameras/cameras",
+        json={"cameras": []},
+        status=200,
+    )
+    client = VancamClient(api_key="k")
+    result = client.radius(lat=49.28, lon=-123.12, radius=1.0, limit=10)
+
+    assert result == {"cameras": []}
+    request = responses.calls[0].request
+    assert request.headers["x-api-key"] == "k"
+    assert "lat=49.28" in request.url
+    assert "radius=1.0" in request.url
+
+
+@responses.activate
+def test_nearest_sets_nearest_flag():
+    responses.add(
+        responses.GET,
+        f"{DEFAULT_BASE_URL}/cameras/cameras",
+        json={"cameras": []},
+        status=200,
+    )
+    client = VancamClient(api_key="k")
+    client.nearest(lat=1.0, lon=2.0, limit=5)
+
+    request = responses.calls[0].request
+    assert "nearest=true" in request.url
+
+
+@responses.activate
+def test_limit_is_clamped_to_max():
+    responses.add(
+        responses.GET,
+        f"{DEFAULT_BASE_URL}/cameras/cameras",
+        json={"cameras": []},
+        status=200,
+    )
+    client = VancamClient(api_key="k")
+    client.radius(lat=1.0, lon=2.0, radius=1.0, limit=10_000)
+
+    request = responses.calls[0].request
+    assert f"limit={MAX_LIMIT}" in request.url
+
+
+@responses.activate
+def test_get_camera_uses_asset_id_param():
+    responses.add(
+        responses.GET,
+        f"{DEFAULT_BASE_URL}/cameras/cameras",
+        json={"asset_id": "30145"},
+        status=200,
+    )
+    client = VancamClient(api_key="k")
+    result = client.get_camera("30145")
+
+    assert result == {"asset_id": "30145"}
+    assert "asset_id=30145" in responses.calls[0].request.url
+
+
+def test_no_api_key_raises_before_request():
+    client = VancamClient(api_key="k")
+    client.api_key = ""
+    with pytest.raises(VancamAPIError, match="No API key set"):
+        client.radius(lat=1.0, lon=2.0, radius=1.0)
+
+
+@responses.activate
+def test_403_raises_with_status_code():
+    responses.add(
+        responses.GET,
+        f"{DEFAULT_BASE_URL}/cameras/cameras",
+        status=403,
+    )
+    client = VancamClient(api_key="k")
+    with pytest.raises(VancamAPIError) as exc_info:
+        client.radius(lat=1.0, lon=2.0, radius=1.0)
+    assert exc_info.value.status_code == 403
+
+
+@responses.activate
+def test_429_raises_with_status_code():
+    responses.add(
+        responses.GET,
+        f"{DEFAULT_BASE_URL}/cameras/cameras",
+        status=429,
+    )
+    client = VancamClient(api_key="k")
+    with pytest.raises(VancamAPIError) as exc_info:
+        client.radius(lat=1.0, lon=2.0, radius=1.0)
+    assert exc_info.value.status_code == 429
+
+
+@responses.activate
+def test_request_exception_wrapped_as_api_error():
+    responses.add(
+        responses.GET,
+        f"{DEFAULT_BASE_URL}/cameras/cameras",
+        body=requests.exceptions.ConnectionError("boom"),
+    )
+    client = VancamClient(api_key="k")
+    with pytest.raises(VancamAPIError, match="Request failed"):
+        client.radius(lat=1.0, lon=2.0, radius=1.0)
+
+
+def test_image_url_format():
+    client = VancamClient(api_key="k", base_url="https://api.vancam.ai")
+    assert client.image_url("30145") == "https://api.vancam.ai/api?asset_id=30145"
+
+
+@responses.activate
+def test_fetch_image_returns_bytes():
+    responses.add(
+        responses.GET,
+        f"{DEFAULT_BASE_URL}/api",
+        body=b"binary-image-data",
+        status=200,
+    )
+    client = VancamClient(api_key="k")
+    assert client.fetch_image("30145") == b"binary-image-data"
+
+
+def test_fetch_image_no_api_key_raises():
+    client = VancamClient(api_key="k")
+    client.api_key = ""
+    with pytest.raises(VancamAPIError, match="No API key set"):
+        client.fetch_image("30145")

vancam-0.1.0/vancam.egg-info/PKG-INFO

@@ -0,0 +1,141 @@
+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

vancam-0.1.0/vancam.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+tests/test_cli.py
+tests/test_client.py
+vancam.egg-info/PKG-INFO
+vancam.egg-info/SOURCES.txt
+vancam.egg-info/dependency_links.txt
+vancam.egg-info/entry_points.txt
+vancam.egg-info/requires.txt
+vancam.egg-info/top_level.txt
+vancam_cli/__init__.py
+vancam_cli/cli.py
+vancam_cli/client.py

vancam-0.1.0/vancam.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vancam-0.1.0/vancam.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vancam = vancam_cli.cli:main

vancam-0.1.0/vancam.egg-info/requires.txt

@@ -0,0 +1,6 @@
+requests>=2.31.0
+python-dotenv>=1.0.0
+
+[test]
+pytest>=8.0.0
+responses>=0.25.0

vancam-0.1.0/vancam.egg-info/top_level.txt

@@ -0,0 +1 @@
+vancam_cli

vancam-0.1.0/vancam_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Vancam CLI — thin client over the api.vancam.ai REST API."""
+
+__version__ = "0.1.0"

vancam-0.1.0/vancam_cli/cli.py

@@ -0,0 +1,157 @@
+"""vancam — CLI for the Vancam camera spatial search API."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Optional
+
+from dotenv import find_dotenv, load_dotenv
+
+from .client import VancamAPIError, VancamClient, DEFAULT_BASE_URL
+
+# usecwd=True: search from the user's current directory, not the installed
+# package's location (python-dotenv's default walks up from __file__, which
+# would silently pick up this repo's own .env regardless of where the CLI
+# is actually run from).
+load_dotenv(find_dotenv(usecwd=True))
+
+
+def _print_json(data, compact: bool) -> None:
+    if compact:
+        print(json.dumps(data, separators=(",", ":")))
+    else:
+        print(json.dumps(data, indent=2))
+
+
+def _client_from_args(args: argparse.Namespace) -> VancamClient:
+    return VancamClient(api_key=args.api_key, base_url=args.base_url)
+
+
+def cmd_radius(args: argparse.Namespace) -> Any:
+    return _client_from_args(args).radius(args.lat, args.lon, args.radius, args.limit)
+
+
+def cmd_nearest(args: argparse.Namespace):
+    return _client_from_args(args).nearest(args.lat, args.lon, args.limit)
+
+
+def cmd_route(args: argparse.Namespace):
+    return _client_from_args(args).route(
+        args.origin_lat, args.origin_lon, args.dest_lat, args.dest_lon, args.buffer, args.limit
+    )
+
+
+def cmd_bounds(args: argparse.Namespace):
+    return _client_from_args(args).bounds(
+        args.min_lat, args.min_lon, args.max_lat, args.max_lon, args.limit
+    )
+
+
+def cmd_get(args: argparse.Namespace):
+    return _client_from_args(args).get_camera(args.asset_id)
+
+
+def cmd_image(args: argparse.Namespace):
+    client = _client_from_args(args)
+    if args.output:
+        data = client.fetch_image(args.asset_id)
+        with open(args.output, "wb") as f:
+            f.write(data)
+        print(f"Saved to {args.output}", file=sys.stderr)
+        return None
+    return {"image_url": client.image_url(args.asset_id)}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    # Shared as a `parents=[...]` mixin so these flags work both before AND
+    # after the subcommand (argparse doesn't inherit parent-only args to
+    # subparsers otherwise).
+    #
+    # Two copies are needed: the top-level parser needs real defaults so
+    # `args.compact` etc. always exist, but if the *subparser* copy also
+    # carried those defaults, it would silently reset any value already set
+    # by the top-level parser back to the default when the flag isn't
+    # repeated after the subcommand (argparse parses both parsers into the
+    # same Namespace). default=SUPPRESS on the subparser copy makes it only
+    # write when the flag is actually given after the subcommand.
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--api-key", help="API key (default: VANCAM_API_KEY env var)")
+    common.add_argument("--base-url", default=DEFAULT_BASE_URL, help=argparse.SUPPRESS)
+    common.add_argument("--compact", action="store_true", help="Compact JSON output")
+
+    common_sub = argparse.ArgumentParser(add_help=False)
+    common_sub.add_argument("--api-key", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+    common_sub.add_argument("--base-url", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+    common_sub.add_argument(
+        "--compact", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS
+    )
+
+    parser = argparse.ArgumentParser(
+        prog="vancam",
+        description="Query the Vancam camera spatial search API (api.vancam.ai).",
+        parents=[common],
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("radius", help="Cameras within a radius (km) of a point", parents=[common_sub])
+    p.add_argument("--lat", type=float, required=True)
+    p.add_argument("--lon", type=float, required=True)
+    p.add_argument("--radius", type=float, default=1.0, help="km, max 50 (default: 1.0)")
+    p.add_argument("--limit", type=int, default=50)
+    p.set_defaults(func=cmd_radius)
+
+    p = sub.add_parser("nearest", help="N nearest cameras to a point", parents=[common_sub])
+    p.add_argument("--lat", type=float, required=True)
+    p.add_argument("--lon", type=float, required=True)
+    p.add_argument("--limit", type=int, default=5)
+    p.set_defaults(func=cmd_nearest)
+
+    p = sub.add_parser("route", help="Cameras along a straight-line route", parents=[common_sub])
+    p.add_argument("--origin-lat", type=float, required=True)
+    p.add_argument("--origin-lon", type=float, required=True)
+    p.add_argument("--dest-lat", type=float, required=True)
+    p.add_argument("--dest-lon", type=float, required=True)
+    p.add_argument("--buffer", type=float, default=100.0, help="corridor width in meters")
+    p.add_argument("--limit", type=int, default=50)
+    p.set_defaults(func=cmd_route)
+
+    p = sub.add_parser("bounds", help="Cameras inside a bounding box", parents=[common_sub])
+    p.add_argument("--min-lat", type=float, required=True)
+    p.add_argument("--min-lon", type=float, required=True)
+    p.add_argument("--max-lat", type=float, required=True)
+    p.add_argument("--max-lon", type=float, required=True)
+    p.add_argument("--limit", type=int, default=100)
+    p.set_defaults(func=cmd_bounds)
+
+    p = sub.add_parser("get", help="Camera details by asset ID", parents=[common_sub])
+    p.add_argument("asset_id")
+    p.set_defaults(func=cmd_get)
+
+    p = sub.add_parser("image", help="Get (or save) a camera's live image", parents=[common_sub])
+    p.add_argument("asset_id")
+    p.add_argument("-o", "--output", help="Save image to this file instead of printing the URL")
+    p.set_defaults(func=cmd_image)
+
+    return parser
+
+
+def main(argv: Optional[list] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        result = args.func(args)
+    except VancamAPIError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    if result is not None:
+        _print_json(result, args.compact)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

vancam-0.1.0/vancam_cli/client.py

@@ -0,0 +1,147 @@
+"""Thin HTTP client for the Vancam REST API (api.vancam.ai)."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+import requests
+
+DEFAULT_BASE_URL = "https://api.vancam.ai"
+DEFAULT_TIMEOUT_SECONDS = 15
+MAX_LIMIT = 100
+
+# Shared, low-limit key (1 req/s, 500/month) — meant to be public, used when
+# the caller hasn't set a personal key. Get a personal free-tier key (higher
+# limits, 5 req/s, 500/month) from the web app's /account page.
+ANONYMOUS_SHARED_API_KEY = "abwSAo91eI8wENsNrZFUE7tC6qGkh9Tw66x4cfcQ"
+
+
+class VancamAPIError(RuntimeError):
+    def __init__(self, message: str, status_code: Optional[int] = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class VancamClient:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = DEFAULT_TIMEOUT_SECONDS,
+    ):
+        self.api_key = api_key or os.getenv("VANCAM_API_KEY", ANONYMOUS_SHARED_API_KEY)
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _headers(self) -> Dict[str, str]:
+        return {"x-api-key": self.api_key} if self.api_key else {}
+
+    def _get(self, path: str, params: Dict[str, Any]) -> Any:
+        if not self.api_key:
+            raise VancamAPIError(
+                "No API key set. Set VANCAM_API_KEY in your environment or pass --api-key.\n"
+                "Get a free key from your account dashboard at https://vancam.ai/account."
+            )
+
+        clean = {k: v for k, v in params.items() if v is not None}
+        if "limit" in clean:
+            clean["limit"] = max(1, min(int(clean["limit"]), MAX_LIMIT))
+
+        url = f"{self.base_url}{path}"
+        try:
+            response = requests.get(
+                url, params=clean, headers=self._headers(), timeout=self.timeout
+            )
+        except requests.exceptions.RequestException as e:
+            raise VancamAPIError(f"Request failed: {e}") from e
+
+        if response.status_code == 403:
+            raise VancamAPIError(
+                "403 Forbidden — missing or invalid API key.", status_code=403
+            )
+        if response.status_code == 429:
+            raise VancamAPIError(
+                "429 Too Many Requests — rate limit exceeded for your plan.",
+                status_code=429,
+            )
+        try:
+            response.raise_for_status()
+        except requests.exceptions.HTTPError as e:
+            raise VancamAPIError(
+                f"HTTP error {response.status_code}: {response.text}",
+                status_code=response.status_code,
+            ) from e
+
+        return response.json()
+
+    def radius(self, lat: float, lon: float, radius: float, limit: Optional[int] = None) -> Any:
+        return self._get(
+            "/cameras/cameras",
+            {"lat": lat, "lon": lon, "radius": radius, "limit": limit},
+        )
+
+    def nearest(self, lat: float, lon: float, limit: Optional[int] = None) -> Any:
+        return self._get(
+            "/cameras/cameras",
+            {"lat": lat, "lon": lon, "nearest": "true", "limit": limit},
+        )
+
+    def route(
+        self,
+        origin_lat: float,
+        origin_lon: float,
+        dest_lat: float,
+        dest_lon: float,
+        buffer: Optional[float] = None,
+        limit: Optional[int] = None,
+    ) -> Any:
+        return self._get(
+            "/cameras/cameras",
+            {
+                "origin_lat": origin_lat,
+                "origin_lon": origin_lon,
+                "dest_lat": dest_lat,
+                "dest_lon": dest_lon,
+                "buffer": buffer,
+                "limit": limit,
+            },
+        )
+
+    def bounds(
+        self,
+        min_lat: float,
+        min_lon: float,
+        max_lat: float,
+        max_lon: float,
+        limit: Optional[int] = None,
+    ) -> Any:
+        return self._get(
+            "/cameras/cameras",
+            {
+                "min_lat": min_lat,
+                "min_lon": min_lon,
+                "max_lat": max_lat,
+                "max_lon": max_lon,
+                "limit": limit,
+            },
+        )
+
+    def get_camera(self, asset_id: str) -> Any:
+        return self._get("/cameras/cameras", {"asset_id": asset_id})
+
+    def image_url(self, asset_id: str) -> str:
+        return f"{self.base_url}/api?asset_id={asset_id}"
+
+    def fetch_image(self, asset_id: str) -> bytes:
+        if not self.api_key:
+            raise VancamAPIError(
+                "No API key set. Set VANCAM_API_KEY in your environment or pass --api-key."
+            )
+        url = self.image_url(asset_id)
+        try:
+            response = requests.get(url, headers=self._headers(), timeout=self.timeout)
+            response.raise_for_status()
+        except requests.exceptions.RequestException as e:
+            raise VancamAPIError(f"Image fetch failed: {e}") from e
+        return response.content