{"skill":{"slug":"tracking-pettracer-location","displayName":"petTracer pet tracking","summary":"Tracks a pet’s location via the PetTracer portal API (snapshot, history, and live updates). Generates a shareable map screenshot (PNG) for the latest locatio...","description":"---\nname: tracking-pettracer-location\ndescription: >-\n  Tracks a pet’s location via the PetTracer portal API (snapshot, history, and live updates).\n  Generates a shareable map screenshot (PNG) for the latest location.\n  Use when user asks where their pet is, needs GPS coordinates, location history, live tracking,\n  or a map image / screenshot of the pet’s location.\n---\n\n# Tracking PetTracer location (and generating map screenshots)\n\n## Why this skill exists\n\nPetTracer collar tracking is exposed via an **unofficial** web portal API and a SockJS/STOMP WebSocket.\nThis skill provides a reliable, repeatable workflow to:\n\n- Get a pet’s **latest known location** (REST snapshot)\n- Fetch **location history** for a time window\n- Subscribe to **live updates** (WebSocket)\n- Generate a **map screenshot image (PNG)** you can send to the user\n\n## Quick start\n\n### 1) Set credentials (preferred)\n\n```bash\nexport PETTRACER_USERNAME=\"you@example.com\"\nexport PETTRACER_PASSWORD=\"…\"\n```\n\n### 2) (For map screenshots) Set Google Maps Static API key\n\n```bash\nexport GOOGLE_MAPS_API_KEY=\"…\"\n```\n\n### 3) Get the latest location (JSON)\n\n```bash\npython scripts/pettracer_cli.py locate --pet \"Fluffy\" --pretty\n```\n\n### 4) Generate a map screenshot PNG for the latest location\n\n```bash\npython scripts/pettracer_mapshot.py --pet \"Fluffy\" --pretty\n# → writes a PNG under ./output/ and prints JSON with the file path\n```\n\n## Capabilities\n\n### Snapshot (latest fix)\n\n- `scripts/pettracer_cli.py locate` — latest known lat/lon + timestamps + battery + helpful links\n\n### History (time window)\n\n- `scripts/pettracer_cli.py history` — list of points for the last N hours or an explicit time range\n\n### Live tracking\n\n- `scripts/pettracer_watch.py` — NDJSON stream of live updates via SockJS/STOMP\n\n### Map screenshot (PNG)\n\n- `scripts/pettracer_mapshot.py` — downloads a static map image centred on the latest fix\n\nSee: `references/maps.md`\n\n## Required inputs\n\n### PetTracer auth (choose one)\n\n**Option A (preferred):**\n- `PETTRACER_USERNAME` (or `PETTRACER_EMAIL`)\n- `PETTRACER_PASSWORD`\n\n**Option B:**\n- `PETTRACER_TOKEN` (bearer token)\n\n### Maps auth (for screenshots)\n\n- `GOOGLE_MAPS_API_KEY`\n\nOptional tuning:\n- `GOOGLE_MAPS_MAPTYPE` (`hybrid` default)\n- `GOOGLE_MAPS_SIZE` (`640x640` default)\n- `GOOGLE_MAPS_SCALE` (`2` default)\n\n## Core workflow (agent)\n\n1) **Decide what the user wants**:\n   - “Where is my pet right now?” → snapshot (`locate`)\n   - “Where has my pet been today?” → history (`history`)\n   - “Track live for 5 minutes” → live (`pettracer_watch.py`)\n   - “Send me a screenshot/map image” → map screenshot (`pettracer_mapshot.py`)\n\n2) **Resolve which device**:\n   - If user names the pet → pass `--pet \"Name\"`\n   - If ambiguous/multiple devices → run `list` and pick by `id` or exact name match\n\n3) **Run the smallest command that answers the request**.\n\n4) **Validate freshness**:\n   - Use `last_fix_age_s` to decide whether the fix is stale.\n   - If stale or missing: say so plainly; provide `last_contact` and suggest switching collar mode in the official app.\n\n5) **If user asked for a map screenshot**:\n   - Run `pettracer_mapshot.py`.\n   - Attach/send the generated PNG.\n   - Also include the interactive map link for convenience.\n\n## Commands\n\n### List devices\n\n```bash\npython scripts/pettracer_cli.py list --pretty\n```\n\n### Locate a pet\n\n```bash\npython scripts/pettracer_cli.py locate --pet \"Fluffy\" --pretty\n\n# If multiple devices, disambiguate:\npython scripts/pettracer_cli.py locate --device-id 12345 --pretty\n```\n\n### Location history\n\n```bash\n# last 6 hours (default)\npython scripts/pettracer_cli.py history --pet \"Fluffy\" --pretty\n\n# last 24 hours\npython scripts/pettracer_cli.py history --pet \"Fluffy\" --hours 24 --pretty\n\n# explicit window (epoch ms)\npython scripts/pettracer_cli.py history --device-id 12345 --from-ms 1767152926491 --to-ms 1767174526491 --pretty\n```\n\n### Live updates (NDJSON)\n\n```bash\n# Install dependency\npip install -r scripts/requirements.txt\n\n# Stream updates\npython scripts/pettracer_watch.py --pet \"Fluffy\"\n```\n\n### Map screenshot (PNG)\n\n```bash\n# Writes ./output/pettracer_<pet>_<id>_<ts>.png\npython scripts/pettracer_mapshot.py --pet \"Fluffy\" --pretty\n\n# Choose output path\npython scripts/pettracer_mapshot.py --pet \"Fluffy\" --out output/fluffy_latest.png --pretty\n\n# Tune map appearance\nGOOGLE_MAPS_MAPTYPE=satellite python scripts/pettracer_mapshot.py --pet \"Fluffy\" --zoom 18 --pretty\n```\n\n## Present results consistently\n\nWhen answering the user, prefer:\n\n- **Human summary**: “Latest fix at HH:MM, accuracy ~X m, battery ~Y%.”\n- **Freshness**: say if stale: “Fix is ~N minutes old.”\n- **Map link(s)**: include the `google_maps` and `openstreetmap` links.\n- **If map screenshot requested**: send/attach the PNG generated by `pettracer_mapshot.py`.\n\n## Security / privacy rules\n\n- Never paste `PETTRACER_PASSWORD`, `PETTRACER_TOKEN`, or `GOOGLE_MAPS_API_KEY` into chat.\n- Avoid printing URLs that contain secrets (PetTracer WebSocket URLs include `access_token=…`).\n- If you must log, redact secrets.\n\n## Reference files\n\n- PetTracer REST endpoints: `references/endpoints.md`\n- Data model fields: `references/data-model.md`\n- Tracking modes (heuristics): `references/modes.md`\n- WebSocket protocol notes: `references/websocket.md`\n- Map screenshots: `references/maps.md`\n\n## THE EXACT PROMPT — “Send me a map screenshot”\n\n```\n1) Run pettracer_mapshot.py for the requested pet/device.\n2) If it returns no_recent_fix, explain that and include last_contact.\n3) If it returns an image path, attach/send that PNG to the user.\n4) In the message: include timestamp, fix age, accuracy, and a clickable Google Maps link.\n5) Do not reveal any API keys/tokens.\n```\n","tags":{"latest":"1.0.1"},"stats":{"comments":0,"downloads":212,"installsAllTime":1,"installsCurrent":1,"stars":0,"versions":2},"createdAt":1772017613255,"updatedAt":1778491636632},"latestVersion":{"version":"1.0.1","createdAt":1772086783653,"changelog":"**Map screenshot generation added for latest pet location.**\n\n- Added ability to generate and send a shareable PNG map screenshot of the pet’s latest location using Google Maps Static API.\n- New script: `scripts/pettracer_mapshot.py` fetches a static map image centered on the last GPS fix.\n- Detailed instructions for map image generation, including required `GOOGLE_MAPS_API_KEY`.\n- Updated documentation to cover new screenshot capability and clarify user-facing answer format.\n- Added reference: `references/maps.md` for map image implementation and tuning.","license":null},"metadata":null,"owner":{"handle":"tristanmanchester","userId":"s17c3xv8wvvzzbj84z9vcj498n83gnkp","displayName":"Tristan Manchester","image":"https://avatars.githubusercontent.com/u/108270628?v=4"},"moderation":null}