maps

Maps Skill

無料のオープンデータソースを利用した位置情報インテリジェンスです。コマンドは8種類、POI カテゴリは44種類で、依存関係はなく（Python 標準ライブラリのみ）、API キーも不要です。

データソース：OpenStreetMap/Nominatim、Overpass API、OSRM、TimeAPI.io。

このスキルは従来の find-nearby スキルに代わるものです。以下の nearby コマンドで find-nearby のすべての機能を利用でき、同じ --near "<place>" ショートカットと複数カテゴリのサポートも含まれます。

使用する場面

• ユーザーが 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 — 地名をジオコーディング

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"

バウンディングボックスの座標、幅／高さ（km）、およその面積が返されます。 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 フィールドを確認してください。情報がない、または不明確な場合は、OSM の営業時間情報はコミュニティが管理しており、最新でない場合もあるため、web_search で確認してください。

ワークフローの例

「コロッセオの近くにあるイタリア料理店を探す」：

1. nearby --near "Colosseum Rome" --category restaurant --radius 500 — 1 つのコマンドで自動的にジオコーディングされます

「送られてきた位置情報ピンの近くには何がありますか？」：

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