Geocodificación

AstroAPI ofrece un endpoint de geocodificación para buscar lugares y obtener sus coordenadas. Esto es útil para convertir nombres de lugares en valores de latitud y longitud requeridos por los endpoints de cálculo.

Buscar Lugares

Buscad ciudades, pueblos y otros lugares por nombre:

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	Obligatorio	Descripción
q	Sí	Consulta de búsqueda (2-100 caracteres)
limit	No	Número máximo de resultados (1-10, por defecto: 5)
lang	No	Código de idioma (por defecto: "en")

Respuesta

{
  "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 de la Respuesta

Campo	Descripción
id	Identificador único (ID de OpenStreetMap)
name	Nombre principal del lugar
displayName	Nombre completo formateado con región y país
latitude	Coordenada de latitud
longitude	Coordenada de longitud
country	Nombre del país
countryCode	Código ISO de 2 letras del país
state	Nombre del estado/provincia/región
city	Nombre de la ciudad (si aplica)

Ejemplos 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;
}

// Uso
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"]

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

Uso con Carta Natal

Combinad la geocodificación con el cálculo de carta natal:

// Paso 1: Buscar lugar de nacimiento
const places = await searchPlace("New York");
const birthplace = places[0];

// Paso 2: Calcular carta 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"
  })
});

Soporte de Idiomas

El endpoint de geocodificación admite varios idiomas para los nombres de lugares. Usad el parámetro lang:

# Alemán
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"

Los códigos de idioma admitidos incluyen: en, de, fr, es, it, nl, pt, ru, ja, zh y más.

Caché

Los resultados de geocodificación se almacenan en caché durante 24 horas para mejorar el rendimiento. La misma consulta de búsqueda devolverá resultados en caché sin consultar el servicio de geocodificación externo.

Límites de Uso

Las solicitudes de geocodificación cuentan hacia vuestros límites de uso de la API. Consultad Límites de Uso para más detalles.