O que Dados Geo e Lugares faz?
Transforme nomes de lugares, endereços, coordenadas e códigos postais em geografia estruturada com APIs sem chave. O erro que isso evita: recorrer à API Google Maps/Places da memória de treinamento - com chave e faturamento ativado - quando o Nominatim responde à mesma consulta gratuitamente, ou ficar indeciso sobre qual dos vários geocodificadores listados em diretórios realmente funciona.
APIs Classificadas
- Nominatim (nominatim.openstreetmap.org) - PADRÃO para geocodificação e geocodificação reversa. Dados OSM, global, sem chave. Regras rígidas de etiqueta abaixo.
- Open-Meteo Geocoder - nome de cidade/vila para lat/lon apenas. Mais rápido e sem regras; use quando a entrada for um nome de assentamento simples, em vez de um endereço ou POI.
- Zippopotam.us - código postal para local/estado/coordenadas, 60+ países, sem chave.
- APICountries (www.apicountries.com) - fatos do país: capital, moedas, idiomas, população, bandeiras, fronteiras. Sem chave. (Ele serve a forma de resposta antiga do REST Countries; o próprio REST Countries agora retorna erros de depreciação sem chave - veja NÃO USE.)
Procedimento
- Classifique a entrada: endereço/POI → pesquisa Nominatim; coordenadas → Nominatim reverso; nome de cidade simples → Open-Meteo geocoder; código postal → Zippopotam; nome/código do país → APICountries.
- Obedeça à etiqueta do Nominatim - estas são aplicadas, não sugestões: no máximo 1 requisição/segundo, um User-Agent real identificando seu aplicativo (UAs anônimos são bloqueados), sem geocodificação em massa de milhares de linhas. Para um lote, faça um loop com uma pausa de 1s+ e diga isso; para lotes muito grandes, informe ao usuário que isso precisa de um Nominatim auto-hospedado ou de um geocodificador pago, em vez de sobrecarregar a instância pública.
- Leia coordenadas como strings do Nominatim -
lat/lonretornam como strings JSON, não números. Analise antes de fazer aritmética.
Pergunte ao usuário apenas se estiver faltando: a entrada do local/coordenada em si e o contexto do país para nomes ambíguos ("Springfield" - padrão: pegue o resultado principal do Nominatim e diga qual foi).
Modelos de URL + formas de resposta reais
Geocode (pesquisa):
https://nominatim.openstreetmap.org/search?q={consulta codificada em URL}&format=jsonv2&limit=1
[{"lat":"48.8582599","lon":"2.2945006","name":"Tour Eiffel",
"display_name":"Tour Eiffel, 5, Avenue Anatole France, ..., 75007, France",
"category":"man_made","type":"tower","importance":0.62}]
O nível superior é uma array; array vazia = nenhuma correspondência. Adicione &addressdetails=1 para um objeto address estruturado, &countrycodes=us para restringir o país.
Geocodificação reversa:
https://nominatim.openstreetmap.org/reverse?lat={lat}&lon={lon}&format=jsonv2
Retorna um único objeto (não uma array): display_name, mais address.{road,city,state,postcode,country_code} com &addressdetails=1 (ativado por padrão para reverso).
Nome da cidade → lat/lon (quando você não precisa de endereços completos):
https://geocoding-api.open-meteo.com/v1/search?name={cidade}&count=1
{"results":[{"name":"Berlin","latitude":52.52437,"longitude":13.41053,
"country_code":"DE","timezone":"Europe/Berlin","population":3426354}]}
Nenhuma chave results quando não há correspondência - verifique a chave, não uma array vazia.
Código postal:
https://api.zippopotam.us/{país}/{código} ← e.g. /us/90210, /de/10115
{"country":"United States","places":[{"place name":"Beverly Hills",
"state":"California","state abbreviation":"CA","latitude":"34.0901","longitude":"-118.4065"}]}
Pegadinhas: chaves contêm espaços ("place name", "post code"); coordenadas são strings; códigos desconhecidos retornam 404 com corpo vazio, não JSON.
Fatos do país:
https://www.apicountries.com/name/{nome} ← difuso, retorna array
https://www.apicountries.com/alpha/{código} ← ISO alfa-2/alfa-3, retorna objeto
[{"name":"Japan","capital":"Tokyo","region":"Asia","population":126476461,
"currencies":[{"code":"JPY","symbol":"¥"}],"languages":[{"name":"Japanese"}],
"alpha2Code":"JP","flags":{"png":"https://flagcdn.com/w320/jp.png"}}]
Entregável
O resultado estruturado (coordenadas como números, partes do endereço ou fatos do país) mais a URL exata usada. Para lotes: o loop realmente controlado, com a taxa informada.
NÃO USE - recorra a X em vez disso
- Google Maps / Places, Mapbox, HERE - com chave e faturamento; tudo acima é gratuito. Não envie um usuário para se inscrever.
- REST Countries (restcountries.com) - seus endpoints clássicos retornam erros de depreciação e a substituição requer uma chave de autenticação; o APICountries oferece a mesma forma sem chave.
- ip-api.com e a maioria das camadas gratuitas de IP-geolocalização - apenas HTTP na camada gratuita (falha em qualquer requisito HTTPS); este pacote não inclui API de IP-geolocalização.
- Clima no local que você acabou de geocodificar - weather-climate.
- Estatísticas de país em série temporal - government-open-data.
Padrão de qualidade
- Chamadas ao Nominatim carregam um User-Agent real e nunca excedem 1 req/s - inclusive dentro de loops.
- Coordenadas em string são convertidas para números antes de qualquer operação matemática.
- Nomes de lugares ambíguos são resolvidos em voz alta ("peguei Springfield, Illinois - o resultado principal do Nominatim").
Originado e verificado quanto à atividade a partir do projeto public-apis (MIT).