# Maps > maps - Skill: `yakeworld/maps` (Agent Skill, multi-file: 14 files) - Install (CLI): `npx skillmds@latest add yakeworld/maps` - Raw SKILL.md: https://api.skillmd.com/api/skills/yakeworld/maps/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: yakeworld (https://skillmd.com/u/yakeworld) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/yakeworld/maps --- ## Operational Steps 1. 确认输入参数完整 2. 执行核心操作（参考本目录下的 scripts/ 或 references/） 3. 验证输出符合契约 4. 保存结果并报告 related_skills: [] requires_toolsets: - terminal supersedes: - find-nearby synthos: author: Mibayy signature: 'query: str -> geo_data: dict' related_skills: - airtable - chinese-form-automation - google-workspace - jupyter-live-kernel - linear version: 1.2.0 ## IO_CONTRACT - **input**: `request: str, context: dict` — 用户请求描述、上下文信息 - **output**: `result: dict — 技能执行结果（结构因技能而异）` > 对应原则：P2（机械原子暴露输入输出规范） # Maps Skill Location intelligence using free, open data sources. 8 commands, 44 POI categories, zero dependencies (Python stdlib only), no API key required. Data sources: OpenStreetMap/Nominatim, Overpass API, OSRM, TimeAPI.io. This skill supersedes the old `find-nearby` skill — all of find-nearby's functionality is covered by the `nearby` command below, with the same `--near ""` shortcut and multi-category support. ## When to Use - User sends a Telegram location pin (latitude/longitude in the message) → `nearby` - User wants coordinates for a place name → `search` - User has coordinates and wants the address → `reverse` - User asks for nearby restaurants, hospitals, pharmacies, hotels, etc. → `nearby` - User wants driving/walking/cycling distance or travel time → `distance` - User wants turn-by-turn directions between two places → `directions` - User wants timezone information for a location → `timezone` - User wants to search for POIs within a geographic area → `area` + `bbox` ## Prerequisites Python 3.8+ (stdlib only — no pip installs needed). Script path: `~/.hermes/skills/maps/scripts/maps_client.py` ## Commands ```bash MAPS=~/.hermes/skills/maps/scripts/maps_client.py ``` ### search — Geocode a place name ```bash python3 $MAPS search "Eiffel Tower" python3 $MAPS search "1600 Pennsylvania Ave, Washington DC" ``` Returns: lat, lon, display name, type, bounding box, importance score. ### reverse — Coordinates to address ```bash python3 $MAPS reverse 48.8584 2.2945 ``` Returns: full address breakdown (street, city, state, country, postcode). ### nearby — Find places by category ```bash # By coordinates (from a Telegram location pin, for example) python3 $MAPS nearby 48.8584 2.2945 restaurant --limit 10 python3 $MAPS nearby 40.7128 -74.0060 hospital --radius 2000 # By address / city / zip / landmark — --near auto-geocodes python3 $MAPS nearby --near "Times Square, New York" --category cafe python3 $MAPS nearby --near "90210" --category pharmacy # Multiple categories merged into one query python3 $MAPS nearby --near "downtown austin" --category restaurant --category bar --limit 10 ``` 46 categories: restaurant, cafe, bar, hospital, pharmacy, hotel, guest_house, camp_site, supermarket, atm, gas_station, parking, museum, park, school, university, bank, police, fire_station, library, airport, train_station, bus_stop, church, mosque, synagogue, dentist, doctor, cinema, theatre, gym, swimming_pool, post_office, convenience_store, bakery, bookshop, laundry, car_wash, car_rental, bicycle_rental, taxi, veterinary, zoo, playground, stadium, nightclub. Each result includes: `name`, `address`, `lat`/`lon`, `distance_m`, `maps_url` (clickable Google Maps link), `directions_url` (Google Maps directions from the search point), and promoted tags when available — `cuisine`, `hours` (opening_hours), `phone`, `website`. ### distance — Travel distance and time ```bash python3 $MAPS distance "Paris" --to "Lyon" python3 $MAPS distance "New York" --to "Boston" --mode driving python3 $MAPS distance "Big Ben" --to "Tower Bridge" --mode walking ``` Modes: driving (default), walking, cycling. Returns road distance, duration, and straight-line distance for comparison. ### directions — Turn-by-turn navigation ```bash python3 $MAPS directions "Eiffel Tower" --to "Louvre Museum" --mode walking python3 $MAPS directions "JFK Airport" --to "Times Square" --mode driving ``` Returns numbered steps with instruction, distance, duration, road name, and maneuver type (turn, depart, arrive, etc.). ### timezone — Timezone for coordinates ```bash python3 $MAPS timezone 48.8584 2.2945 python3 $MAPS timezone 35.6762 139.6503 ``` Returns timezone name, UTC offset, and current local time. ### area — Bounding box and area for a place ```bash python3 $MAPS area "Manhattan, New York" python3 $MAPS area "London" ``` Returns bounding box coordinates, width/height in km, and approximate area. Useful as input for the bbox command. ### bbox — Search within a bounding box ```bash python3 $MAPS bbox 40.75 -74.00 40.77 -73.98 restaurant --limit 20 ``` Finds POIs within a geographic rectangle. Use `area` first to get the bounding box coordinates for a named place. ## Working With Telegram Location Pins When a user sends a location pin, the message contains `latitude:` and `longitude:` fields. Extract those and pass them straight to `nearby`: ```bash # User sent a pin at 36.17, -115.14 and asked "find cafes nearby" python3 $MAPS nearby 36.17 -115.14 cafe --radius 1500 ``` Present results as a numbered list with names, distances, and the `maps_url` field so the user gets a tap-to-open link in chat. For "open now?" questions, check the `hours` field; if missing or unclear, verify with `web_search` since OSM hours are community-maintained and not always current. ## Workflow Examples **"Find Italian restaurants near the Colosseum":** 1. `nearby --near "Colosseum Rome" --category restaurant --radius 500` — one command, auto-geocoded **"What's near this location pin they sent?":** 1. Extract lat/lon from the Telegram message 2. `nearby LAT LON cafe --radius 1500` **"How do I walk from hotel to conference center?":** 1. `directions "Hotel Name" --to "Conference Center" --mode walking` **"What restaurants are in downtown Seattle?":** 1. `area "Downtown Seattle"` → get bounding box 2. `bbox S W N E restaurant --limit 30` ## Pitfalls - Nominatim ToS: max 1 req/s (handled automatically by the script) - `nearby` requires lat/lon OR `--near "
"` — one of the two is needed - OSRM routing coverage is best for Europe and North America - Overpass API can be slow during peak hours; the script automatically falls back between mirrors (overpass-api.de → overpass.kumi.systems) - `distance` and `directions` use `--to` flag for the destination (not positional) - If a zip code alone gives ambiguous results globally, include country/state ## Verification ```bash python3 ~/.hermes/skills/maps/scripts/maps_client.py search "Statue of Liberty" # Should return lat ~40.689, lon ~-74.044 python3 ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "Times Square" --category restaurant --limit 3 # Should return a list of restaurants within ~500m of Times Square ``` ## 验证清单 · VERIFICATION - [ ] `search` 基准通过："Statue of Liberty" 返回 lat ~40.689、lon ~-74.044 - [ ] `nearby` 基准通过：`--near "Times Square" --category restaurant --limit 3` 返回 ~500m 内餐厅列表 - [ ] `nearby` 调用提供了 lat/lon 或 `--near` 之一；全球歧义输入（仅邮编/通用名）已补充国家/州 - [ ] `distance`/`directions` 目的地使用 `--to` 标志并指定出行模式（driving/walking/cycling） - [ ] 区域 POI 查询先 `area` 获取边界框再调 `bbox`；请求频率 ≤1 req/s - [ ] "现在营业?" 类问题已核对 `hours` 字段，缺失/模糊时经 `web_search` 复核 ## 约束规则 · RULES 1. **输入约束**: 参数类型、范围、格式必须校验 2. **输出约束**: 返回值结构、编码、命名必须一致 3. **异常约束**: 错误信息必须包含上下文和恢复建议 4. **安全约束**: 不执行未验证的任意代码，不暴露内部状态 ## Golden 集合 · GOLDEN SET - **Golden Input**: 标准输入样本（覆盖正常路径） - **Golden Output**: 预期输出（精确匹配或格式校验） - **Golden Error**: 预期错误信息（覆盖失败路径） > Golden 集合是测试的单一真理来源。所有改进必须通过 golden 测试。 > 违反规则的操作视为不安全，必须拒绝或隔离。 > 每项验证必须可执行、可记录、可复现。验证失败时记录原因和修复。 # Maps ## Genes (策略基因) > 紧凑策略表示。条件→策略。需要深度时参考完整文档。 - **[MAPS-001]** 用户发送包含经纬度的定位信息 → 直接提取坐标并调用 `nearby` 命令，避免二次地理编码 - **[MAPS-002]** 需要查询特定区域内的 POI 而非单点周边 → 先使用 `area` 获取边界框，再结合 `bbox` 进行矩形区域搜索 - **[MAPS-003]** 查询地点名称存在全球歧义（如仅邮编或通用名） → 在输入中显式包含国家或州名以消除歧义 - **[MAPS-004]** 需要计算两点间的路径距离或时间 → 使用 `distance` 命令并明确指定 `--to` 标志及出行模式（驾车/步行/骑行） - **[MAPS-005]** 用户询问附近设施是否“现在营业” → 优先检查 OSM 返回的 `hours` 字段，若缺失或模糊则通过 `web_search` 验证 - **[MAPS-006]** 需要获取从起点到终点的详细导航步骤 → 使用 `directions` 命令获取包含转向指令、距离和道路名称的分步列表 - **[MAPS-007]** 需要确定某坐标点所属时区及当前时间 → 使用 `timezone` 命令获取时区名称、UTC 偏移量及本地时间