The CycleCalcs API

A free astronomy API that answers the question, not the coordinates. Ask for the Moon and get "Waning Gibbous, 95% lit, sets at 06:14", not a longitude to decode.

• 29endpoints
• No keyno signup, no header
• 5,000requests a day, free
• 1700 to 2200date range

Every answer is computed live by the same engine that powers this site. Start with a single curl, or run one in the browser. Version 1 is frozen and keeps working.

• Interpreted, not raw

  Phase names, rise and set times, "evening sky, after dusk", the next eclipse and whether it is visible from your spot. The interpretation is the product.

• Real, live positions

  No lookup tables. Each call runs the engine on the spot, so answers are current and work for any date in range, for any place on Earth.

• Open and instant

  No key required, permissive CORS, and cache-friendly. Call it from a script, a Discord bot, a dashboard or a classroom.

Quick startv2

Every v2 endpoint is a plain GET under /v2/. No headers, no auth, no key. Try tonight's Moon from London:

curl "https://www.cyclecalcs.com/v2/moon?lat=51.5074&lon=-0.1278"

Response (trimmed; the full body also carries bright limb, libration, tropical sign, constellation, and the full geocentric and topocentric position):

{
  "endpoint": "/v2/moon",
  "data": {
    "phase": { "name": "Waning Gibbous", "illumination_percent": 95.2, "day_of_cycle": 18 },
    "summary": "The Moon is a waning gibbous, 95.2 percent lit, 17.4 days into its cycle. It sets at 06:14 and rises at 20:36 UTC.",
    "next_phases": [
      { "name": "Last Quarter", "instant": "2026-08-06T02:21:58.672Z", "days_until": 5.28 }
    ]
  },
  "links": { "docs": "https://www.cyclecalcs.com/api/reference.html#moon" },
  "meta": { "api_version": "2" }
}

Add ?at= (any ISO 8601 date or datetime) to ask about another moment; leave it off for right now. Location (lat and lon, decimal degrees) is optional on most endpoints and required on a few, including /v2/sun, /v2/rise-set, /v2/twilight and /v2/dark-window; each route's entry in the table below says which. Add ?format=csv on endpoints that support it for a spreadsheet-friendly download instead of JSON.

Run it in Postman

The same endpoints as a Postman collection, organised as worked examples rather than a route list: the response contract, the refusals and their cap blocks, field projection and CSV, and a chained observing-night workflow. Its tests assert the answers, not just the status codes. Nothing needs a key, so every request runs the moment you fork it.

Or browse it first on the public workspace.

Try it livev2

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

Choose an endpoint and press "Run request".

/v2/sun requires a location; the rest work with or without one. Full parameter lists are in the table below and at the endpoint reference.

The 29 v2 routes

Every route is a GET under /v2/. Click a route for its full parameter list, response shape and examples on the endpoint reference.

Start free, grow into it

Every tier serves the same 29 endpoints, the same precision and the same answers. What money buys is volume, and how much sky one request may ask for. Most integrations live on the free tier indefinitely; that is the design, not a trial.

Ultra and Mega carry the same range caps, so above Ultra you are buying volume, not reach: if the size of one request is what bounds you, Ultra is the last rung that changes it. Range maxima are per request shape, and on the largest endpoints the response-size bound binds before the tier bound; a refusal always names which one applied.

The paid rungs sell through the RapidAPI listing, which issues the key and handles billing. A subscriber's requests arrive through RapidAPI's gateway and are served at their plan's caps; the direct API stays keyless and free, which the keys page states as data.

Outgrowing Mega, or needing a shape the tiers do not fit? Contact us at info@cyclecalcs.com.

Going over returns 429 with a Retry-After you can honour, never a silently truncated answer, and the RateLimit and RateLimit-Policy headers carry your remaining budget so a client can back off before it is throttled rather than after.

These are a floor, not a ceiling: the versioning policy makes tightening a published limit a breaking change that never happens inside /v2, so these numbers can only ever go up. Full detail, including the headers and what a 429 looks like, is on API status and limits.

Version 1 has no hard limit but is meant for fair, cached use of a few requests a second; see its own fair use note.

More v2 documentation

• Errors

  Every RFC 9457 error code, what triggers it, and how to fix it.

• Accuracy

  The accuracy statement and residuals behind every computed position.

• Versioning

  How the v2 contract is versioned, and the full v1-to-v2 field map.

• Status

  Uptime and incident history for the live API.

• API keys

  The no-key Basic tier, and what a paid RapidAPI subscription changes.

• Terms

  The full terms of use for version 2.

• OpenAPI spec

  The machine-readable contract, generated from the same route table as this page.

• MCP server

  The API as eleven Model Context Protocol tools for Claude and other AI clients.

• Calendar feeds

  The same computations as subscribable iCalendar feeds, if a calendar is a better fit than JSON.

Frequently asked questions

Is the CycleCalcs API free?

Yes. The free Basic tier needs no key, no signup and no card, and inside /v2 its published limits can only ever go up, by the versioning policy. Three paid tiers, Pro at 5 dollars a month, Ultra at 9 and Mega at 15, sell monthly volume through the RapidAPI marketplace, which issues and bills the key. No tier changes an answer.

Do I need an API key?

No. The direct API needs no key and is served at the free Basic tier, and any key you send it is ignored with a disclosed warning. The paid tiers sell through RapidAPI, whose gateway holds the key; a subscription buys a higher rate limit and larger single requests, exactly as api/keys.html describes, and nothing else.

What are the rate limits?

Version 2 enforces 300 requests a minute, 2,000 an hour and 5,000 a day per caller. A caller is an IP address for direct keyless requests and an individual subscriber behind the RapidAPI gateway, so a backend that proxies every request for its users counts as one caller, while browsers or devices calling directly each count as their own; that is what the open CORS is for. Limits are reported on every response in the RateLimit header. Version 1 has no hard limit but is meant for fair, cached use of a few requests a second.

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

Positions are reliable from 1700 to 2200, in UTC; see api/accuracy.html for the full statement. Responses are computed facts and need no attribution, with one exception: /v2/places serves GeoNames data under CC BY 4.0 and requires the credit named in its meta.attribution.text.

What happened to version 1?

Nothing, on purpose. Version 1 is frozen: its endpoints, fields and behaviour will not change, so integrations built against it keep working. All new development happens on version 2; the version 1 page gives the version 2 equivalent of every version 1 route.

Older versions

Terms of use

The short version: the answers are computed astronomical facts and facts are yours to use, commercially or not; keep each response's attribution string in place, stay inside the published limits, and nothing here is navigation or safety advice. Provided as is, no warranty. The full terms say all of this precisely, and versioning promises that v1 never changes and v2 only grows.

All API documentation

• Developer hub: What to build and where every tool lives: API, MCP server, widgets.
• Overview and playground: What the API answers, the plans, and a live try-it panel.
• Endpoint reference: Every route, its parameters and a real captured response.
• Keys and plans: How to get a key, what each plan raises, and how quotas are counted.
• Error codes: The registered problem documents, one entry per code.
• Accuracy and residuals: Measured error against reference ephemerides, and the conventions every response states.
• Versioning policy: What is frozen, what may change, and how a change is announced.
• Status and limits: Rate windows, range caps and the current service position.
• MCP server: The same engine as tools an AI assistant can call directly.
• Version 1 (frozen): The original seven endpoints, still served and never changing shape.
• Terms of use: What you may do with the answers, including in commercial products.