Exact Aspect Calendar API
Search a date window for exact aspects between transiting and natal planets. The engine brackets and solves longitude crossings instead of treating a daily sample as an exact event.
POST /v1/astrology/aspect-calendar50,000 credits per monthly allowance · no trial · no automatic overage charges. Plan details ↗
What this API provides.
Find exact transit-to-natal conjunctions, sextiles, squares, trines and oppositions. Get solved UTC crossings and explicit station-contact metadata.
Exact UTC event timestamps and residual metadata
Station-aware search partitions for retrograde motion
Separate numerical station contacts instead of fabricated crossings
Send
- A known-time birth object
- start_date and 1–365 days defining a UTC window
- Optional aspects array: conjunction, sextile, square, trine, opposition
Receive
- events with moving body, natal body, aspect, angle and UTC time
- station_contacts with tolerance and crossing-confidence flags
- Search method, numerical tolerances and warnings
A time, not a daily guess.
The first 5 events from the real result. Download the complete response for all events, methods and residuals.
- moon sextile natal venusAspect 60°
- sun sextile natal saturnAspect 60°
- moon square natal sunAspect 90°
- moon sextile natal mercuryAspect 60°
- moon sextile natal uranusAspect 60°
Real input. Real output.
Precomputed by the actual calculation engine and response formatter, using synthetic example data. No purchased access or paid provider call was needed.
{
"locale": "en",
"birth": {
"date": "1990-05-21",
"time": "14:30:00",
"timezone": "Europe/Madrid",
"latitude": 40.4168,
"longitude": -3.7038
},
"start_date": "2026-11-17",
"days": 7
}{
"request_id": "f9878144d747d5a17b94d49b87b9633a",
"api_version": "v1",
"locale": "en",
"data": {
"window": {
"start_at": "2026-11-17T00:00:00Z",
"end_at_exclusive": "2026-11-24T00:00:00Z",
"days": 7
},
"events": [
{
"at": "2026-11-17T01:03:27.975Z",
"transiting_body": "moon",
"natal_body": "venus",
"aspect": "sextile"
},
{
"at": "2026-11-17T11:16:35.244Z",
"transiting_body": "sun",
"natal_body": "saturn",
"aspect": "sextile"
}
],
"station_contacts": [],
"method": {
"type": "exact_transit_to_natal_ecliptic_longitude_crossings",
"search_scale": "TT",
"grid_max_hours": 6,
"solver": "station_partition_then_bracketed_bisection",
"time_bracket_tolerance_seconds": 0.01,
"station_derivative": "central_difference_plus_minus_60_seconds",
"station_contact_tolerance_deg": 1e-7
}
},
"interpretation": {
"locale": "en",
"kind": "astrology/aspect-calendar",
"disclaimer": "Symbolic reflection, not a verified prediction or professional advice.",
"coverage": {
"total_facts": 27,
"selected_facts": 27,
"omitted_count": 0,
"selection_method": "all-source-facts-v1",
"full_numeric_data_unchanged": true
},
"method": {
"engine": "celestack-original-rules-v1",
"corpus": "celestack-original-compositional-v1",
"corpus_version": "2026-11-17.2",
"fallback_locale": null,
"editorial_status": "agent-authored; independent linguistic review pending",
"predictive_validity": "symbolic interpretations are not scientifically validated predictions",
"chinese_solar_terms": "numeric calendar output only; no rule paragraphs in this corpus"
},
"items": [
{
"fact_id": "astrology/aspect-calendar.events.1",
"title": "Moon — Venus",
"text": "Transit to natal aspect crossing: transiting Moon, natal Venus, sextile, target angle 60°. Calculated time (UTC): 2026-11-17T01:03:27.975Z. Look for a modest opportunity to connect these themes through practice. The astronomical contact does not guarantee a personal event.",
"source": {
"at": "2026-11-17T01:03:27.975Z",
"transiting_body": "moon",
"natal_body": "venus",
"aspect": "sextile",
"angle": 60,
"orientation_deg": -60,
"transit_longitude": 319.71374096,
"natal_longitude": 19.7137408,
"residual_deg": 1.608e-7,
"contact": "crossing",
"id": "astrology/aspect-calendar.events.1",
"type": "astro_event_aspect"
}
}
]
},
"warnings": [],
"credits_used": 10
}The response preview selects whole fields and array entries for readability; no numeric values have been replaced. The full download preserves all fields, arrays and interpretation. The request_id is synthetic, and credits_used shows the configured successful-request cost; no credits were consumed.
cURL request — use your own API key and a new idempotency key
curl --request POST 'https://api.celestackapi.com/v1/astrology/aspect-calendar' \
+ --header 'Authorization: Bearer YOUR_API_KEY' \
+ --header 'Content-Type: application/json' \
+ --header 'Idempotency-Key: aspect-calendar-api-example-001' \
+ --data '{
"locale": "en",
"birth": {
"date": "1990-05-21",
"time": "14:30:00",
"timezone": "Europe/Madrid",
"latitude": 40.4168,
"longitude": -3.7038
},
"start_date": "2026-11-17",
"days": 7
}'Example computed 2026-11-17. Full fixture manifest, engine versions and SHA-256 checksums ↗
Ways to use it.
- Personalized aspect calendars
- Event-time alerts selected by your own product rules
- Exact-event overlays beside a daily sampled forecast
12 response locales
English, Ukrainian, Japanese, Spanish, French, German, Portuguese, Arabic, Italian, Hindi, Chinese and Korean.
Calculation values remain language-independent. Localized rule text is agent-authored; independent native-language review remains pending. Machine-readable field names stay stable.
Limits and interpretation.
- The UTC window is start-inclusive and end-exclusive. It is not a local-midnight window.
- A station within numerical angular tolerance is reported separately and is not asserted to be a proven transverse crossing.
- Exact numerical timing is not evidence that a life event or outcome will occur.
Interpretive content is for symbolic reflection and entertainment. It is not a verified personal prediction or professional advice. Read the API conventions ↗
Choose your billing.
Both options include 50,000 credits per monthly allowance, resetting monthly. No trial and no automatic overage. Custom needs use a contact form.
Saved results: 7-day retention, up to 128 MiB per organization on this initial shared deployment, with a 512 MiB shared retained-result limit. Capacity can return a temporary error; there are no automatic extra charges. Production artifacts have separate retention. All usage and resource limits ↗. Checkout availability is shown in your account.
Frequently asked questions.
How does this differ from a daily forecast?
The aspect calendar solves actual longitude crossings in a date interval. A forecast evaluates one local-noon sample per day and can miss an event between samples.
How are retrograde stations handled?
The search partitions longitude motion around estimated stations. Near-station tolerance contacts are returned separately with proven_transverse_crossing: false rather than counted as proven crossings.
Which time interval is searched?
The window begins at 00:00 UTC on start_date and ends days later. The beginning is included and the ending is excluded, helping consecutive requests avoid duplicate boundary events.
What does access cost?
Access is USD 39.99 per month or USD 199 billed annually, with no trial. Both billing options provide 50,000 credits per monthly allowance. 10 credits per started 30-day block; 1–365 days per request Daily credit, attempt, rate and resource limits apply. There are no automatic overage charges.