API pública del cielo

Petición

GET https://api.astroletra.com/api/v1/cielo con dos parámetros opcionales, date (AAAA-MM-DD, a ±7 días de hoy en la zona pedida; por defecto, hoy) y tz (zona IANA como America/Bogota; por defecto, Europe/Madrid). Se admiten España, las capitales de los países hispanohablantes y algunas zonas más; la lista completa y la especificación están en openapi.json (OpenAPI 3.1).

date

AAAA-MM-DD Por defecto, hoy; hasta 7 días antes o después.

tz

Zona IANA Por defecto, Europe/Madrid.

curl -s "https://api.astroletra.com/api/v1/cielo?tz=America/Mexico_City"

const r = await fetch("https://api.astroletra.com/api/v1/cielo?tz=America/Mexico_City");
const cielo = await r.json();
console.log(cielo.moon.sign_label, cielo.moon.next_sign_change?.time);
// Muestra «Datos de Astroletra» con un enlace a https://astroletra.com/

import json, urllib.request
url = "https://api.astroletra.com/api/v1/cielo?tz=America/Mexico_City"
cielo = json.load(urllib.request.urlopen(url))
print(cielo["moon"]["sign_label"], [r["planet_label"] for r in cielo["retrogrades"]])

Qué devuelve

{
  "date": "2026-11-10",
  "tz": "America/Mexico_City",
  "moon": {
    "sign_label": "Sagitario",
    "degree": 4.77,
    "phase": "Waxing Crescent",
    "illumination": 0.02,
    "next_sign_change": {
      "time": "02:35",
      "date_local": "2026-11-10",
      "to_sign_label": "Sagitario"
    }
  },
  "aspects": [
    {
      "p1_label": "Venus",
      "p2_label": "Marte",
      "type_label": "sextil",
      "exact": true,
      "time": "00:47"
    }
  ],
  "retrogrades": [
    {
      "planet_label": "Mercurio",
      "since": "2026-10-24",
      "until": "2026-11-13",
      "shadow_to": "2026-11-30"
    }
  ],
  "next_lunation": {
    "phase": "full",
    "at_local": "2026-11-24T08:53-06:00",
    "date_local": "2026-11-24",
    "sign": "Gemini",
    "sign_label": "Géminis"
  },
  "source": "Astroletra — https://astroletra.com",
  "license": "CC BY 4.0"
}

Límites y errores

• 42960 peticiones por minuto y dirección IP. Al pasarlas, 429 con la cabecera Retry-After.
• 404404 en /api/v1/datos/ si no existe un fichero con ese nombre. La lista está en datos abiertos.
• 422422 si la zona no está en la lista admitida o la fecha está a más de 7 días de hoy; el cuerpo explica qué campo falla y, para la zona, da la lista.
• 1 hLas respuestas se guardan una hora en caché (Cache-Control: public, max-age=3600; un día en las fechas pasadas, que no cambian) y llevan Access-Control-Allow-Origin: *, así que se pueden pedir desde el navegador.

Los ficheros de datos, también por la API

Las tablas de datos abiertos (lunaciones, eclipses, retrógrados, entradas del Sol y calendarios) se pueden pedir a la API con el mismo nombre de fichero, en GET https://api.astroletra.com/api/v1/datos/lunaciones.csv. Es la dirección que conviene usar desde un programa. La descarga directa de astroletra.com rechaza el agente genérico de algunas bibliotecas, como urllib en Python, y la API admite cualquier cliente.

import csv, io, urllib.request
url = "https://api.astroletra.com/api/v1/datos/lunaciones.csv"
texto = urllib.request.urlopen(url).read().decode("utf-8-sig")
lunas = list(csv.DictReader(io.StringIO(texto)))
print(len(lunas), lunas[0]["phase"], lunas[0]["madrid"])
# Con pandas: pandas.read_csv(url, encoding="utf-8-sig")