tracking-pettracer-location

# Tracking PetTracer pet location ## Why this exists PetTracer exposes an (unofficial) web portal API used by their apps/website. This skill gives a reliable, low-drama workflow for: - **Current location** (latest known point) - **Recent route/history** (time-windowed points) - **Near-real-time updates** (WebSocket push, optional) It is designed to minimise API load (be respectful) and to produce **consistent, copy/paste-friendly outputs**. ## Quick start ### Snapshot location (recommended default) 1. Set credentials (prefer env vars, not CLI args): ```bash export PETTRACER_USERNAME="you@example.com" export PETTRACER_PASSWORD="••••••••" ``` 2. List devices: ```bash python scripts/pettracer_cli.py list --format json --pretty ``` 3. Locate a pet: - By name: ```bash python scripts/pettracer_cli.py locate --pet "Fluffy" --format json --pretty ``` - By id: ```bash python scripts/pettracer_cli.py locate --device-id 12345 --format json --pretty ``` - If the account has **exactly one collar**, you can omit `--pet/--device-id`: ```bash python scripts/pettracer_cli.py locate --format json --pretty ``` ### Get location history (last 6 hours) ```bash python scripts/pettracer_cli.py history --pet "Fluffy" --hours 6 --format json --pretty ``` ## Core workflow the agent should follow ### 1) Decide: snapshot vs history vs live updates - **Snapshot**: user asks “where is X right now?” → use `locate`. - **History**: user asks “where has X been today/last hour?” → use `history`. - **Live**: user wants continuous updates → use WebSocket (see [references/websocket.md](references/websocket.md)). Default to **snapshot** unless the user explicitly wants a route or live tracking. ### 2) Authenticate safely Preferred order: 1. Use `PETTRACER_TOKEN` if already available. 2. Else login with `PETTRACER_USERNAME` + `PETTRACER_PASSWORD` (or `PETTRACER_EMAIL`). **Never** ask the user to paste tokens into chat. Ask them to set env vars or store secrets in their vault. Optional overrides (useful for debugging / future-proofing): - `PETTRACER_API_BASE` (REST base; default `https://portal.pettracer.com/api`) - `PETTRACER_WS_BASE` (WebSocket base; default `wss://pt.pettracer.com/sc`) ### 3) Identify the right device - Fetch devices via `GET /api/map/getccs` (wrapped by `pettracer_cli.py list`). - Match by `details.name` case-insensitively. - If multiple matches: show a disambiguation list (id + name) and ask the user which one. - If no match: show available device names. - If the account has exactly one collar, you can default to it. ### 4) Fetch location data - **Current location** comes from `device.lastPos` (collars) or top-level `posLat/posLong` (HomeStations): - `posLat`, `posLong` - `timeMeasure` (timestamp) - `acc` (accuracy, metres) or `horiPrec` (fallback) - **History** uses `POST /api/map/getccpositions` with: - `devId`, `filterTime` (ms), `toTime` (ms) See [references/endpoints.md](references/endpoints.md) and [references/data-model.md](references/data-model.md). ### 5) Present results consistently When reporting location, include: - Pet name + device id - Coordinates (lat, lon) - Last update time - Accuracy (if present) - How old the fix is (seconds/minutes since last fix), if possible - Optional: a map link (Google Maps + OpenStreetMap) **Preferred JSON shape (for tool-to-tool handoff):** ```json { "pet": { "id": 12345, "name": "Fluffy" }, "last_fix": { "lat": 48.137154, "lon": 11.576124, "time": "2026-02-25T12:34:56+00:00", "accuracy_m": 12 }, "last_fix_age_s": 90, "battery_mv": 4012, "battery_percent_est": 78, "home": false, "links": { "google_maps": "https://www.google.com/maps?q=48.137154,11.576124", "openstreetmap": "https://www.openstreetmap.org/?mlat=48.137154&mlon=11.576124#map=18/48.137154/11.576124" } } ``` Notes: - `battery_percent_est` is an **estimate** derived from voltage (PetTracer reports millivolts, not %). - If there’s no GPS fix, report `error=no_recent_fix` and include `last_contact`. ## Live tracking (optional, avoid aggressive polling) If you need frequent updates: - Prefer WebSocket push (avoid aggressive polling). - Only fall back to polling if WebSocket is not possible; keep polling ≥ 60s by default. Install dependency: ```bash pip install aiohttp ``` Then run: ```bash python scripts/pettracer_watch.py --pet "Fluffy" ``` See: - [references/websocket.md](references/websocket.md) - `scripts/pettracer_watch.py` for a working SockJS/STOMP implementation. ## Troubleshooting playbook ### No location / `lastPos` is missing Common reasons: - Collar hasn’t reported a GPS fix recently (indoors, low signal). - Battery low / collar off. - Subscription expired. Action: - Report “no recent fix” and show `lastContact` if available. - Suggest switching to a higher-frequency mode (Fast/Live) in the PetTracer app/portal **only if the user asks** (see [references/modes.md](references/modes.md)). ### Auth failures (401 / invalid_auth) - Re-login to obtain a fresh `access_token`. - Confirm the login payload uses keys `login` + `password` (not `username`). ### Rate limiting / service respect - Avoid tight loops against `/map/getccs`. - Prefer WebSocket for near-real-time tracking. ## THE EXACT PROMPT — Location response format Use this when the user wants a human-readable answer: ``` Give the pet’s latest known PetTracer location. Include: - Pet name + device id - Time of last fix (and last contact if different) - Coordinates + map link(s) - Accuracy (metres) if present - One-line assessment: “recent fix” vs “stale fix” (use last_fix_age_s if available; interpret in the context of the current tracking mode) ```