maps

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Maps Skill

地图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 "<place>"

shortcut and multi-category support.

基于免费开源数据源的位置智能工具。包含8个命令、44种POI分类，零依赖（仅需Python标准库），无需API密钥。

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

本Skill替代了旧的

find-nearby

Skill——

find-nearby

的所有功能都被下方的

nearby

命令覆盖，支持相同的

--near "<地点>"

快捷方式和多分类查询。

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
```

用户发送Telegram定位标记（消息中包含纬度/经度）→ 使用
```
nearby
```
命令
用户需要某个地点名称的坐标→ 使用
```
search
```
命令
用户已有坐标并需要对应的地址→ 使用
```
reverse
```
命令
用户查询附近的餐厅、医院、药店、酒店等→ 使用
```
nearby
```
命令
用户需要驾车/步行/骑行的距离或耗时→ 使用
```
distance
```
命令
用户需要两地之间的逐向导航路线→ 使用
```
directions
```
命令
用户需要某个地点的时区信息→ 使用
```
timezone
```
命令
用户需要在指定地理区域内搜索POI→ 结合使用
```
area
```
与
```
bbox
```
命令

Prerequisites

前置条件

Python 3.8+ (stdlib only — no pip installs needed).

Script path:

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

Python 3.8+（仅需标准库——无需通过pip安装额外依赖）。

脚本路径：

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

Commands

命令

bash

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

bash

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

search — Geocode a place name

search — 地点名称地理编码

bash

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

Returns: lat, lon, display name, type, bounding box, importance score.

bash

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

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

reverse — Coordinates to address

reverse — 坐标转地址

bash

python3 $MAPS reverse 48.8584 2.2945

Returns: full address breakdown (street, city, state, country, postcode).

bash

python3 $MAPS reverse 48.8584 2.2945

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

nearby — Find places by category

nearby — 按分类查找地点

bash

undefined

bash

undefined

By coordinates (from a Telegram location pin, for example)

通过坐标（例如来自Telegram定位标记）

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

通过地址/城市/邮政编码/地标——--near参数自动进行地理编码

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`.

python3 $MAPS nearby --near "downtown austin" --category restaurant --category bar --limit 10


支持46种分类：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。

每个结果包含：`name`（名称）、`address`（地址）、`lat`/`lon`（纬度/经度）、`distance_m`（距离，单位米）、`maps_url`（可点击的Google Maps链接）、`directions_url`（从搜索点出发的Google Maps导航链接），以及可用的附加信息标签——`cuisine`（菜系）、`hours`（营业时间）、`phone`（电话）、`website`（官网）。

distance — Travel distance and time

distance — 出行距离与时间

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.

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

支持模式：driving（驾车，默认）、walking（步行）、cycling（骑行）。返回道路距离、耗时，以及用于对比的直线距离。

directions — Turn-by-turn navigation

directions — 逐向导航

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.).

bash

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

返回带编号的步骤，包含导航指令、距离、耗时、道路名称以及操作类型（转弯、出发、到达等）。

timezone — Timezone for coordinates

timezone — 坐标对应的时区

bash

python3 $MAPS timezone 48.8584 2.2945
python3 $MAPS timezone 35.6762 139.6503

Returns timezone name, UTC offset, and current local time.

bash

python3 $MAPS timezone 48.8584 2.2945
python3 $MAPS timezone 35.6762 139.6503

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

area — Bounding box and area for a place

area — 地点的边界框与区域范围

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.

bash

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

返回边界框坐标、宽度/高度（单位千米）以及近似区域面积。该命令的结果可作为bbox命令的输入。

bbox — Search within a bounding box

bbox — 在边界框内搜索

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.

bash

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

查找指定地理矩形范围内的POI。可先使用

area

命令获取指定地点的边界框坐标。

Working With Telegram Location Pins

与Telegram定位标记配合使用

When a user sends a location pin, the message contains

latitude:

and

longitude:

fields. Extract those and pass them straight to

nearby

bash

undefined

当用户发送定位标记时，消息中包含

latitude:

（纬度）和

longitude:

（经度）字段。提取这些坐标并直接传入

nearby

命令：

bash

undefined

User sent a pin at 36.17, -115.14 and asked "find cafes nearby"

用户发送了坐标为36.17, -115.14的定位标记，并询问"附近的咖啡馆"

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.

python3 $MAPS nearby 36.17 -115.14 cafe --radius 1500


将结果以编号列表形式展示，包含名称、距离以及`maps_url`字段，方便用户在聊天中点击打开链接。对于“是否营业？”这类问题，可查看`hours`字段；若该字段缺失或信息不明确，建议通过`web_search`验证，因为OSRM的营业时间由社区维护，并非始终最新。

Workflow Examples

工作流示例

"Find Italian restaurants near the Colosseum":

nearby --near "Colosseum Rome" --category restaurant --radius 500

— one command, auto-geocoded

"What's near this location pin they sent?":

Extract lat/lon from the Telegram message
```
nearby LAT LON cafe --radius 1500
```

"How do I walk from hotel to conference center?":

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

"What restaurants are in downtown Seattle?":

```
area "Downtown Seattle"
```
→ get bounding box
```
bbox S W N E restaurant --limit 30
```

"查找罗马斗兽场附近的意大利餐厅":

执行

nearby --near "Colosseum Rome" --category restaurant --radius 500

——一键完成，自动地理编码

"用户发送的定位标记附近有什么？":

从Telegram消息中提取纬度/经度
执行
```
nearby LAT LON cafe --radius 1500
```

"如何从酒店步行到会议中心？":

执行

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

"西雅图市中心有哪些餐厅？":

执行
```
area "Downtown Seattle"
```
→ 获取边界框坐标
执行
```
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 "<address>"
```
— 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

Nominatim服务条款：最大请求频率为1次/秒（脚本已自动处理）
```
nearby
```
命令需要纬度/经度或
```
--near "<地址>"
```
参数——二者必须提供其一
OSRM路线规划在欧洲和北美地区覆盖最完善
Overpass API在高峰时段可能较慢；脚本会自动在镜像站点间切换（overpass-api.de → overpass.kumi.systems）
```
distance
```
和
```
directions
```
命令使用
```
--to
```
参数指定目的地（而非位置参数）
如果单独使用邮政编码导致全球范围内结果模糊，请补充国家/州信息

Verification

验证方法

bash

python3 ~/.hermes/skills/maps/scripts/maps_client.py search "Statue of Liberty"

bash

python3 ~/.hermes/skills/maps/scripts/maps_client.py search "Statue of Liberty"

Should return lat ~40.689, lon ~-74.044

应返回纬度约40.689，经度约-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

应返回时代广场周边约500米范围内的餐厅列表

undefined

undefined