# CycleCalcs API v2 The CycleCalcs API v2 is a read-only astronomy API, free to use without a key, that returns interpreted answers (not raw ephemeris) over HTTP, computed live with the open-source MIT-licensed Astronomy Engine. Positions are arcminute class for the Sun, Moon and planets across 1700 to 2200, degrading toward the ends of that window. Pure astronomy only: no astrology, no fortune-telling, no claims that sky events affect people or Earth. Base URL: https://www.cyclecalcs.com/v2 ## Authentication No API key is required: the free Basic tier is keyless, and a direct request is served at the anonymous tier whatever it sends. The paid Pro, Ultra and Mega tiers are sold through the RapidAPI listing and authenticate at that gateway, never with a query parameter. Limits are PER CALLER, keyed on a salted hash of the client address (per subscriber behind the gateway). There is no global limit and one caller cannot exhaust another's quota. 300 requests per minute (anonymous) 2000 requests per hour (anonymous-hour) 5000 requests per day (anonymous-day) ## Response Envelope Every response carries a nine-key JSON envelope: endpoint: The path that served this response, for example /v2/sun. computed_at: The revision stamp of the data and code that produced this answer. It is NOT the wall-clock time the response was generated. Two identical requests return identical bytes and the same computed_at, which is what makes the ETag meaningful and a conditional request able to return 304. For a request whose answer depends on the current time, it is the later of the data revision and the quantized evaluation instant for that cache class. query: A copy of the parsed and resolved query parameters, for verification. data: The computed answer. Structure and content vary by endpoint. warnings: An array of warning objects raised by the computation. Empty if none. links: A set of URLs: self (the canonical request), first (first page), next (next page, if pagination applies and more data exists), and others depending on the endpoint. meta: Metadata about the response: the request budget consumed, conventions used (thresholds, models, etc.), why fields are missing (not_computed), and the accuracy envelope. attribution: A text string naming every data source; always present and never empty, because all answers rest on cited data. docs: A URL to the reference documentation for this endpoint on the live site. ## Shared Parameters These parameters are accepted by multiple endpoints: at: An instant in ISO 8601 format (for example 2026-07-28 or 2026-07-28T21:30:00Z). Default is now. UTC unless tz is supplied; if given, the instant is in that time zone. start, end: A range, in the same ISO 8601 grammar as at, times included. start is inclusive. Whether a row landing exactly on end is returned DEPENDS ON THE ENDPOINT: most return it, the four event searches (seasons, apsides, moon-nodes, eclipses) do not, and sun, rise-set and twilight compare end against the START of a day, so their last row can finish after end. Every endpoint's rule is published under limits.range_boundaries in /v2/conventions. Send count instead of end to take a fixed number of rows from start. Ranges must honour endpoint-specific caps on width and count. Pages are earliest first. step: How to slice a range. Examples: 1h, 6h, 1d, 7d, 1mo. Maximum 1 year. count: How many results to return. Must be a positive integer up to the endpoint cap. lat, lon: Observer latitude and longitude in decimal degrees. Latitude from -90 to 90, north positive. Longitude from -180 to 180, east positive. Both required together. elevation_m: Observer elevation in metres above mean sea level. From -500 to 9000. place: A place name or a place_id (from /v2/places) to resolve location and timezone. tz: An IANA time zone name (for example Europe/London) to resolve ambiguous or nonexistent local times, and to stamp output times. format: The output format. json is the default. csv and txt are available where the endpoint declares them; each route's supported set is listed with it below. svg and ics are NOT available on any route and are refused with BAD_FORMAT. fields: A comma-separated list of dot-paths into `data`, for example fields=bodies.name,bodies.position.horizontal.azimuth_deg. Projects `data` only; meta and attribution are never stripped. An unresolvable path is 400 BAD_FIELDS. Default is the whole of `data`. It does not change the CSV column set. shape: The structure of the output: flat or nested (default). Affects the response body shape. precision: Decimal places on numeric output: 0 to 9. Default is 6. pretty: A boolean; true adds indentation and line breaks to JSON. Default is false. verbosity: Controls what meta includes: full (default), compact (less prose), or minimal (just numbers and codes). limit, cursor: For pagination. limit is results per page. cursor is an opaque string from a previous response's links.next, used to fetch the next page. ## Endpoints ### Phase 1 (Discovery and Core) /v2: The discovery document: every endpoint, parameter, convention and limit Parameters: format?, precision?, pretty?, verbosity? Formats: json /v2/conventions: Every convention, threshold, model and limit the API uses, as data Parameters: format?, precision?, pretty?, verbosity? Formats: json /v2/enums: Every enumerated value the API can emit or accept, as data STATUS: Partially blocked. The meteor_showers set is withheld until the meteor catalogue reduction clears its licence review. Parameters: set?, endpoint?, format?, precision?, pretty?, verbosity? Formats: json /v2/attribution: Every source behind every endpoint, with its licence and what it obliges a caller to do Parameters: endpoint?, fields?, format?, precision?, pretty?, verbosity? Formats: json /v2/positions: Where every body is, in every frame, with refraction stated Parameters: at?, start?, end?, step?, count?, bodies?, body?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, frames?, frame?, refraction?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit?, cursor? Formats: json, csv /v2/rise-set: Rise, transit, set and lower transit for any named object, with an explicit status at every latitude Parameters: body, bodies?, at?, start?, end?, lat, lon, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, day_anchor?, horizon?, search_horizon_days?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit?, cursor? Formats: json, csv /v2/sun: The complete solar day: every named boundary, azimuth, day length and polar status Parameters: lat, lon, elevation_m?, place?, place_strategy?, at?, start?, end?, step?, day_anchor?, depressions?, tz?, ambiguous?, nonexistent?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit?, cursor? Formats: json, csv, txt /v2/moon: The Moon in render-ready form: phase, illumination, bright limb, libration Parameters: at?, start?, end?, step?, count?, lat?, lon?, elevation_m?, place?, place_strategy?, hemisphere?, next_phases?, style?, tz?, ambiguous?, nonexistent?, day_anchor?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit?, cursor? Formats: json, csv, txt /v2/time: Every time scale, sidereal time, solar time, the equation of time and the Julian dates Parameters: at?, start?, end?, step?, count?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit?, cursor? Formats: json, csv /v2/today: The whole sky for a place right now, in one request STATUS: Partially blocked. Meteor-shower events are withheld from next_events until the meteor catalogue reduction clears its licence review. Parameters: at?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, day_anchor?, include?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity? Formats: json, txt ### Phase 2 (Events and Cycles) /v2/seasons: Every equinox and solstice in a window, with the length of each season they bound Parameters: at?, start?, end?, count?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, hemisphere?, include?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit?, cursor? Formats: json, csv /v2/apsides: Every perigee, apogee, perihelion and aphelion in a window, with its distance Parameters: at?, start?, end?, count?, body?, bodies?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, kind?, include?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit?, cursor? Formats: json, csv /v2/moon-nodes: Every crossing of the ecliptic by the Moon, the node longitudes and the eclipse seasons they define Parameters: at?, start?, end?, count?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, node_model?, kind?, include?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit?, cursor? Formats: json, csv /v2/eclipses: Solar and lunar eclipses with global geometry, local circumstances and an explicit answer to whether you can see it STATUS: Partially blocked. The Saros MEMBER number is withheld: it needs a 223-row table of series-start epochs, which is catalogue data, and the obvious source has not cleared a provenance check. The series number is closed-form and is published. Parameters: at?, start?, end?, count?, direction?, type?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, visible_only?, include?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit?, cursor? Formats: json, csv, txt /v2/planet-board: All eight planets in one request: place, brightness, apparent size, retrograde state, next station and whether it is worth looking tonight Parameters: at?, start?, end?, step?, count?, bodies?, body?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, day_anchor?, include?, sort?, refraction?, frames?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit?, cursor? Formats: json, csv, txt /v2/retrogrades: Every retrograde and direct station of every planet in a window, with the loop length, its arc, and the interval of triple crossing Parameters: at?, start?, end?, body?, bodies?, motion?, include?, step?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit?, cursor? Formats: json, csv /v2/conjunctions: Close approaches between body pairs in a window, ranked, with the separation and whether the pair is observable or lost in twilight Parameters: at?, start?, end?, bodies?, pairs?, max_separation_deg?, min_elongation_deg?, kind?, frame?, step?, sort?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit?, cursor? Formats: json, csv /v2/separation: The angular separation between any two targets at an instant, and the minima of that separation across a window Parameters: a, b, at?, start?, end?, step?, max_separation_deg?, frame?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit?, cursor? Formats: json, csv, txt /v2/cycles: 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 Parameters: at?, start?, end?, step?, count?, keys?, kind?, family?, include?, tz?, ambiguous?, nonexistent?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit? Formats: json, csv, txt /v2/phases: The lunar phase calendar: every quarter with its distance, apparent size, supermoon classification under BOTH competing rules, traditional name and any eclipse Parameters: at?, start?, end?, count?, phases?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, day_anchor?, include?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit?, cursor? Formats: json, csv, txt ### Phase 3 (Specialized) /v2/twilight: All three twilights plus day and night as non-overlapping intervals that tile the whole day, each with the reason it starts and ends, and a checksum the caller can assert Parameters: at?, start?, end?, count?, step?, lat, lon, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, day_anchor?, depressions?, refraction?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit?, cursor? Formats: json, csv /v2/dark-window: The genuinely dark moonless observing window of a night: astronomical night intersected with the Moon being down, ranked across up to 62 nights with a trend Parameters: at?, lat, lon, elevation_m?, place?, place_strategy?, nights?, sun_depression_deg?, moon_altitude_max_deg?, moon_illumination_max?, tz?, ambiguous?, nonexistent?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity? Formats: json, csv /v2/sidereal-time: Greenwich and local sidereal time, apparent and mean side by side, with the equation of the equinoxes that separates them and the nutation terms it is built from Parameters: at?, start?, end?, step?, count?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity? Formats: json, csv, txt /v2/equation-of-time: How far a sundial runs ahead of or behind the clock, from the real Sun rather than a day-of-year series, with the Sun place that makes a range query an analemma Parameters: at?, start?, end?, step?, count?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, include?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity? Formats: json, csv, txt /v2/libration: Lunar libration, the sub-Earth point, the axis and bright-limb position angles, and with the terminator token the sub-solar point and the colongitude that fixes where the terminator falls Parameters: at?, start?, end?, step?, count?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, include?, refraction?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity? Formats: json, csv /v2/jupiter-moons: Where the four Galilean moons are, and every transit, shadow transit, eclipse and occultation in the window, with both contact instants for each Parameters: at?, start?, end?, step?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, moons?, events?, refraction?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity? Formats: json, csv /v2/sky-quality: Naked-eye limiting magnitude and aperture reach for a sky class you supply, with an explicit machine-readable statement that the number is a tuned estimate rather than a measurement Parameters: bortle?, nelm?, equipment?, aperture_mm?, lat?, lon?, elevation_m?, place?, place_strategy?, at?, tz?, ambiguous?, nonexistent?, include?, refraction?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity? Formats: json, csv, txt /v2/places: Place-name search and reverse lookup against the self-hosted GeoNames index, returning name, region, country, coordinates and IANA timezone with a stable place_id STATUS: Conditional use. Every response is GeoNames data under CC BY 4.0, so every response carries rights: attribution_required and the credit in meta.attribution.text. The rest of the API is unrestricted. Parameters: q?, id?, lat?, lon?, country?, region?, limit?, min_population?, radius_km?, format?, fields?, shape?, precision?, pretty?, verbosity?, time_format? Formats: json, csv /v2/planet-events: The apparition cycle of Mercury and Venus as events: conjunctions, greatest elongations, peak brightness and transits, with the current cycle state Parameters: at?, start?, end?, body?, bodies?, kinds?, lat?, lon?, elevation_m?, place?, place_strategy?, tz?, ambiguous?, nonexistent?, time_format?, format?, fields?, shape?, precision?, pretty?, verbosity?, limit?, cursor? Formats: json, csv ## Error Responses When an error occurs, the response is an HTTP 4xx or 5xx with a problem document in JSON: status: The HTTP status code (400, 401, 403, 404, 406, 409, 410, 413, 414, 429, 500, 503). code: A machine-readable error code such as BAD_DATE or RANGE_TOO_LARGE. title: A human-readable title of the problem. detail: Additional details, such as which parameter was wrong or what the acceptable values are. parameter: The name of the parameter that caused the error, or null if the problem is not parameter-specific. The complete error catalogue is at https://www.cyclecalcs.com/api/errors.html ## Rate Limit 300 requests per minute, per caller (anonymous). 2000 requests per hour, per caller (anonymous-hour). 5000 requests per day, per caller (anonymous-day). The limit is keyed on a salted hash of the client address, never on a stored raw address. It counts only requests that reach the origin: an answer served from the CDN cache does not consume quota. If rate-limited, the response is HTTP 429 with a Retry-After header naming the seconds to wait, and RateLimit headers naming the policy closest to exhaustion. Per-request compute budget: 250,000 engine calls and 8 seconds of wall time. Requests that exceed the budget are refused with HTTP 400. ## Output Rights https://www.cyclecalcs.com/v2/attribution ## Worked Examples These URLs return 200 and demonstrate the API in action: https://www.cyclecalcs.com/v2?verbosity=compact https://www.cyclecalcs.com/v2/sun?lat=51.4778&lon=-0.0015&at=2026-07-27&tz=Europe/London https://www.cyclecalcs.com/v2/moon?at=2026-07-27T21:00:00Z https://www.cyclecalcs.com/v2/positions?bodies=sun,moon&at=2026-07-28T21:30:00Z&lat=51.4778&lon=-0.0015 https://www.cyclecalcs.com/v2/rise-set?body=moon&at=2026-12-21&lat=69.6492&lon=18.9553&tz=Europe/Oslo https://www.cyclecalcs.com/v2/today?at=2026-07-28T21:00:00Z&lat=51.4778&lon=-0.0015&tz=Europe/London https://www.cyclecalcs.com/v2/eclipses?at=2026-07-28T21:30:00Z&lat=51.4778&lon=-0.0015&count=2 https://www.cyclecalcs.com/v2/planet-board?at=2026-07-28T21:30:00Z&lat=51.4778&lon=-0.0015&tz=Europe/London https://www.cyclecalcs.com/v2/phases?start=2026-07-29&end=2026-08-31&tz=Europe/London https://www.cyclecalcs.com/v2/cycles?at=2026-07-28T21:30:00Z ## Reference Full reference documentation, including parameters for every endpoint, error codes, and interactive examples, is available at https://www.cyclecalcs.com/api.html