Geocodificação direta

Transforme texto em coordenadas. Aceita endereços completos, endereços parciais, códigos postais, nomes de lugares e pontos de interesse, em qualquer idioma.

Parâmetros

Exemplo

$ curl -H "X-API-Key: YOUR_KEY" "https://api.mygeocode.com/v1/forward?q=Dam+1,+Amsterdam&countries=nl&limit=1"

const url = new URL("https://api.mygeocode.com/v1/forward");
url.searchParams.set("q", "Dam 1, Amsterdam");
url.searchParams.set("countries", "nl");
url.searchParams.set("limit", "1");

const data = await (await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } })).json();
console.log(data.results[0]);

import requests

r = requests.get("https://api.mygeocode.com/v1/forward",
                 params={"q": "Dam 1, Amsterdam", "countries": "nl", "limit": 1}, headers={"X-API-Key": "YOUR_KEY"}, timeout=10)
print(r.json()["results"][0])

{
  "status": "ok",
  "query": "Dam 1, Amsterdam",
  "results": [
    {
      "formatted": "Dam 1, 1012 JS Amsterdam, Netherlands",
      "lat": 52.373119,
      "lon": 4.893604,
      "type": "address",
      "precision": "house",
      "confidence": 0.98,
      "place_id": "nl.addr.c21d40e8",
      "components": {
        "house_number": "1",
        "road": "Dam",
        "neighbourhood": "Centrum",
        "city": "Amsterdam",
        "state": "North Holland",
        "state_code": "NH",
        "postcode": "1012 JS",
        "country": "Netherlands",
        "country_code": "nl"
      },
      "bounds": { "north": 52.373519, "south": 52.372719, "east": 4.894204, "west": 4.893004 }
    }
  ]
}

Campos da resposta

Chaves dos componentes

Só aparecem as chaves que se aplicam. As mesmas chaves são usadas em todos os países.

Observações

• Os resultados são ordenados por uma combinação de confiança, precisão e proximidade. O primeiro resultado é o que você deve usar, a menos que esteja mostrando um seletor.
• Quando um número de casa não é encontrado numa rua conhecida, o resultado tem type: street e precision: street, com o número interpolado onde os dados permitem. Verifique precision se isso for importante para você.
• Códigos postais sozinhos funcionam bem como q. Para cargas de trabalho só com códigos postais, o endpoint de código postal é mais rápido e retorna o nome de lugar da autoridade postal.
• Uma consulta num sistema de escrita para um lugar que usa outro (cirílico para um endereço japonês, por exemplo) funciona, mas lang decide o sistema de escrita da resposta.

A mesma consulta nos formatos de outros provedores

Se você já tem código escrito para um desses provedores, mantenha-o: o host compatível aceita o mesmo caminho e os mesmos parâmetros e responde no formato de resposta desse provedor, com este endpoint por trás. Veja como funcionam os hosts compatíveis.

Consultas em lote

Envie um corpo JSON por POST para o mesmo caminho com queries, um array de até 100 endereços, e a resposta traz um array results com uma entrada por consulta, na ordem enviada. Cada entrada conta como uma requisição, e um lote maior do que o que resta da cota é recusado por inteiro.

$ curl -X POST "https://api.mygeocode.com/v1/forward" -H "Content-Type: application/json" -d '{"queries": ["Brandenburg Gate, Berlin", "Bahnhofstrasse 1, Zurich"]}'

Erros

400 invalid_request quando não há nem q, nem um campo estruturado, nem place_id, quando limit está fora do intervalo de 1 a 10, ou quando bounds ou proximity está malformado. Veja erros para o resto.