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 펜실베이니아 애비뉴, 워싱턴 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 경로),
및 사용 가능 시 태그 — 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 "런던"
반환값: 경계 상자 좌표, 가로/세로 킬로미터, 대략적인 면적. 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 "자유의 여신상"
# 약 lat ~40.689, lon ~-74.044 반환
python3 ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "타임스퀘어" --category restaurant --limit 3
# 타임스퀘어 반경 ~500m 내 레스토랑 목록 반환