vancam 0.1.0__py3-none-any.whl

vancam-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+vancam-0.1.0.dist-info/licenses/LICENSE,sha256=xw_AVv_gOYHukLSKhzf5gg48NBvNXr11CTSO0KvWhts,1059
+vancam_cli/__init__.py,sha256=9wh8wr5RSdg6u4Gy2v6VNFGo_31PXErJTe60x9DbbVQ,89
+vancam_cli/cli.py,sha256=hHAwevH9EiPN6rLaplBJPlgVP1kBUJoQyBJAmPQdz20,6057
+vancam_cli/client.py,sha256=QbFIvoPoFFWHDV8tPSyKHRmVLUL59Uxkt5qCHRnDtEw,4925
+vancam-0.1.0.dist-info/METADATA,sha256=22ioo4lAdrYH1rciBp_401gZ2mnmYwiZ23PgPRpdTrQ,4919
+vancam-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+vancam-0.1.0.dist-info/entry_points.txt,sha256=pog7gu__k-KHZjiQdi3f-lPyKs1AV6HbgkLiMClYnAw,47
+vancam-0.1.0.dist-info/top_level.txt,sha256=_og1te7KFo_AfOmYQIt2Kz6qe_t2oUNWEjPxPMXCigc,11
+vancam-0.1.0.dist-info/RECORD,,

vancam-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vancam-0.1.0.dist-info/entry_points.txt

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

vancam-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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

vancam_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Vancam CLI — thin client over the api.vancam.ai REST API."""
+
+__version__ = "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_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