Documentação

Tudo é uma requisição GET para https://api.mygeocode.com/v1/ com parâmetros de consulta, respondida em JSON. Esta página cobre as partes que todos os endpoints compartilham. As páginas de cada endpoint cobrem os parâmetros e campos de cada um.

Sua primeira requisição

Nenhuma chave é necessária para as primeiras 2.500 requisições por dia a partir de um endereço. De qualquer máquina:

$ curl "https://api.mygeocode.com/v1/forward?q=Brandenburg+Gate,+Berlin&limit=1"

{
  "status": "ok",
  "query": "Brandenburg Gate, Berlin",
  "results": [
    {
      "formatted": "Brandenburger Tor, Pariser Platz, 10117 Berlin, Germany",
      "lat": 52.516275,
      "lon": 13.377704,
      "type": "poi",
      "precision": "house",
      "confidence": 0.99,
      "components": {
        "name": "Brandenburger Tor",
        "road": "Pariser Platz",
        "suburb": "Mitte",
        "city": "Berlin",
        "state": "Berlin",
        "postcode": "10117",
        "country": "Germany",
        "country_code": "de"
      },
      "bounds": { "north": 52.516441, "south": 52.516107, "east": 13.377862, "west": 13.377538 }
    }
  ]
}

Essa requisição contou como 1 das 2.500 requisições gratuitas que o seu endereço tem hoje. Com uma chave, ela seria contada na chave, e os cabeçalhos incluiriam os números do seu crédito e das suas vagas de IP. Os cabeçalhos da resposta mostram a sua situação:

HTTP/2 200
content-type: application/json; charset=utf-8
x-quota-limit: 2500
x-quota-used: 1
x-quota-free-remaining: 2499
x-quota-reset: 1756339200
x-request-id: 2726386e38428697

Vindo de outro provedor?

Talvez você não precise do resto desta página. Se o seu código já se comunica com Google Maps, Bing Maps, HERE, Mapbox, Geocode.Farm, Nominatim, OpenCage, LocationIQ, Geoapify, TomTom, MapQuest, Geocodio, PositionStack, ip-api, ipinfo, ipstack ou Open-Elevation, nós mantemos um host que fala o formato de requisição e resposta desse provedor, com os nossos dados por trás. Troque o nome do host, coloque a sua chave onde ficava a antiga e mantenha o seu código de parsing. O mesmo vale para a Google Maps JavaScript API, o Bing Maps V8, o HERE Maps for JavaScript, o MapQuest.js e os plugins de geocodificação do MapLibre, Mapbox GL e Leaflet.

• Google Maps
• Bing Maps
• HERE
• Mapbox
• Geocode.Farm
• Nominatim
• OpenCage
• LocationIQ
• Geoapify
• TomTom
• MapQuest
• Geocodio
• PositionStack
• ip-api
• ipinfo
• ipstack
• Open-Elevation
• Bibliotecas de mapas JavaScript

Como funcionam os hosts compatíveis (drop-in): a matriz completa de hosts, o mapeamento de chaves, o mapeamento de erros e um checklist de migração.

URL base e endpoints

Somente HTTPS é atendido. Requisições em HTTP simples são recusadas com 400 em vez de redirecionadas, para que uma chave nunca seja enviada sem criptografia por acidente. HTTP/2 e HTTP/3 são suportados. As respostas são comprimidas quando o cliente aceita gzip ou br.

O envelope da resposta

Toda resposta é um objeto JSON com um status igual a ok ou error.

• Com ok, segue o conteúdo: results (um array) para endpoints que podem retornar várias correspondências, result (um objeto ou null) para geocodificação reversa, e campos planos para consultas de IP e fuso horário.
• Com error, há um objeto error com uma string code, uma frase message e, quando relevante, o param que causou o erro. O status HTTP corresponde. Consulte erros.

Uma consulta válida que não encontra nada retorna ok com um array results vazio ou um result null. Isso não é um erro, e conta como uma requisição.

Parâmetros aceitos por todos os endpoints

Os nomes de parâmetros diferenciam maiúsculas de minúsculas e são em minúsculas. Parâmetros desconhecidos são ignorados, e parâmetros vazios são tratados como ausentes, então um formulário HTML pode enviar campos opcionais em branco. As coordenadas são em graus decimais; lat de -90 a 90 e lon de -180 a 180. O texto é UTF-8 e deve ser codificado para URL.

Autenticação em um parágrafo

A chave é opcional: todo endereço tem 2.500 requisições gratuitas por dia sem uma. A chave é enviada no cabeçalho X-API-Key, como token Authorization: Bearer ou no parâmetro key; as chaves são gratuitas, e uma conta pede o seu nome, um endereço de e-mail e uma senha. Cada chave tem 2.500 requisições gratuitas por dia só dela; além disso, as requisições usam o crédito pré-pago da conta a € 0,0001 cada, ou são gratuitas numa chave que pertence a um pacote Unlimited (€ 50 por mês). Requisições sem chave e requisições com chave da mesma rede compartilham uma única cota diária. Uma chave de pagamento por uso funciona a partir de dois endereços IP a cada 24 horas móveis, uma chave Unlimited a partir de três. As regras completas estão na página de autenticação.

Cabeçalhos de cota

Chamadas a partir do navegador

O CORS está ativado em todos os endpoints e os cabeçalhos de cota são expostos, mas uma chave no código-fonte da página é pública e esgotaria as suas vagas de IP depois de alguns visitantes. Faça as chamadas a partir do seu servidor; veja chaves e navegadores.

Versionamento

O prefixo de caminho /v1/ é a versão. Dentro de uma versão, adicionamos campos e parâmetros, mas nunca os removemos nem renomeamos, e nunca mudamos o significado de um campo existente. Se algum dia precisarmos quebrar algo, isso vai para /v2/, e /v1/ continua funcionando por pelo menos seis meses após o anúncio. As novidades são anunciadas na seção Notícias do blog.

O seu parser JSON deve ignorar os campos que não conhece. Esse é o único requisito de compatibilidade futura.