Geocodificação, consulta de IP e de fuso horário em uma única API HTTP simples

Transforme endereços em coordenadas e vice-versa, descubra onde fica um endereço IPv4 ou IPv6, obtenha o fuso horário ou a altitude de qualquer ponto e consulte códigos postais. Envie uma requisição GET e leia o JSON. Nada para instalar.

2.500 requisições gratuitas por dia a partir de qualquer endereço, sem chave e sem conta. Precisa de mais? Cadastre-se com seu nome e e-mail, adicione crédito pré-pago a € 0,0001 por requisição ou adquira uma chave Unlimited por € 50 ao mês. Aceitamos cartões e criptomoedas.

$ curl -H "X-API-Key: YOUR_KEY" "https://api.mygeocode.com/v1/reverse?lat=48.8584&lon=2.2945"
{
  "status": "ok",
  "result": {
    "formatted": "5 Avenue Anatole France, 75007 Paris, France",
    "lat": 48.85837,
    "lon": 2.29448,
    "distance_m": 12,
    "precision": "house",
    "components": {
      "house_number": "5",
      "road": "Avenue Anatole France",
      "city": "Paris",
      "postcode": "75007",
      "country": "France",
      "country_code": "fr"
    }
  }
}
2.500requisições gratuitas por dia, em cada chave
€ 0,0001por requisição em crédito pré-pago
€ 50por mês por uma chave Unlimited
17hosts compatíveis (drop-in) para APIs de outros provedores
Endpoints

Oito consultas, uma URL base

Todos os endpoints ficam em https://api.mygeocode.com/v1/, recebem parâmetros de consulta e retornam JSON com o mesmo envelope. Aprenda um e você conhecerá todos.

API de geocodificação direta

GET /v1/forward

Envie um endereço, um nome de lugar ou uma descrição aproximada e receba coordenadas, um endereço padronizado e cada uma de suas partes.

Detalhes e exemplos

API de geocodificação reversa

GET /v1/reverse

Envie uma latitude e uma longitude e receba o endereço mais próximo, com cidade, região, código postal e país separados.

Detalhes e exemplos

API de preenchimento automático de endereços

GET /v1/autocomplete

Sugira endereços enquanto alguém digita. Cada sugestão vem com coordenadas, então raramente você precisa de uma segunda chamada.

Detalhes e exemplos

API de consulta de IPv4

GET /v1/ipv4

País, região, cidade, coordenadas, fuso horário e proprietário da rede de qualquer endereço IPv4, ou de quem faz a chamada se você omiti-lo.

Detalhes e exemplos

API de consulta de IPv6

GET /v1/ipv6

Os mesmos detalhes para endereços IPv6, além do prefixo anunciado ao qual o endereço pertence.

Detalhes e exemplos

API de consulta de fuso horário

GET /v1/timezone

Nome do fuso horário IANA, deslocamento em relação ao UTC, status do horário de verão e hora local de qualquer coordenada, agora ou em um timestamp que você escolher.

Detalhes e exemplos

API de consulta de altitude

GET /v1/elevation

Altitude acima do nível do mar em metros para um ponto, ou para até 100 pontos em uma única chamada.

Detalhes e exemplos

API de consulta de código postal

GET /v1/postcode

Transforme um código postal em nome de lugar, região e coordenadas. Funciona com CEPs, ZIP codes, postcodes e seus equivalentes na maioria dos países.

Detalhes e exemplos
Precisão

Cada resultado informa sua precisão

Um geocodificador que retorna o centro da cidade quando você pediu um número de casa é pior do que um que diz que não encontrou a casa. Cada resultado que retornamos traz um campo precision com um de quatro valores, para que seu código decida o que fazer com uma correspondência aproximada em vez de adivinhar.

A cobertura não é igual em todos os lugares, e preferimos mostrar isso a fazer uma afirmação genérica. A página de cobertura lista o melhor nível que alcançamos em cada um dos 249 países e territórios.

Veja o nível de cada país

NívelO que o ponto representa
houseO próprio edifício ou lote. O ponto fica sobre o imóvel.
streetUma posição ao longo da rua, interpolada a partir da faixa de numeração daquele quarteirão.
postcodeO centro da área do código postal.
adminO centro da cidade, do bairro, da região ou do país, o que for a correspondência mais específica que conseguimos fazer.
Migração

Já usa a API de outro provedor? Troque o nome do host.

Mantemos hosts compatíveis (drop-in) que aceitam os mesmos caminhos e parâmetros do Google Maps, Bing Maps, HERE, Mapbox, Geocode.Farm, Nominatim e outros onze, e respondem no formato de resposta deles com os nossos dados. Seu código de parsing não muda. Coloque sua chave do My Geocode onde estava a chave antiga.

Antes
$ curl "https://maps.googleapis.com/maps/api/geocode/json?address=10+Downing+St+London&key=GOOGLE_KEY"
Depois
$ curl "https://gapi.mygeocode.com/maps/api/geocode/json?address=10+Downing+St+London&key=MYGEOCODE_KEY"

A mesma ideia funciona para bibliotecas JavaScript. Carregue a Google Maps JavaScript API a partir de gapi.mygeocode.com e google.maps.Map, Geocoder e o Autocomplete do Places continuam funcionando, com carregamentos de mapa que não custam nada. Há carregadores para o controle Bing Maps V8, o HERE Maps for JavaScript e o MapQuest.js, e configurações para os plugins de geocodificação do MapLibre, do Mapbox GL e do Leaflet.

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

Hosts compatíveis REST Substitutos compatíveis para JavaScript

Qualquer linguagem

Se consegue enviar uma requisição HTTP, consegue usar isto

Nenhum SDK é necessário. Estes exemplos geocodificam um endereço e exibem suas coordenadas. Bibliotecas oficiais para cada linguagem estão a caminho e continuarão sendo camadas finas sobre essas mesmas chamadas.

$ curl -H "X-API-Key: YOUR_KEY" "https://api.mygeocode.com/v1/forward?q=221B+Baker+Street,+London"

$ curl -H "X-API-Key: YOUR_KEY" "https://api.mygeocode.com/v1/forward?q=221B+Baker+Street,+London"
const url = new URL("https://api.mygeocode.com/v1/forward");
url.searchParams.set("q", "221B Baker Street, London");

const res = await fetch(url, { headers: { "X-API-Key": process.env.MYGEOCODE_KEY } });
const data = await res.json();

const [first] = data.results;
console.log(first.lat, first.lon, first.precision);
import os
import requests

r = requests.get(
    "https://api.mygeocode.com/v1/forward",
    params={"q": "221B Baker Street, London"},
    headers={"X-API-Key": os.environ["MYGEOCODE_KEY"]},
    timeout=10,
)
r.raise_for_status()
first = r.json()["results"][0]
print(first["lat"], first["lon"], first["precision"])
<?php
$url = "https://api.mygeocode.com/v1/forward?" . http_build_query([
    "q" => "221B Baker Street, London",
]);

$context = stream_context_create(["http" => ["header" => "X-API-Key: " . getenv("MYGEOCODE_KEY")]]);
$data = json_decode(file_get_contents($url, false, $context), true);

$first = $data["results"][0];
echo $first["lat"], ", ", $first["lon"], " (", $first["precision"], ")\n";
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"os"
)

func main() {
	q := url.Values{"q": {"221B Baker Street, London"}}
	req, _ := http.NewRequest("GET", "https://api.mygeocode.com/v1/forward?"+q.Encode(), nil)
	req.Header.Set("X-API-Key", os.Getenv("MYGEOCODE_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var data struct {
		Results []struct {
			Lat       float64 `json:"lat"`
			Lon       float64 `json:"lon"`
			Precision string  `json:"precision"`
		} `json:"results"`
	}
	json.NewDecoder(resp.Body).Decode(&data)
	fmt.Println(data.Results[0].Lat, data.Results[0].Lon, data.Results[0].Precision)
}
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

public class Geocode {
    public static void main(String[] args) throws Exception {
        String q = URLEncoder.encode("221B Baker Street, London", StandardCharsets.UTF_8);
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.mygeocode.com/v1/forward?q=" + q))
            .header("X-API-Key", System.getenv("MYGEOCODE_KEY"))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
using System.Net.Http;
using System.Text.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", Environment.GetEnvironmentVariable("MYGEOCODE_KEY"));

var q = Uri.EscapeDataString("221B Baker Street, London");
var json = await client.GetStringAsync($"https://api.mygeocode.com/v1/forward?q={q}");

using var doc = JsonDocument.Parse(json);
var first = doc.RootElement.GetProperty("results")[0];
Console.WriteLine($"{first.GetProperty("lat")}, {first.GetProperty("lon")} ({first.GetProperty("precision")})");
require "net/http"
require "json"

uri = URI("https://api.mygeocode.com/v1/forward")
uri.query = URI.encode_www_form(q: "221B Baker Street, London")

req = Net::HTTP::Get.new(uri)
req["X-API-Key"] = ENV["MYGEOCODE_KEY"]
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }

first = JSON.parse(res.body)["results"][0]
puts "#{first["lat"]}, #{first["lon"]} (#{first["precision"]})"

Veja os planos de SDK e exemplos completos para cada linguagem

As chaves são opcionais

Um endereço de e-mail é todo o cadastro

Qualquer endereço recebe 2.500 requisições gratuitas por dia sem nenhuma chave, em todos os endpoints e hosts compatíveis, contadas a partir das 00:00 UTC. Uma chave leva um minuto quando você quiser uma: cadastre-se com seu nome, um endereço de e-mail e uma senha, e sua primeira chave aparece na tela. Sem empresa, sem cartão. Cada chave tem suas próprias 2.500 requisições gratuitas por dia, e as requisições feitas sem chave a partir da mesma rede compartilham essa cota, então uma conta acrescenta crédito, pacotes e um histórico de uso, e não um segundo lote gratuito de 2.500.

As chaves ficam vinculadas às máquinas que as usam. Uma chave de pagamento por uso atende dois endereços IP em qualquer janela móvel de 24 horas, uma chave Unlimited, três. Cada endereço ocupa sua vaga por 24 horas a partir da primeira requisição e depois a libera. Uma requisição de um endereço adicional é recusada e não é contada, e é isso que impede que uma chave vazada seja útil para outra pessoa. Precisa de mais endereços? Crie mais chaves ou adicione pacotes.

  1. Cadastre-se e obtenha uma chave

    E-mail e senha. A chave aparece uma única vez; copie-a. 2.500 requisições por dia, grátis, a partir de até dois endereços IP.

  2. Adicione crédito quando precisar de mais

    Recarregue a partir de € 5 com cartão ou criptomoeda. As requisições acima da cota gratuita de uma chave consomem € 0,0001 cada do saldo. O crédito nunca expira e nada é cobrado automaticamente.

  3. Ou adquira uma chave Unlimited

    Por € 50 ao mês você tem uma chave sem cobranças por requisição, utilizável a partir de três endereços IP por janela móvel de 24 horas. Contrate quantos pacotes você tiver de aplicações.

Preços

Grátis para começar, simples de pagar

Todos os endpoints custam o mesmo. Todos os hosts compatíveis contam da mesma forma. Sem faixas, sem cobrança por usuário, sem contrato. Preços em euros, pagos com cartão ou criptomoeda.

Chave gratuita

2.500 requisições por dia em cada chave. Cadastre-se com seu nome e e-mail; sem cartão. Os mesmos dados e os mesmos endpoints do uso pago.

Crédito

€ 0,0001 por requisição acima das 2.500 gratuitas diárias de uma chave, descontados de um saldo que você recarrega quando quiser. Sem mensalidade, sem expiração. 10.000 requisições em um dia consomem € 0,75 de crédito.

Chave Unlimited

€ 50 por mês. Uma chave sem cobranças por requisição em todos os endpoints e todos os hosts compatíveis, a partir de até três endereços IP por janela móvel de 24 horas.

Preços completos e exemplos práticos

SDKs

Bibliotecas oficiais, uma por linguagem, todas enxutas

Estamos escrevendo pequenas bibliotecas cliente para JavaScript e TypeScript, Python, PHP, Go, Java, C#, Ruby e Rust. Cada uma oferecerá respostas tipadas, timeouts razoáveis, novas tentativas em 429 e 503, e nada além disso. Quando uma estiver pronta, ela entra na página de SDKs com o comando de instalação.

Acompanhe o andamento dos SDKs

Preciso de uma chave para testar?

Não. Qualquer endereço recebe 2.500 requisições por dia sem chave e sem conta. A página de demonstração envia requisições direto do navegador sem chave. Uma chave gratuita leva um minuto quando você quiser crédito, um pacote Unlimited ou um histórico de uso.

O que acontece na requisição 2.501?

Se sua conta tiver crédito, a requisição é processada e consome € 0,0001 dele. Se não tiver, você recebe HTTP 402 até as 00:00 UTC ou até recarregar. Em uma chave Unlimited, nada muda.

Por que uma chave é limitada a dois ou três endereços IP?

As chaves são feitas para servidores, e o limite garante que uma chave vazada em um repositório público não possa ser usada a partir de cem máquinas. Cada endereço ocupa sua vaga por 24 horas a partir da primeira requisição e depois a vaga é liberada. Uma chave de pagamento por uso tem duas vagas, uma chave Unlimited, três. Para mais máquinas, crie mais chaves ou adicione pacotes.

Posso armazenar os resultados?

Sim. Coloque em cache, salve no seu banco de dados, exiba em um mapa de outro provedor. Os termos só pedem que você não revenda os dados brutos como um serviço de geocodificação próprio.

Envie sua primeira requisição agora

A demonstração envia requisições reais a partir do seu navegador com a sua chave e abre a resposta em JSON. Uma chave gratuita pede seu nome, um endereço de e-mail e um minuto; quando 2.500 por dia não bastarem mais, recarregue crédito ou adicione uma chave Unlimited.