maps

地图技能

使用免费的开放数据源提供位置智能功能。包含 8 个命令、44 个 POI 类别、零依赖（仅使用 Python 标准库），无需 API 密钥。

数据源：OpenStreetMap/Nominatim、Overpass API、OSRM、TimeAPI.io。

此技能取代旧版 find-nearby 技能——find-nearby 的所有功能均由下方的 nearby 命令覆盖，并保留相同的 --near "<place>" 快捷方式和多类别支持。

适用场景

• 用户发送 Telegram 位置图钉（消息中包含纬度/经度）→ nearby
• 用户想查询某个地点名称对应的坐标 → search
• 用户有坐标，想查询对应地址 → reverse
• 用户询问附近的餐厅、医院、药店、酒店等 → nearby
• 用户想查询驾车/步行/骑行距离或行程时间 → distance
• 用户想查询两地之间的逐向导航路线 → directions
• 用户想查询某个地点的时区信息 → timezone
• 用户想搜索某个地理区域内的 POI → area + bbox

前提条件

Python 3.8+（仅使用标准库，无需通过 pip 安装）。

脚本路径：~/.hermes/skills/maps/scripts/maps_client.py

命令

MAPS=~/.hermes/skills/maps/scripts/maps_client.py

search — 地点名称地理编码

python $MAPS search "Eiffel Tower"
python $MAPS search "1600 Pennsylvania Ave, Washington DC"

返回：纬度、经度、显示名称、类型、边界框、重要性评分。

reverse — 根据坐标查询地址

python $MAPS reverse 48.8584 2.2945

返回：完整地址信息（街道、城市、州/省、国家、邮政编码）。

nearby — 按类别查找地点

# By coordinates (from a Telegram location pin, for example)
python $MAPS nearby 48.8584 2.2945 restaurant --limit 10
python $MAPS nearby 40.7128 -74.0060 hospital --radius 2000

# By address / city / zip / landmark — --near auto-geocodes
python $MAPS nearby --near "Times Square, New York" --category cafe
python $MAPS nearby --near "90210" --category pharmacy

# Multiple categories merged into one query
python $MAPS nearby --near "downtown austin" --category restaurant --category bar --limit 10

46 个类别：餐厅、咖啡馆、酒吧、医院、药店、酒店、宾馆、 露营地、超市、ATM、加油站、停车场、博物馆、公园、学校、 大学、银行、警察局、消防站、图书馆、机场、火车站、 公交车站、教堂、清真寺、犹太教堂、牙医、医生、电影院、剧院、健身房、 游泳池、邮局、便利店、面包店、书店、洗衣店、 洗车店、汽车租赁、自行车租赁、出租车、兽医、动物园、游乐场、 体育场、夜总会。

每条结果包含：name、address、lat/lon、distance_m、 maps_url（可点击的 Google Maps 链接）、directions_url（从搜索点出发的 Google Maps 路线），以及可用时提升显示的标签—— cuisine、hours（opening_hours）、phone、website。

distance — 行程距离与时间

python $MAPS distance "Paris" --to "Lyon"
python $MAPS distance "New York" --to "Boston" --mode driving
python $MAPS distance "Big Ben" --to "Tower Bridge" --mode walking

模式：驾车（默认）、步行、骑行。返回道路距离、行程时间 和直线距离，供比较参考。

directions — 逐向导航

python $MAPS directions "Eiffel Tower" --to "Louvre Museum" --mode walking
python $MAPS directions "JFK Airport" --to "Times Square" --mode driving

返回编号步骤，包含指示、距离、行程时间、道路名称和 操作类型（转弯、出发、抵达等）。

timezone — 查询坐标对应的时区

python $MAPS timezone 48.8584 2.2945
python $MAPS timezone 35.6762 139.6503

返回时区名称、UTC 偏移量和当地当前时间。

area — 查询地点的边界框和面积

python $MAPS area "Manhattan, New York"
python $MAPS area "London"

返回边界框坐标、宽度/高度（公里）和大致面积。 可用于为 bbox 命令提供输入。

bbox — 在边界框内搜索

python $MAPS bbox 40.75 -74.00 40.77 -73.98 restaurant --limit 20

查找地理矩形范围内的 POI。先使用 area 获取指定地点的 边界框坐标。

使用 Telegram 位置图钉

用户发送位置图钉时，消息中会包含 latitude: 和 longitude: 字段。提取这两个字段，并直接传给 nearby：

# User sent a pin at 36.17, -115.14 and asked "find cafes nearby"
python $MAPS nearby 36.17 -115.14 cafe --radius 1500

将结果整理为编号列表，列出名称、距离和 maps_url 字段，方便用户在聊天中点击链接打开地图。对于“现在 营业吗？”之类的问题，请检查 hours 字段；如果缺失或不明确，请通过 web_search 核实，因为 OSM 营业时间由社区维护，不一定 是最新信息。

工作流示例

“查找罗马斗兽场附近的意大利餐厅”：

1. nearby --near "Colosseum Rome" --category restaurant --radius 500 — 一条命令，自动进行地理编码

“他们发来的这个位置图钉附近有什么？”：

1. 从 Telegram 消息中提取纬度/经度
2. nearby LAT LON cafe --radius 1500

“从酒店到会议中心怎么走？”：

1. directions "Hotel Name" --to "Conference Center" --mode walking

“西雅图市中心有哪些餐厅？”：

1. area "Downtown Seattle" → 获取边界框
2. bbox S W N E restaurant --limit 30

注意事项

• Nominatim 服务条款：每秒最多 1 个请求（脚本会自动处理）
• nearby 需要纬度/经度或 --near "<address>"，二者任选其一
• OSRM 的路线规划覆盖范围以欧洲和北美为佳
• 高峰时段 Overpass API 可能响应较慢；脚本会自动在镜像之间切换（overpass-api.de → overpass.kumi.systems）
• distance 和 directions 使用 --to 标志指定目的地（而非位置参数）
• 如果单独使用邮政编码在全球范围内会产生歧义，请附上国家/州信息

验证

python ~/.hermes/skills/maps/scripts/maps_client.py search "Statue of Liberty"
# Should return lat ~40.689, lon ~-74.044

python ~/.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