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:
| Kind | What it finds |
|---|---|
aspect | A transiting body perfecting an aspect to a natal point or angle |
station | A planet turning retrograde or direct |
lunation | New and full moons, quarters, and the eclipses among them |
ingress | A body crossing into the next zodiac sign |
house-ingress | A 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
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
{
"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
}
}exactAtis the moment it perfects. A client that wants a calendar entry uses this.windowis the period it is within orb, when that means anything. A client that wants "what is running now" uses this. It isnullfor a point event such as a station.strengthis 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.minStrengthfilters on it, and that is the one knob that makes "only show me the important things" usable without understanding orbs.orbis how far off exact the aspect is atexactAt, in degrees. Almost always zero, becauseexactAtis where it perfects — but a body can turn around inside the orb without ever reaching the angle, and thenexactAtis the closest it came andorbsays how close. That is a real event, so it is reported rather than dropped; filter onorbif you only want perfected aspects.pass/ofPassesmark 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.labelis English and deliberately untranslated. Treat it as a fallback and build your own wording fromdetails, which carries ids rather than prose.
details per kind
| Kind | Fields |
|---|---|
aspect | transiting, natal, aspect, transitingLongitude, natalLongitude, orb, retrograde, pass, ofPasses |
station | point, direction (retrograde / direct), longitude, sign |
lunation | phase, moonLongitude, sunLongitude, sign, nodeDistance |
ingress | point, fromSign, toSign, longitude, direction |
house-ingress | point, fromHouse, toHouse, longitude, direction, houseSystem |
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
subject | object | For aspect and house-ingress | dateTime (YYYY-MM-DDTHH:mm) and location |
window | object | Yes | from and to, YYYY-MM-DD or ISO 8601. Always read as UTC |
kinds | array | Yes | One or more of the five kinds |
aspect | object | No | transiting, natal, aspects, orb, minStrength |
station | object | No | points |
lunation | object | No | phases |
ingress | object | No | points, signs |
houseIngress | object | No | points, houses, houseSystem |
limit | number | No | Default 100, maximum 500 |
cursor | string | No | The nextCursor of the previous page |
ical | boolean | No | Also 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.
| Filter | Applies to |
|---|---|
orb (a number, or a number per aspect) | aspect |
minStrength | aspect |
aspects | aspect |
transiting / natal | aspect |
points | station, ingress, house-ingress |
phases | lunation |
signs | ingress |
houses | house-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 scanned | Maximum window |
|---|---|
| Slow bodies only | 25 years |
| Including Mercury, Venus or the Sun | 5 years |
| Including the Moon | 1 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.
{
"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.
// 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.
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 }'{
"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.