CycleCalcs
Advertisement

Home › API

The CycleCalcs API

A read-only HTTP API that answers the question, not the coordinates. Ask for the Moon and get "Waning Crescent, 6% lit, new moon in two days", not a longitude to decode. Every response is computed in real time with the same MIT-licensed Astronomy Engine behind this site, in UTC, reliable from 1700 to 2200.

Quick start

Every endpoint is a plain GET under /v1/. No headers, no auth. Try 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.

Try it live

Pick an endpoint, optionally set a date and a place, and run it against the live API.

Choose an endpoint and press "Run request".

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.

ParameterRequiredDescription
datenoISO 8601 date or datetime. Defaults to now.
lat, lonnoDecimal degrees. Provide both to get rise and set times.
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.

ParameterRequiredDescription
lat, lonyesDecimal degrees. Required for rise and set.
datenoISO 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": "..." } }
}
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.

ParameterRequiredDescription
datenoISO 8601 date or datetime. Defaults to now.
lat, lonnoDecimal degrees. Provide both for rise and set.
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.

ParameterRequiredDescription
datenoSearch forward from this moment. Defaults to now.
lat, lonnoDecimal 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 } }
}
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.

ParameterRequiredDescription
datenoISO 8601 date or datetime. Defaults to now.
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.

ParameterRequiredDescription
datenoISO 8601 date. Defaults to today.
lat, lonnoDecimal degrees. Adds the Sun's times.

A discovery root at /v1 lists every endpoint as JSON. 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 and what is next

The API is free and open while we learn how it is used. Please cache responses (a given date and place always give the same answer) and keep requests to a reasonable rate. Higher-volume, keyed access with guaranteed limits is planned; if you are building something that depends on it, there is a contact on the About page.

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.

Frequently asked questions

Is the CycleCalcs API free?

Yes. Version 1 is free, read-only, and open, with no API key required. Please cache responses and keep your usage reasonable so it stays fast for everyone.

Do I need an API key?

Not for version 1. Higher-volume access with guaranteed rate limits and keys is planned; if you are building something that depends on the API, get in touch through the About page.

What are the rate limits?

There is no hard limit in version 1, but the service is meant for fair, cached use of a few requests per second. Heavy or abusive traffic may be throttled, which is also when keyed tiers will arrive.

How accurate is it, and how should I credit it?

Positions are computed with the MIT-licensed Astronomy Engine and are reliable from 1700 to 2200, in UTC. A link back to cyclecalcs.com is appreciated but not required.

Terms of use

Using the CycleCalcs API means agreeing to these terms. They are short on purpose.