API Version 1 frozen

Version 1 is frozen on purpose: its endpoints, fields and behaviour will not change, so anything built against it keeps working exactly as documented here. All new development happens on version 2. This page is the complete v1 record: what changed in v2, the six v1 endpoints, the fair-use note, and the field-by-field migration map.

What v2 offers over v1

28 endpoints, not 6. Positions in any frame, rise and set for any body, seasons, apsides, lunar nodes, eclipses with full local circumstances, all eight planets in one call, retrogrades, conjunctions, angular separation, cycles, twilight bands, the darkest window of a night, sidereal time, the equation of time, lunar libration, the Galilean moons of Jupiter, sky quality and place lookup.
Self-describing. /v2, /v2/conventions, /v2/enums and /v2/attribution publish the endpoint list, the constants, the enumerated values and the licensing as data, and /v2/openapi.json is the machine-readable contract.
Every field states its unit. Snake-case names like illumination_percent and distance_km, and every response states its frame, epoch, refraction model and engine version, not just in prose.
Ranges, not just instants. Send start, end, step or count on most endpoints and get a series back, every eclipse in a year or every conjunction in a decade, not one answer at a time.
CSV and plain text alongside JSON, for endpoints where a spreadsheet or a terminal is the destination.
RFC 9457 errors. A stable code, a docs link, and often a hint and a worked example, in place of v1's plain {"error":{"code","message","hint"}}. See the error catalogue.
Real HTTP caching. ETag and 304 Not Modified, plus structured RateLimit headers so a client can see its remaining budget without guessing.
v1 does not go away. It is frozen exactly as documented below, so anything already built against it keeps working.

Version 1frozen, legacy

Version 1 is frozen. Its endpoints, fields, error bodies and cache headers will not change; anything built against it today keeps working. It is documented in full below for existing callers. New projects should start with the v2 quick start on the developers page; each v1 route below links to its v2 equivalent.

Every v1 endpoint is a plain GET under /v1/. No headers, no auth. Tonight's Moon:

curl "https://www.cyclecalcs.com/v1/moon"

{
  "phase": {
    "name": "Waning Crescent",
    "illuminationPercent": 6,
    "waxing": false,
    "dayOfCycle": 27
  },
  "constellation": "Taurus",
  "next": { "newMoon": "2026-07-14T09:44:04Z", "fullMoon": "2026-07-29T14:36:19Z" },
  "daysUntil": { "newMoon": 1.91, "fullMoon": 17.11 }
}

Add a location with ?lat=&lon= (decimal degrees) to get rise and set times and local eclipse visibility. Add ?date= (any ISO 8601 date or datetime) to ask about another moment; leave it off for right now.

Version 1 endpoints

GET /v1/moon

The Moon's phase, illuminated fraction, day of the 29.53-day cycle, constellation, and the next new, first-quarter, full and last-quarter moons. With a location, adds rise, transit and set.

Parameter	Required	Description
`date`	no	ISO 8601 date or datetime. Defaults to now.
`lat`, `lon`	no	Decimal degrees. Provide both to get rise and set times.

Migrating: GET /v2/moon. date becomes at. v2 adds bright limb, libration, tropical sign, constellation, full geocentric and topocentric position, and a plain-language summary field.

GET /v1/sun

Sunrise, sunset, solar noon, day length and the three twilights (civil, nautical, astronomical) for a location, plus the Sun's constellation and zodiac position. Handles polar day and night.

Parameter	Required	Description
`lat`, `lon`	yes	Decimal degrees. Required for rise and set.
`date`	no	ISO 8601 date. Defaults to today.

Example response

{
  "sunrise": "2026-12-21T08:04:...Z",
  "sunset": "2026-12-21T15:53:...Z",
  "dayLength": "7h 49m",
  "twilight": { "astronomical": { "dawn": "...", "dusk": "..." } }
}

Migrating: GET /v2/sun. date becomes at; lat and lon are still required. v2 adds azimuth at every event and a depressions parameter for custom twilight angles.

GET /v1/planets

Every planet (Mercury through Pluto): its constellation, tropical zodiac position, apparent magnitude, elongation from the Sun, and a plain-language visibility verdict ("Evening sky, after dusk", "Lost in the Sun's glare"). With a location, adds rise and set.

Parameter	Required	Description
`date`	no	ISO 8601 date or datetime. Defaults to now.
`lat`, `lon`	no	Decimal degrees. Provide both for rise and set.

Migrating: GET /v2/planet-board. date becomes at. v2 adds retrograde state, next station and apparent size. (The name /v2/planets is reserved and is never served.)

GET /v1/next-eclipse

The next solar and next lunar eclipse anywhere on Earth: kind (total, partial, annular, penumbral), peak time, obscuration and Saros series. With a location it adds whether the headline solar eclipse reaches you, the next solar eclipse actually visible from your spot (often a later one), and whether the next lunar eclipse sits above your horizon.

Parameter	Required	Description
`date`	no	Search forward from this moment. Defaults to now.
`lat`, `lon`	no	Decimal degrees. Provide both for local visibility.

Example response

// from Sydney (lat=-33.87&lon=151.21): the 2026 total does not reach there
{
  "solar": { "kind": "total", "peak": "2026-08-12T17:45:...Z", "sarosSeries": 126,
    "visibleFromYourLocation": false },
  "nextVisibleSolarEclipse": { "kind": "total", "peak": "2028-07-22T04:01:...Z",
    "sunAltitudeAtPeak": 28.9, "sameAsNextGlobal": false },
  "lunar": { "kind": "partial", "peak": "2026-08-28T04:12:...Z", "sarosSeries": 138,
    "fromYourLocation": { "visible": false, "moonAltitudeAtPeak": -36.3 } }
}

Migrating: GET /v2/eclipses. date becomes at. v2 takes a count and a direction, and states obscuration, magnitude and full local circumstances for every eclipse in the window, not just the next one.

GET /v1/cycles

Where we are right now in each major astronomical cycle: the synodic and sidereal month, the tropical year and seasons, the lunar nodal cycle, the Jupiter-Saturn great conjunction, the Venus figure, the Metonic cycle, Solar Cycle 25 and the eclipse season. Each returns a fraction from 0 to 1 and a human-readable position. This is the API behind the site's cosmic clock.

Parameter	Required	Description
`date`	no	ISO 8601 date or datetime. Defaults to now.

Migrating: GET /v2/cycles. date becomes at; add start, end, step and count for a series instead of one instant. v2 states, for each cycle, whether the number is computed, observed, or an interval with no live phase.

GET /v1/today

A whole-sky summary in one call: the Moon's phase, the planets that are well-placed, the next eclipse, and (with a location) the Sun's rise and set. The quickest way to power a "tonight" widget or a morning briefing.

Parameter	Required	Description
`date`	no	ISO 8601 date. Defaults to today.
`lat`, `lon`	no	Decimal degrees. Adds the Sun's times.

Migrating: GET /v2/today. date becomes at; an include parameter chooses which of sun, moon, planets, events and night to return.

A discovery root at /v1 lists every endpoint as JSON, same as /v2 does for version 2 (see the v2 equivalent). Errors come back with a clear 400 and a message, for example an out-of-range date or a latitude past the poles.

Fair use (version 1)

Version 1 is free and open, unchanged since it shipped. Please cache responses (a given date and place always give the same answer) and keep requests to a reasonable rate. It has no hard limit, but heavy or abusive traffic may be throttled.

The three embeddable widgets share this engine and mirror /v1/moon, /v1/next-eclipse and /v1/planets, so a widget on your page and an API call return the same answer.