Skip to content

Event Search ​

Every other endpoint on this API answers a question about one moment: give it a date, get the positions. POST /api/calc/events answers when. Give it a natal chart, a window and some criteria, and it returns every date inside that window on which something happens.

Five kinds of thing, in one uniform envelope:

KindWhat it finds
aspectA transiting body perfecting an aspect to a natal point or angle
stationA planet turning retrograde or direct
lunationNew and full moons, quarters, and the eclipses among them
ingressA body crossing into the next zodiac sign
house-ingressA body crossing into the next natal house

Required Module

Requires the event-search:calc module, which every plan carries. It is not sold separately.

A first query ​

bash
curl -X POST "https://api.astroapi.cloud/api/calc/events" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "dateTime": "1984-03-11T14:25",
      "location": { "latitude": 51.22, "longitude": 4.40, "timezone": "Europe/Brussels" }
    },
    "window": { "from": "2027-01-01", "to": "2028-12-31" },
    "kinds": ["aspect", "station", "lunation"],
    "aspect": {
      "transiting": ["saturn", "uranus", "neptune", "pluto", "jupiter"],
      "natal": ["sun", "moon", "ascendant", "midheaven"],
      "aspects": ["conjunction", "opposition", "square", "trine"],
      "minStrength": 0.4
    },
    "station": { "points": ["mercury", "mars"] },
    "lunation": { "phases": ["new", "full", "solar-eclipse", "lunar-eclipse"] },
    "limit": 100
  }'

Asking for several kinds at once is close to free: they share one ephemeris load. A kind that is not in kinds is not searched at all, and its criteria block is ignored — including for the purpose of caching.

What an event looks like ​

json
{
    "kind": "aspect",
    "exactAt": "2027-06-14T09:12:00.000Z",
    "window": { "start": "2027-05-02T04:19:00.000Z", "end": "2027-07-28T22:41:00.000Z" },
    "label": "Saturn square natal Moon",
    "strength": 0.71,
    "details": {
        "transiting": "saturn",
        "natal": "moon",
        "aspect": "square",
        "transitingLongitude": 121.44,
        "natalLongitude": 31.44,
        "orb": 0.0,
        "retrograde": true,
        "pass": 2,
        "ofPasses": 3
    }
}
  • exactAt is the moment it perfects. A client that wants a calendar entry uses this.
  • window is the period it is within orb, when that means anything. A client that wants "what is running now" uses this. It is null for a point event such as a station.
  • strength is 0–1. For an aspect it comes from the crossing's own strength: how exact it gets, how slowly it moves, how long it lasts. aspect.minStrength filters on it, and that is the one knob that makes "only show me the important things" usable without understanding orbs.
  • orb is how far off exact the aspect is at exactAt, in degrees. Almost always zero, because exactAt is where it perfects — but a body can turn around inside the orb without ever reaching the angle, and then exactAt is the closest it came and orb says how close. That is a real event, so it is reported rather than dropped; filter on orb if you only want perfected aspects.
  • pass / ofPasses mark the passes of a retrograde series. A triple Saturn square is one experience spread over nine months; without this it reads as three unrelated rows and nobody can tell they belong together.
  • label is English and deliberately untranslated. Treat it as a fallback and build your own wording from details, which carries ids rather than prose.

details per kind ​

KindFields
aspecttransiting, natal, aspect, transitingLongitude, natalLongitude, orb, retrograde, pass, ofPasses
stationpoint, direction (retrograde / direct), longitude, sign
lunationphase, moonLongitude, sunLongitude, sign, nodeDistance
ingresspoint, fromSign, toSign, longitude, direction
house-ingresspoint, fromHouse, toHouse, longitude, direction, houseSystem

Parameters ​

ParameterTypeRequiredDescription
subjectobjectFor aspect and house-ingressdateTime (YYYY-MM-DDTHH:mm) and location
windowobjectYesfrom and to, YYYY-MM-DD or ISO 8601. Always read as UTC
kindsarrayYesOne or more of the five kinds
aspectobjectNotransiting, natal, aspects, orb, minStrength
stationobjectNopoints
lunationobjectNophases
ingressobjectNopoints, signs
houseIngressobjectNopoints, houses, houseSystem
limitnumberNoDefault 100, maximum 500
cursorstringNoThe nextCursor of the previous page
icalbooleanNoAlso return a subscribable calendar feed URL

A bare date as window.to means the whole of that day, so "to": "2027-12-31" covers the year. A bound that carries a time is read as UTC even without a Z.

subject is only needed for the two kinds that are read against a chart. A station, a lunation and a sign ingress are facts about the sky, so a query for those alone needs no birth data.

Filters ​

Filter what is worth filtering, and nothing more. There is no and/or tree and no expression language: a query DSL is six months of work and a security problem, and nobody asks for one. If you want compound logic, make two requests and intersect the results yourself.

FilterApplies to
orb (a number, or a number per aspect)aspect
minStrengthaspect
aspectsaspect
transiting / natalaspect
pointsstation, ingress, house-ingress
phaseslunation
signsingress
houseshouse-ingress

Window limits ​

This is the part support will be asked about, so it is spelled out.

The Moon is the sharp edge. It covers 13° a day, so it has to be sampled many times a day for a crossing not to slip between two samples; Pluto can be sampled once a week. One Moon in aspect.transiting multiplies the work by an order of magnitude. So how long a window may be depends on what is in it:

Bodies being scannedMaximum window
Slow bodies only25 years
Including Mercury, Venus or the Sun5 years
Including the Moon1 year

"Bodies being scanned" means the transiting bodies of an aspect query plus the points of a station, ingress or house-ingress query. A lunation search does not count as a Moon search: phases are found by estimating from the Moon's mean elongation and refining once, not by sampling a fine grid.

A window past the limit is a 400 with the reason and the maximum in it — never a silently shortened window. A truncated time axis hands you an answer that is correct, incomplete, and indistinguishable from a complete one.

json
{
    "error": "Bad Request",
    "message": "That window is 730 days; the maximum for this set of bodies is 1 year (365 days). The Moon covers 13° a day, so it has to be sampled many times a day. Shorten the window, or drop the fast bodies from it."
}

Paging ​

Paging is on time, not on an offset. An offset over an ephemeris scan that runs again is not stable; a date is, and it is also readable.

jsonc
// First page
{ "window": { "from": "2027-01-01", "to": "2029-12-31" }, "kinds": ["aspect"], "limit": 100 }

// Response
{ "data": { "events": [ /* 100 */ ], "truncated": true, "nextCursor": "2027-11-04T18:22:00.000Z" } }

// Next page: feed nextCursor back as cursor
{ "window": { "from": "2027-01-01", "to": "2029-12-31" }, "kinds": ["aspect"], "limit": 100,
  "cursor": "2027-11-04T18:22:00.000Z" }

truncated tells you there was more inside the window than fitted in the page. Without it a client that fills a page believes it has everything.

Calendar feed ​

Set ical: true and the response carries an icalUrl alongside the events: a signed, subscribable calendar feed of that exact query.

bash
curl -X POST "https://api.astroapi.cloud/api/calc/events" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "subject": { "dateTime": "1984-03-11T14:25",
        "location": { "latitude": 51.22, "longitude": 4.40, "timezone": "Europe/Brussels" } },
        "window": { "from": "2027-01-01", "to": "2027-12-31" },
        "kinds": ["aspect", "station"],
        "ical": true }'
json
{
    "data": {
        "events": [],
        "truncated": false,
        "nextCursor": null,
        "icalUrl": "https://api.astroapi.cloud/api/calc/events/ical?q=eyJzdWJ...&expires=1801900800&sig=..."
    }
}

Paste that URL into Google Calendar, Apple Calendar or Outlook as a calendar subscription. It carries its own signature — the same mechanism as a signed chart image URL — so it needs no API key, which is what makes it work in a calendar application at all. The signature covers the path and every query parameter, so a feed URL can be neither pointed at another endpoint nor edited into a different query. It is valid for thirty days.

Fetching the feed does not count against your quota. The search that produced the URL was charged when it ran.

What it counts for ​

One event search is honestly more than one calculation, and it is priced accordingly:

cost = 1 + ceil(windowDays / 365) × (1 + number of fast transiting bodies)

capped at 50, where "fast" means the Moon, Mercury, Venus or the Sun. One year over slow planets costs 2. Three years with the Moon in it costs 7.

A repeated query is served from cache and counts as one. Events are immutable — the ephemeris does not change — so the same question gives the same answer forever, and a cached answer is never stale. Two clients that write the same question with their keys in a different order or their arrays in a different sequence share the same cache entry.

What this is not ​

  • Not webhooks. Push is its own thing, with a scheduler, delivery, retries and signing. This is the search engine that one would need underneath.
  • Not interpretation texts. An event is a date and a label. What it means comes from the content endpoints and is a separate module.
  • Not a bulk ephemeris. This gives events, not positions per day.
  • Not an eclipse catalogue. A lunation is classified as an eclipse when it falls near a lunar node, which is what an astrologer reads. Magnitude, type and the path of visibility are a different instrument.

AstroAPI Documentation