Skill de Mapas
Inteligência de localização usando fontes de dados abertas e gratuitas. 8 comandos, 44 categorias de POI, zero dependências (apenas stdlib do Python), sem necessidade de chave de API.
Fontes de dados: OpenStreetMap/Nominatim, Overpass API, OSRM, TimeAPI.io.
Este skill substitui o antigo skill find-nearby — toda a funcionalidade do find-nearby é coberta pelo comando nearby abaixo, com o mesmo atalho --near "<lugar>" e suporte a múltiplas categorias.
Quando Usar
- Usuário envia um pin de localização do Telegram (latitude/longitude na mensagem) →
nearby - Usuário quer coordenadas para um nome de lugar →
search - Usuário tem coordenadas e quer o endereço →
reverse - Usuário pergunta sobre restaurantes, hospitais, farmácias, hotéis, etc. próximos →
nearby - Usuário quer distância ou tempo de viagem a pé/de carro/bicicleta →
distance - Usuário quer direções passo a passo entre dois lugares →
directions - Usuário quer informações de fuso horário para uma localização →
timezone - Usuário quer pesquisar POIs dentro de uma área geográfica →
area+bbox
Pré-requisitos
Python 3.8+ (apenas stdlib — sem necessidade de pip install).
Caminho do script: ~/.hermes/skills/maps/scripts/maps_client.py
Comandos
MAPS=~/.hermes/skills/maps/scripts/maps_client.py
search — Geocodificar um nome de lugar
python3 $MAPS search "Torre Eiffel"
python3 $MAPS search "1600 Pennsylvania Ave, Washington DC"
Retorna: lat, lon, nome de exibição, tipo, caixa delimitadora, pontuação de importância.
reverse — Coordenadas para endereço
python3 $MAPS reverse 48.8584 2.2945
Retorna: detalhamento completo do endereço (rua, cidade, estado, país, CEP).
nearby — Encontrar lugares por categoria
# Por coordenadas (de um pin de localização do Telegram, por exemplo)
python3 $MAPS nearby 48.8584 2.2945 restaurante --limit 10
python3 $MAPS nearby 40.7128 -74.0060 hospital --radius 2000
# Por endereço / cidade / CEP / ponto de referência — --near faz auto-geocodificação
python3 $MAPS nearby --near "Times Square, Nova York" --category cafe
python3 $MAPS nearby --near "90210" --category farmacia
# Várias categorias mescladas em uma consulta
python3 $MAPS nearby --near "centro de austin" --category restaurante --category bar --limit 10
46 categorias: restaurante, cafe, bar, hospital, farmacia, hotel, guest_house, camp_site, supermercado, atm, gas_station, estacionamento, museu, parque, escola, universidade, banco, policia, corpo_de_bombeiros, biblioteca, aeroporto, estacao_de_trem, ponto_de_onibus, igreja, mesquita, sinagoga, dentista, medico, cinema, teatro, academia, piscina, correios, loja_de_conveniencia, padaria, livraria, lavanderia, lava_carros, aluguel_de_carros, aluguel_de_bicicletas, taxi, veterinario, zoologico, parquinho, estadio, boate.
Cada resultado inclui: nome, endereco, lat/lon, distance_m, maps_url (link clicável do Google Maps), directions_url (direções do Google Maps a partir do ponto de pesquisa) e tags promovidas quando disponíveis — cozinha, horario (horário de funcionamento), telefone, website.
distance — Distância e tempo de viagem
python3 $MAPS distance "Paris" --to "Lyon"
python3 $MAPS distance "Nova York" --to "Boston" --mode carro
python3 $MAPS distance "Big Ben" --to "Ponte da Torre" --mode caminhada
Modos: carro (padrão), caminhada, bicicleta. Retorna distância por estrada, duração e distância em linha reta para comparação.
directions — Navegação passo a passo
python3 $MAPS directions "Torre Eiffel" --to "Museu do Louvre" --mode caminhada
python3 $MAPS directions "Aeroporto JFK" --to "Times Square" --mode carro
Retorna etapas numeradas com instrução, distância, duração, nome da rua e tipo de manobra (virar, sair, chegar, etc.).
timezone — Fuso horário para coordenadas
python3 $MAPS timezone 48.8584 2.2945
python3 $MAPS timezone 35.6762 139.6503
Retorna nome do fuso horário, offset UTC e horário local atual.
area — Caixa delimitadora e área para um lugar
python3 $MAPS area "Manhattan, Nova York"
python3 $MAPS area "Londres"
Retorna coordenadas da caixa delimitadora, largura/altura em km e área aproximada. Útil como entrada para o comando bbox.
bbox — Pesquisar dentro de uma caixa delimitadora
python3 $MAPS bbox 40.75 -74.00 40.77 -73.98 restaurante --limit 20
Encontra POIs dentro de um retângulo geográfico. Use area primeiro para obter as coordenadas da caixa delimitadora para um lugar nomeado.
Trabalhando com Pins de Localização do Telegram
Quando um usuário envia um pin de localização, a mensagem contém os campos latitude: e longitude:. Extraia esses valores e passe-os diretamente para nearby:
# Usuário enviou um pin em 36.17, -115.14 e perguntou "encontre cafés perto"
python3 $MAPS nearby 36.17 -115.14 cafe --radius 1500
Apresente os resultados como uma lista numerada com nomes, distâncias e o campo maps_url para que o usuário receba um link clicável no chat. Para perguntas do tipo "está aberto agora?", verifique o campo horario; se estiver faltando ou pouco claro, confirme com web_search, pois os horários do OSM são mantidos pela comunidade e nem sempre estão atualizados.
Exemplos de Fluxo de Trabalho
"Encontre restaurantes italianos perto do Coliseu":
nearby --near "Coliseu Roma" --category restaurante --radius 500— um comando, auto-geocodificado
"O que tem perto deste pin de localização que enviaram?":
- Extraia lat/lon da mensagem do Telegram
nearby LAT LON cafe --radius 1500
"Como faço para andar do hotel até o centro de convenções?":
directions "Nome do Hotel" --to "Centro de Convenções" --mode caminhada
"Quais restaurantes existem no centro de Seattle?":
area "Centro de Seattle"→ obtenha a caixa delimitadorabbox S W N E restaurante --limit 30
Armadilhas
- Termos de Serviço do Nominatim: máximo 1 req/s (tratado automaticamente pelo script)
nearbyrequer lat/lon OU--near "<endereço>"— um dos dois é necessário- A cobertura de roteamento do OSRM é melhor para a Europa e América do Norte
- A Overpass API pode ser lenta em horários de pico; o script alterna automaticamente entre mirrors (overpass-api.de → overpass.kumi.systems)
distanceedirectionsusam a flag--topara o destino (não posicional)- Se um CEP isolado der resultados ambíguos globalmente, inclua país/estado
Verificação
python3 ~/.hermes/skills/maps/scripts/maps_client.py search "Estátua da Liberdade"
# Deve retornar lat ~40.689, lon ~-74.044
python3 ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "Times Square" --category restaurante --limit 3
# Deve retornar uma lista de restaurantes dentro de ~500m da Times Square