# API pública del cielo

URL: https://astroletra.com/datos/api/
Actualizado: 2026-11-07T13:00:00+01:00
Fuente: Astroletra (https://astroletra.com). Datos calculados con efemérides JPL DE440 (NASA).

La API del cielo de Astroletra es gratuita y no pide clave. Una sola llamada a api.astroletra.com/api/v1/cielo, con la fecha y la zona horaria, devuelve en JSON la Luna, los aspectos exactos con su hora local, los retrógrados y la próxima lunación. Admite 60 peticiones por minuto y fechas a 7 días de hoy.

GET`api.astroletra.com**/api/v1/cielo**`

**Clave** No hace falta

**Precio** Gratis

**Límite** 60 por minuto

**Licencia** CC BY 4.0

Actualizado el 7 de noviembre de 2026 · [Redacción de Astroletra](https://astroletra.com/redaccion/)

## 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](https://astroletra.com/datos/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

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

### JavaScript

`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/`

### Python

`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

Campos principales de la respuesta JSON.

| Campo | Contenido |
| --- | --- |
| `moon` | Signo, grado dentro del signo, fase, iluminación (0-1) y próximo cambio de signo con hora local |
| `aspects` | Aspectos del día entre planetas; los exactos llevan at_local y time |
| `retrogrades` | Planetas retrógrados con since, until y shadow_to |
| `next_lunation` | Próxima luna nueva o llena con hora local y signo |
| `planets` | Posición de cada astro a mediodía local |
| `source, license, ephemeris, docs` | Atribución, licencia (CC BY 4.0), efemérides (JPL DE440) y esta página |

Respuesta

200 · JSON · 2026-11-10, recortada

`{ "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

- 60 peticiones por minuto y dirección IP. Al pasarlas, `429` con la cabecera `Retry-After`.
- `404` en `/api/v1/datos/` si no existe un fichero con ese nombre. La lista está en [datos abiertos](https://astroletra.com/datos/).
- `422` 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.
- Las 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](https://astroletra.com/datos/) (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.

### Python

`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")`

## ¿Qué hay que poner al usarla?

Los datos tienen licencia [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/deed.es). Basta con una línea visible junto a los datos, «Datos de Astroletra», con un enlace a astroletra.com. No hace falta registrarse ni avisarnos, aunque nos gusta saber dónde se usan. Cuéntanoslo en [info@astroletra.com](mailto:info@astroletra.com).

La semana de tu signo y sus días clave, el lunes en tu correo. Apúntate al boletín, es gratis.