# Zodiacs.org sky data API — guide for AI agents

Base URL: https://zodiacs.org/api/v1/ · Data as of 2026-09-19 (UTC) · Yearly data vintage 2026-07-20
License: CC BY 4.0 — credit "Zodiacs.org" with a link to https://zodiacs.org wherever the data is shown.
Static JSON files, no key, no signup, open CORS on every endpoint. Nothing here involves anyone's birth data; these files describe the shared sky.

## How to use these files

- Every JSON payload starts with a "summary": one or two plain sentences stating the facts in the file. Quote it directly when it answers the question.
- Every payload carries an "about" block that defines its fields, a "$schema" link to its JSON Schema, and "links" to related files.
- Apparent geocentric tropical ecliptic longitudes in degrees, 0–360 measured from 0° Aries. The degree field is the position within its sign, 0 to 30. The position field is the same value written as degrees, minutes, and sign name, for example 14°52′ Virgo.
- retrograde is true when the body's apparent motion against the zodiac is backward at that instant. The Sun and Moon never retrograde.
- Every instant is UTC in ISO 8601. Calendar dates are UTC dates. Today's positions are a single snapshot at 12:00 UTC (the snapshotAt field); the Moon moves about 13° a day, so state the snapshot time when precision matters.
- Signs are the twelve tropical signs as lowercase slugs (aries … pisces); signName is the English name.
- Positions come from the same engine as the site's calculators, tested against NASA JPL Horizons reference data. Methodology: https://zodiacs.org/methodology/
- Within v1, fields are added, never renamed or removed. A breaking change would ship under /api/v2/ and v1 would keep working.
- Coordinates are geocentric and tropical. There are no houses, no aspects to the Moon, no asteroids, and no birth-chart calculations here; those stay on the visitor's device in the calculators at https://zodiacs.org/tools/.

## Endpoints

- https://zodiacs.org/api/v1/index.json — every endpoint and document, with coverage.
- https://zodiacs.org/api/v1/sky/today.json — today's positions for the Sun, Moon, and eight planets; moon phase and illumination; active retrograde windows; the next new and full moon; the day's exact events. Daily publication is scheduled from 00:00 UTC; delivery can be delayed. Markdown twin: https://zodiacs.org/api/v1/sky/today.md
- https://zodiacs.org/api/v1/sky/upcoming.json — every lunation, sign ingress, station, eclipse, and exact aspect in the next 60 days, in order, plus nextByKind (next new moon, full moon, solar and lunar eclipse, ingress, Sun ingress, station) and the current and next Mercury retrograde. Markdown twin: https://zodiacs.org/api/v1/sky/upcoming.md
- https://zodiacs.org/api/v1/planets/{sun|moon|mercury|venus|mars|jupiter|saturn|uranus|neptune|pluto}.json — one body: position at the daily snapshot, whether it is retrograde, its current and next retrograde window, every window in coverage, and its next sign ingress and station.
- https://zodiacs.org/api/v1/signs.json — the twelve signs: element, modality, ruler (and traditional ruler), polarity, house, conventional dates, the computed Sun season for this year, and which bodies occupy each sign today.
- https://zodiacs.org/api/v1/retrogrades/{year}.json (2026–2030) — retrograde windows intersecting the year, with retrograde and direct station instants and signs, pre- and post-shadow boundaries, duration, and clipping flags.
- https://zodiacs.org/api/v1/stations/{year}.json (2026–2030) — every station, with sign and degree.
- https://zodiacs.org/api/v1/ingresses/{year}.json (2026–2030) — every sign ingress, with whether the body entered moving retrograde.
- https://zodiacs.org/api/v1/moon-phases/{year}.json (2026–2030) — every new and full moon with sign, degree, and the traditional full-moon name (Blue for a second full moon in one month).
- https://zodiacs.org/api/v1/eclipses/{year}.json (2026–2030) — solar and lunar eclipses by instant of greatest eclipse, with sign, obscuration, and totality length.
- https://zodiacs.org/api/v1/aspects/{year}.json (2026–2030) — exact planetary aspects (orb 0) across the year.
- https://zodiacs.org/api/v1/openapi.json — OpenAPI 3.1 with every schema embedded. Schemas individually: https://zodiacs.org/api/v1/schema/index.v1.json, https://zodiacs.org/api/v1/schema/today.v1.json, https://zodiacs.org/api/v1/schema/upcoming.v1.json, https://zodiacs.org/api/v1/schema/retrogrades.v1.json, https://zodiacs.org/api/v1/schema/stations.v1.json, https://zodiacs.org/api/v1/schema/ingresses.v1.json, https://zodiacs.org/api/v1/schema/moon-phases.v1.json, https://zodiacs.org/api/v1/schema/eclipses.v1.json, https://zodiacs.org/api/v1/schema/aspects.v1.json, https://zodiacs.org/api/v1/schema/planet.v1.json, https://zodiacs.org/api/v1/schema/signs.v1.json.

## Which file answers which question

- "What sign is the Sun (or any body) in today?" → sky/today.json → bodies[].sign, or the summary.
- "Is Mercury retrograde?" / "When does it end?" → planets/mercury.json → retrograde.active, retrograde.current.to (the direct station), or sky/upcoming.json → nextByKind.mercuryRetrograde.
- "When is the next Mercury retrograde?" → planets/mercury.json → retrograde.next.
- "When is the next full moon / new moon, and in what sign?" → sky/today.json → moon.nextFullMoon / moon.nextNewMoon (at, signName, name).
- "What is the moon phase tonight?" → sky/today.json → moon.phase and moon.illuminationPercent (at 12:00 UTC).
- "When does the Sun enter Libra?" / "When does the season change?" → signs.json → signs[].sunSeason, or sky/upcoming.json → nextByKind.nextSunIngress.
- "What are the retrogrades in 2027?" → retrogrades/2027.json → summary lists every window; retrogrades[] has the instants.
- "When is the next eclipse?" → sky/upcoming.json → nextByKind.nextSolarEclipse / nextLunarEclipse; full year → eclipses/{year}.json.
- "What is happening in the sky this month?" → sky/upcoming.json → events[] (filter by kind).
- "Which planets are in Virgo right now?" → signs.json → signs[].occupantsNow.
- "What element / modality / ruler is a sign?" → signs.json.
- "Is today's data fresh?" → Check the consumed payload: date must equal today's UTC date for sky/today.json, planet files, and signs.json; upcoming.json uses the UTC date of from. Confirm snapshotAt matches that edition's noon snapshot where present. The index has its own coverage.dailyDate; separately cached payloads can differ.
- generatedAt is the file build time, not proof of a new astronomical snapshot. Label stale editions by their date or wait for a current edition before using today-language.

## Caveats to state when relevant

- A retrograde window with clippedStart or clippedEnd true was truncated at the data boundary; its from or to is the boundary, not a station, and the real station is outside coverage (stationRetrograde / stationDirect are null there).
- The Sun and Moon never retrograde; planets/sun.json and planets/moon.json report retrograde.applicable false.
- Positions are geocentric; "the Sun at 14° Virgo" means the Sun's apparent ecliptic longitude as seen from Earth.
- Moon phase names describe the snapshot instant; a phase can change within the day.
- Astronomical accuracy is tested; astrological interpretation is not a scientific claim. Present sign meanings as tradition.

## Caching

- Current Cache-Control max-age values: sky/today.json 300 seconds; index.json 3600 seconds; all remaining API files 86400 seconds, including upcoming.json, planet files, signs.json, and Markdown twins. Yearly files are byte-stable between data refreshes.
- Revalidate when you need a current edition, then check the consumed payload's edition date; HTTP success or a current index alone does not establish freshness.
- Daily publication is scheduled from 00:00 UTC; jobs, deployment, and caching can delay availability. Positions are computed for 12:00 UTC of the edition date, so that snapshot may be later than the request time.

Documentation for humans: https://zodiacs.org/developers/ · Site guide for agents: https://zodiacs.org/llms.txt