Where we are in every astronomical cycle the site tracks, with an explicit statement of whether each number was computed, observed, or is an interval with no live phase

Where we are in every astronomical cycle the site tracks, with an explicit statement of whether each number was computed, observed, or is an interval with no live phase. Formats: json, csv, txt. Example: GET /v2/cycles?at=2026-07-28T21:30:00Z

get/v2/cycles

Request

  • Base URL: https://www.cyclecalcs.com
  • URL: https://www.cyclecalcs.com/v2/cycles
  • Auth: one of:
    • none
    • API key in header X-RapidAPI-Key

Query parameters

atstring

The instant to evaluate. ISO 8601: a date (2026-06-21), or a date and time with an optional seconds, fraction and either Z or a numeric UTC offset (+hh:mm, no seconds). No offset and no tz reads as UTC. Or jd: followed by a Julian Day on the UT scale, read as UTC whatever tz says: jd:2461000.5 is 2025-11-21T00:00:00Z. Reliable from 1700 to 2200.

startstring

The start of a range query, inclusive. ISO 8601: a date (2026-06-21), or a date and time with an optional seconds, fraction and either Z or a numeric UTC offset (+hh:mm, no seconds). No offset and no tz reads as UTC. Or jd: followed by a Julian Day on the UT scale, read as UTC whatever tz says: jd:2461000.5 is 2025-11-21T00:00:00Z. Reliable from 1700 to 2200.

endstring

The end of a range query. A row landing exactly on end IS returned: the window is [start, end]. Every endpoint's rule is published as data under limits.range_boundaries in /v2/conventions. ISO 8601: a date (2026-06-21), or a date and time with an optional seconds, fraction and either Z or a numeric UTC offset (+hh:mm, no seconds). No offset and no tz reads as UTC. Or jd: followed by a Julian Day on the UT scale, read as UTC whatever tz says: jd:2461000.5 is 2025-11-21T00:00:00Z. Reliable from 1700 to 2200.

stepstring

Sampling stride for a range query: a number plus a unit, one of min, m (minute), h (hour), d (day), w (week), mo (month) or y (year), for example 1h, 6h or 1d. Resolves to at least 1 minute and at most 1 year. Needs start. This is the generic grammar; an endpoint that narrows it documents the narrowing on its own step parameter, and /v2/conventions publishes every narrowing under limits.step_grammar.endpoint_policies.

countinteger

Number of rows to return from a range query, counted forward from start. Mutually exclusive with end.

keys'anomalistic_month' | 'anomalistic_year' | 'axial_precession' | 'callippic' | 'draconic_month' | 'eclipse_year' | 'exeligmos' | 'great_conjunction' | 'hale' | 'inex' | 'lunar_nodal_cycle' | 'lunar_standstill' | 'metonic_cycle' | 'saros' | 'sidereal_month' | 'sidereal_year' | 'sunspot_cycle' | 'synodic_month' | 'tritos' | 'tropical_year' | 'venus_pentagram'

A comma-separated list of specific cycle keys to return. Mutually exclusive with kind/family. Omit for every cycle.

kind'computed_phase' | 'observed' | 'interval' | 'state'

Filter cycles by how their current position is known: computed from the ephemeris, observed (a live dataset), a named interval with no live phase, or a discrete state.

family'conjunction' | 'eclipse' | 'eclipse_period' | 'lunar_month' | 'node' | 'secular' | 'sunspot' | 'venus' | 'year'

Filter to one cycle family. Mutually exclusive with keys.

include'fraction' | 'next_event' | 'observed' | 'definition'

Comma-separated optional blocks to include. Omit for the endpoint default set.

tzstring

An IANA time zone name, for example Europe/London or America/Chicago. Numeric offsets and abbreviations are not accepted. Governs how a date-only or offset-free at/start/end is read, and how local instants are rendered when time_format=iso. Before 1970 the tz database records the history of a zone for its principal location only, and some names are links to another zone: the tz_source_boundary_1970 warning names whose history was used, and tzdb_lmt_interval marks a local mean time. Neither changes an offset.

ambiguous'first' | 'last' | 'error'

How to resolve a local time that a clock repeated, such as the return from daylight saving. error refuses with 409 AMBIGUOUS_LOCAL_TIME.

nonexistent'error' | 'shift_forward' | 'shift_back'

How to resolve a local time that never happened, such as inside a spring-forward gap. error refuses with 400 NONEXISTENT_LOCAL_TIME.

time_format'iso' | 'unix'

How instants are rendered: iso for ISO 8601 strings carrying the effective offset, or unix for integer seconds since the epoch. An ISO offset has no seconds field, so an instant in a pre-1972 local mean time era whose offset has seconds (Moscow +02:30:17 until 1916) is written in UTC with a Z; utc_offset_seconds stays exact, utc_offset_iso rounds it to the nearest minute, and the tzdb_lmt_interval warning says so.

formatstring

Response representation. Each endpoint serves a subset of json, csv and txt; see that operation's description for the exact list, or GET /v2 for every endpoint's formats array. An unsupported value is 400 BAD_FORMAT with the accepted list in supported.

fieldsstring

Comma-separated dot paths into data (for example moon.phase_name,moon.illumination) so only those fields are returned. Up to 64 paths; an array element is addressed by its object key, never by index.

shape'nested' | 'flat'

nested returns the documented object tree. flat returns one object with dotted keys, format=json only.

precisioninteger

Decimal places for numeric fields.

pretty0 | 1

Whether the JSON body is indented (1) or compact (0). Has no effect on csv or txt.

verbosity'full' | 'compact'

full includes prose notes, frame definitions and withheld-field reasons in meta. compact keeps every value and every machine-readable name and drops the prose.

limitstring

See the endpoint description at /api/reference.html.

Response

The answer.

endpointstring required

The endpoint path that produced this response.

computed_atstring date-time required

A revision stamp, never a wall clock: identical requests return identical bytes, so a fixed_instant or reference response can be cached for a year and 304 stays reachable.

queryobject required

The request as understood: every resolved input (instant, location, presentation options) plus ignored, in the order spec-00 13.2 defines. Shape is endpoint-specific.

dataunknown required
linksobject required

Related URLs. self reproduces this exact response; docs is always present; others (page, spec, next, first, explain) appear where relevant.

metaobject required

Provenance: engine version, rights and attribution, cache class, accuracy statement, tzdb version, and endpoint-specific conventions (refraction model, horizon definitions, time scales, and so on). Never subject to fields projection.

attributionstring required

The credit line, byte-identical to meta.attribution.text.

docsstring uri required

The human-readable reference section for this endpoint.

Example response

{
  "endpoint": "/v2/sun",
  "computed_at": "2026-08-01T00:00:00.000Z",
  "links": {
    "self": "https://www.cyclecalcs.com/v2/sun?at=2026-06-21&lat=51.4778&lon=-0.0015",
    "docs": "https://www.cyclecalcs.com/api/reference.html#sun",
    "spec": "https://www.cyclecalcs.com/v2/openapi.json",
    "page": "https://www.cyclecalcs.com/sunrise-sunset-calculator.html",
    "explain": "https://www.cyclecalcs.com/learn/seasons.html"
  },
  "attribution": "Computed by CycleCalcs (cyclecalcs.com) with the MIT-licensed Astronomy Engine. Positional astronomy only.",
  "docs": "https://www.cyclecalcs.com/api/reference.html#sun"
}

Changes

No recorded changes to this operation across all 1 revision of this API.