Skip to content

Event Search​

POST
/api/calc/events

Find every date in a window on which something happens: aspect crossings to the natal chart,
retrograde and direct stations, lunations and eclipses, sign ingresses and natal house ingresses.

Ask for as many of the five kinds as you like — they share one ephemeris load, so a second kind is nearly free, and a
kind that is not in kinds is not searched and costs nothing.

Every event comes back in the same envelope: kind, exactAt, window, label, strength and a per-kind
details. For an aspect, details.pass and details.ofPasses mark the passes of a retrograde series, so a triple
Saturn square reads as one stretch rather than three unrelated rows.

Window limits. The Moon covers 13° a day and has to be sampled many times a day; Pluto gets away with weeks. 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

A lunation search does not count as a Moon search: phases are reached by estimate and refinement, not by a fine grid.

limit defaults to 100 and caps at 500. Paging is on time, not on an offset: pass
the nextCursor you were given back as cursor. truncated says there was more inside the window than fitted.

Cost. This counts for more than one request, because it is honestly more than one calculation:
1 + ceil(windowDays / 365) × (1 + number of fast transiting bodies), capped at 50. A repeated query is served from
cache and counts as one — events never change, so the answer never goes stale.

Set ical: true to get icalUrl alongside the events: a signed, subscribable calendar feed of this exact query that
needs no API key, so it can be pasted straight into a calendar application.

Authorizations​

ApiKeyAuth

API key for authentication. Get your API key from the dashboard.

Type
API Key (header: X-Api-Key)

Request Body​

application/json
JSON
{
  
"subject": {
  
  
"dateTime": "string",
  
  
"location": {
  
  
  
"longitude": 0,
  
  
  
"latitude": 0,
  
  
  
"timezone": "string"
  
  
}
  
},
  
"window": {
  
  
"from": "string",
  
  
"to": "string"
  
},
  
"kinds": [
  
  
"string"
  
],
  
"aspect": {
  
  
"transiting": [
  
  
  
"string"
  
  
],
  
  
"natal": [
  
  
  
"string"
  
  
],
  
  
"aspects": [
  
  
  
"string"
  
  
],
  
  
"orb": 0,
  
  
"minStrength": 0
  
},
  
"station": {
  
  
"points": [
  
  
  
"string"
  
  
]
  
},
  
"lunation": {
  
  
"phases": [
  
  
  
"string"
  
  
]
  
},
  
"ingress": {
  
  
"points": [
  
  
  
"string"
  
  
],
  
  
"signs": [
  
  
  
"string"
  
  
]
  
},
  
"houseIngress": {
  
  
"points": [
  
  
  
"string"
  
  
],
  
  
"houses": [
  
  
  
0
  
  
],
  
  
"houseSystem": "placidus"
  
},
  
"profection": {
  
  
"from": "string",
  
  
"includeMonths": true
  
},
  
"zodiacalReleasing": {
  
  
"from": "string",
  
  
"levels": 0,
  
  
"peaksOnly": true
  
},
  
"firdaria": {
  
  
"includeNodes": true,
  
  
"includeSubPeriods": true
  
},
  
"limit": 0,
  
"cursor": "string",
  
"ical": true
}

Responses​

The events found in the window

application/vnd.api+json
JSON
{
  
"data": {
  
  
"events": [
  
  
  
{
  
  
  
  
"kind": "string",
  
  
  
  
"exactAt": "string",
  
  
  
  
"window": {
  
  
  
  
  
"start": "string",
  
  
  
  
  
"end": "string"
  
  
  
  
},
  
  
  
  
"label": "string",
  
  
  
  
"strength": 0,
  
  
  
  
"details": {
  
  
  
  
  
"additionalProperties": null
  
  
  
  
}
  
  
  
}
  
  
],
  
  
"truncated": true,
  
  
"nextCursor": "string",
  
  
"window": {
  
  
  
"from": "string",
  
  
  
"to": "string"
  
  
},
  
  
"kinds": [
  
  
  
"string"
  
  
],
  
  
"icalUrl": "string"
  
}
}

Playground​

Authorization
Body

Samples​

Powered by VitePress OpenAPI

AstroAPI Documentation