Geocodificação

A AstroAPI disponibiliza um endpoint de geocodificação para pesquisar lugares e obter as respectivas coordenadas. Isto é útil para converter nomes de localizações em valores de latitude/longitude exigidos pelos endpoints de cálculo.

Pesquisar Lugares

Pesquisa cidades, vilas e outros lugares pelo nome:

curl -X GET "https://api.astroapi.cloud/api/geocoding/search?q=Amsterdam" \
  -H "X-Api-Key: your-api-key"

Parâmetros de Consulta

Parâmetro	Obrigatório	Descrição
q	Sim	Consulta de pesquisa (2–100 caracteres)
limit	Não	Número máximo de resultados (1–10, padrão: 5)
lang	Não	Código de idioma (padrão: "en")

Resposta

{
  "data": [
    {
      "id": "node_123456",
      "name": "Amsterdam",
      "displayName": "Amsterdam, North Holland, Netherlands",
      "latitude": 52.3676,
      "longitude": 4.9041,
      "country": "Netherlands",
      "countryCode": "NL",
      "state": "North Holland",
      "city": "Amsterdam"
    }
  ]
}

Campos da Resposta

Campo	Descrição
id	Identificador único (ID do OpenStreetMap)
name	Nome principal do lugar
displayName	Nome completo formatado com região e país
latitude	Coordenada de latitude
longitude	Coordenada de longitude
country	Nome do país
countryCode	Código ISO de 2 letras do país
state	Nome do estado/província/região
city	Nome da cidade (se aplicável)

Exemplos de Código

JavaScript

async function searchPlace(query) {
  const response = await fetch(
    `https://api.astroapi.cloud/api/geocoding/search?q=${encodeURIComponent(query)}`,
    {
      headers: {
        "X-Api-Key": "your-api-key"
      }
    }
  );
  const { data } = await response.json();
  return data;
}

// Utilização
const results = await searchPlace("London");
const { latitude, longitude } = results[0];
console.log(`London: ${latitude}, ${longitude}`);

Python

import requests

def search_place(query):
    response = requests.get(
        "https://api.astroapi.cloud/api/geocoding/search",
        params={"q": query},
        headers={"X-Api-Key": "your-api-key"}
    )
    return response.json()["data"]

# Utilização
results = search_place("Paris")
place = results[0]
print(f"Paris: {place['latitude']}, {place['longitude']}")

Usar com o Mapa Natal

Combina a geocodificação com o cálculo do mapa natal:

// Passo 1: Pesquisar o local de nascimento
const places = await searchPlace("New York");
const birthplace = places[0];

// Passo 2: Calcular o mapa natal
const response = await fetch("https://api.astroapi.cloud/api/calc/natal", {
  method: "POST",
  headers: {
    "X-Api-Key": "your-api-key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    datetime: "1990-06-15T14:30:00",
    latitude: birthplace.latitude,
    longitude: birthplace.longitude,
    timezone: "America/New_York"
  })
});

Suporte de Idiomas

O endpoint de geocodificação suporta múltiplos idiomas para nomes de lugares. Usa o parâmetro lang:

# Alemão
curl "https://api.astroapi.cloud/api/geocoding/search?q=Munich&lang=de"

# Francês
curl "https://api.astroapi.cloud/api/geocoding/search?q=Munich&lang=fr"

Os códigos de idioma suportados incluem: en, de, fr, es, it, nl, pt, ru, ja, zh, entre outros.

Cache

Os resultados de geocodificação são guardados em cache durante 24 horas para melhorar o desempenho. A mesma consulta de pesquisa devolverá resultados em cache sem contactar o serviço de geocodificação externo.

Limites de Utilização

Os pedidos de geocodificação contam para os teus limites de utilização da API. Consulta Limites de Utilização para mais detalhes.