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 - 사용자가 두 장소 간 경로 안내를 원하는 경우 →
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 "에펠탑"
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 "타임스퀘어, 뉴욕" --category cafe
python3 $MAPS nearby --near "90210" --category pharmacy
# 여러 카테고리를 하나의 쿼리로 병합
python3 $MAPS nearby --near "오스틴 시내" --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 경로), 그리고 가능한 경우 promoted 태그 — cuisine, hours
(영업 시간), phone, website가 포함됩니다.
distance — 이동 거리 및 시간
python3 $MAPS distance "파리" --to "리옹"
python3 $MAPS distance "뉴욕" --to "보스턴" --mode driving
python3 $MAPS distance "빅벤" --to "타워브릿지" --mode walking
모드: driving(기본값), walking, cycling. 도로 거리, 소요 시간, 비교용 직선 거리를 반환합니다.
directions — 경로 안내
python3 $MAPS directions "에펠탑" --to "루브르 박물관" --mode walking
python3 $MAPS directions "JFK 공항" --to "타임스퀘어" --mode driving
안내, 거리, 소요 시간, 도로명, 기동 유형(회전, 출발, 도착 등)이 포함된 번호별 단계를 반환합니다.
timezone — 좌표의 시간대
python3 $MAPS timezone 48.8584 2.2945
python3 $MAPS timezone 35.6762 139.6503
시간대 이름, UTC 오프셋, 현재 현지 시간을 반환합니다.
area — 장소의 경계 상자 및 영역
python3 $MAPS area "맨해튼, 뉴욕"
python3 $MAPS area "런던"
경계 상자 좌표, 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 필드를 확인하세요. 만약 누락되었거나
불명확하면 web_search로 확인하세요. OSM 영업 시간은 커뮤니티가 유지 관리하며
항상 최신이 아닐 수 있습니다.
워크플로 예시
"콜로세움 근처 이탈리안 레스토랑 찾아줘":
nearby --near "콜로세움 로마" --category restaurant --radius 500— 명령어 하나로 자동 지오코딩
"보낸 위치 핀 근처에 뭐가 있지?":
- Telegram 메시지에서 위도/경도 추출
nearby LAT LON cafe --radius 1500
"호텔에서 컨퍼런스 센터까지 걸어서 어떻게 가나요?":
directions "호텔 이름" --to "컨퍼런스 센터" --mode walking
"시애틀 시내에 어떤 레스토랑이 있나요?":
area "시애틀 시내"→ 경계 상자 얻기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 "자유의 여신상"
# 위도 ~40.689, 경도 ~-74.044 반환 예상
python3 ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "타임스퀘어" --category restaurant --limit 3
# 타임스퀘어 약 500m 이내 레스토랑 목록 반환 예상