Maps Skill は何をしますか？
フリーでオープンなデータソースを利用した位置情報インテリジェンス。8つのコマンド、44のPOIカテゴリ、依存関係ゼロ（Python標準ライブラリのみ）、APIキー不要。
データソース：OpenStreetMap/Nominatim、Overpass API、OSRM、TimeAPI.io。
このスキルは旧find-nearbyスキルを置き換えます — find-nearbyの全機能は以下のnearbyコマンドに含まれており、同じ--near "<場所>"ショートカットとマルチカテゴリ対応を備えています。
使用するタイミング
- ユーザーがTelegramのロケーションピンを送信した（メッセージに緯度/経度が含まれる）場合→
nearby - ユーザーが場所名の座標を欲しがっている場合→
search - ユーザーが座標を持っていて住所を欲しがっている場合→
reverse - ユーザーが近くのレストラン、病院、薬局、ホテルなどを尋ねた場合→
nearby - ユーザーが運転/徒歩/自転車での距離や所要時間を尋ねた場合→
distance - ユーザーが2地点間の詳細な道順を尋ねた場合→
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 — 場所名をジオコーディング
python3 $MAPS search "Eiffel Tower"
python3 $MAPS search "1600 Pennsylvania Ave, Washington DC"
戻り値：緯度、経度、表示名、タイプ、バウンディングボックス、重要度スコア。
reverse — 座標から住所へ
python3 $MAPS reverse 48.8584 2.2945
戻り値：完全な住所分解（番地、市区町村、州、国、郵便番号）。
nearby — カテゴリで施設を検索
# 座標による検索（例：Telegramのロケーションピンから）
python3 $MAPS nearby 48.8584 2.2945 restaurant --limit 10
python3 $MAPS nearby 40.7128 -74.0060 hospital --radius 2000
# 住所/市区町村/郵便番号/ランドマークによる検索 — --near で自動ジオコーディング
python3 $MAPS nearby --near "Times Square, New York" --category cafe
python3 $MAPS nearby --near "90210" --category pharmacy
# 複数カテゴリを一つのクエリに統合
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 — 移動距離と時間
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 — ターンバイターン案内
python3 $MAPS directions "Eiffel Tower" --to "Louvre Museum" --mode walking
python3 $MAPS directions "JFK Airport" --to "Times Square" --mode driving
番号付きのステップを返します。各ステップには指示、距離、所要時間、道路名、操作タイプ（turn、depart、arrive など）が含まれます。
timezone — 座標からタイムゾーン
python3 $MAPS timezone 48.8584 2.2945
python3 $MAPS timezone 35.6762 139.6503
戻り値：タイムゾーン名、UTCオフセット、現在の現地時間。
area — 場所のバウンディングボックスと面積
python3 $MAPS area "Manhattan, New York"
python3 $MAPS area "London"
戻り値：バウンディングボックス座標、幅/高さ（km）、おおよその面積。bboxコマンドの入力として有用。
bbox — バウンディングボックス内を検索
python3 $MAPS bbox 40.75 -74.00 40.77 -73.98 restaurant --limit 20
地理的な矩形内のPOIを検索します。名前付きの場所のバウンディングボックス座標を得るには、最初にareaを使用してください。
Telegramのロケーションピンの扱い方
ユーザーがロケーションピンを送信すると、メッセージにはlatitude:とlongitude:フィールドが含まれます。それらを抽出して、そのままnearbyに渡します。
# ユーザーが位置(36.17, -115.14)のピンを送信し、「近くのカフェを探して」と尋ねた場合
python3 $MAPS nearby 36.17 -115.14 cafe --radius 1500
結果は番号付きリストで、名前、距離、maps_urlフィールドを提示してください。これによりユーザーはチャット内でタップして開くリンクを得られます。「今開いてる？」という質問に対しては、hoursフィールドを確認してください。欠落しているか不明瞭な場合は、OSMの営業時間はコミュニティメンテナンスであり常に最新とは限らないため、web_searchで確認してください。
ワークフロー例
「コロッセオの近くのイタリアンレストランを探して」
nearby --near "Colosseum Rome" --category restaurant --radius 500— 1コマンド、自動ジオコーディング
「この送られてきたロケーションピンの近くは？」
- 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
注意点
- Nominatimの利用規約：最大1 req/s（スクリプトが自動的に処理）
nearbyには緯度/経度 または--near "<住所>"のいずれかが必要 — どちらか一方が必要- OSRMのルーティングカバレッジはヨーロッパと北アメリカで最も良好
- Overpass APIはピーク時に遅くなることがあります。スクリプトは自動的にミラー間でフォールバックします（overpass-api.de → overpass.kumi.systems）
distanceとdirectionsは目的地に--toフラグを使用します（位置引数ではありません）- 郵便番号だけで世界的にあいまいな結果になる場合は、国/州を含めてください
検証
python3 ~/.hermes/skills/maps/scripts/maps_client.py search "Statue of Liberty"
# 緯度~40.689、経度~-74.044を返すはず
python3 ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "Times Square" --category restaurant --limit 3
# Times Squareから約500m以内のレストランリストを返すはず