Skip to content

Birth Time Rectification​

POST
/api/calc/rectification

Rank candidate birth times against dated life events.

This is not an oracle, and the response says so itself. There is no validated ground truth
for rectification: no astrological technique is known to recover a birth time. What this
endpoint does is rank the candidate times in a window by how well each fits the rules you
turned on
, and show per candidate what produced its score. It is a structured way of working
that replaces hours of doing the same comparison by hand — not a claim to have found anything.

Three things follow, and they are part of the contract:

  1. There is never one answer. candidates is a ranking with scores, always several.
  2. The reasoning comes with it. Every candidate lists what each rule contributed and why,
    so you can read the ranking and reject it.
  3. Flatness is reported. discrimination is the normalized entropy of the ranking. At
    verdict: "none" the evidence separated nothing and the order is arbitrary — say that to
    whoever is reading it rather than presenting the accidental winner.

What moves with the birth time

Almost nothing does, and that is what makes the search possible. The ascendant and the
midheaven move 1° every four minutes, the houses follow them, the Moon covers 0.55° an hour,
and everything derived from the ascendant moves with it. A planet-to-planet aspect is the same
for the whole window, so a rule that looks at one contributes nothing and only dilutes what the
others found. Every rule here is angle-sensitive.

The rules

Rule What it looks for
transit-to-angle A transiting body on an angle on the event date. The sharpest rule: a 1° orb pins the time to about eight minutes.
house-placement A transiting body in a house the event type is about. Coarse — a house is 30° — but it keeps scoring when nothing lands on an angle.
solar-arc-to-angle A solar arc direction reaching an angle, either way round. As sharp as a transit contact.
progressed-moon The secondary-progressed Moon on an angle or in a matching house. A weak signal, weighted as one.
stated-time The time you gave, as a normal prior with spread sigmaMinutes. Leave it on: without it a single lucky transit six hours away wins.
profection Annual profections and zodiacal releasing. Declared but not yet available; it is reported as available: false rather than quietly scoring zero.

The event taxonomy

A fixed list, not free text. A description interpreted by a model would make the same request
answer differently on two days, and reproducibility is what this endpoint has to offer. Your own
wording goes in description and is carried into the evidence lines untouched.

Type Subject Houses (weight)
marriage marriage or committed partnership 7 (1), 5 (0.4), 1 (0.3)
separation separation or divorce 7 (1), 8 (0.5), 12 (0.3)
child-born birth of a child 5 (1), 4 (0.4), 11 (0.2)
relocation move of home 4 (1), 3 (0.4)
emigration emigration or long stay abroad 9 (1), 4 (0.6), 3 (0.3)
career-change change of career or standing 10 (1), 6 (0.5), 2 (0.3)
job-loss loss of work 6 (1), 10 (0.6), 12 (0.3)
education start of a course of study 9 (1), 3 (0.5)
illness illness 6 (1), 12 (0.6), 8 (0.3)
surgery surgery 8 (1), 6 (0.8), 12 (0.4)
accident accident or injury 6 (0.8), 8 (0.8), 1 (0.6)
bereavement death of someone close 8 (1), 4 (0.4), 12 (0.3)
financial-gain windfall or substantial gain 2 (1), 11 (0.5), 8 (0.4)
financial-loss substantial financial loss 2 (1), 8 (0.8), 12 (0.4)
public-recognition public recognition 10 (1), 11 (0.6), 1 (0.3)
other unclassified —

Limits and what it costs

The window is at most ±720 minutes, the resolution at least 1 minute, the candidates at most
1441, and the events at most 25. Past any of
those the request is a 400 with the reason — never a silently truncated search.

This is the most expensive route on the API and it is priced accordingly:

cost = 5 + events + ceil(candidates / 60)     capped at 60

An everyday question — ±2 hours at one minute, 8 events — costs 18. The largest possible one
costs 55. A request that fails costs nothing. The answer reports what it charged in
method.requestCost.

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
{
  
"dateTime": "string",
  
"location": {
  
  
"longitude": 0,
  
  
"latitude": 0,
  
  
"timezone": "string"
  
},
  
"windowMinutes": 120,
  
"resolutionMinutes": 1,
  
"events": [
  
  
{
  
  
  
"date": "string",
  
  
  
"type": "string",
  
  
  
"description": "string",
  
  
  
"weight": 1
  
  
}
  
],
  
"rules": [
  
  
"string"
  
],
  
"sigmaMinutes": 60,
  
"orbDegrees": 1,
  
"transitingPoints": [
  
  
"string"
  
],
  
"maxCandidates": 20,
  
"houseSystem": "placidus"
}

Responses​

A ranking of candidate birth times, with the contribution of each rule and how much the evidence discriminated

application/vnd.api+json
JSON
{
  
"data": {
  
  
"statedDateTime": "string",
  
  
"candidates": [
  
  
  
{
  
  
  
  
"dateTime": "string",
  
  
  
  
"localDateTime": "string",
  
  
  
  
"time": "string",
  
  
  
  
"offsetMinutes": 0,
  
  
  
  
"score": 0,
  
  
  
  
"logScore": 0,
  
  
  
  
"ascendant": 0,
  
  
  
  
"midheaven": 0,
  
  
  
  
"rules": [
  
  
  
  
  
{
  
  
  
  
  
  
"rule": "string",
  
  
  
  
  
  
"contribution": 0,
  
  
  
  
  
  
"evidence": "string"
  
  
  
  
  
}
  
  
  
  
]
  
  
  
}
  
  
],
  
  
"discrimination": {
  
  
  
"entropy": 0,
  
  
  
"effectiveCandidates": 0,
  
  
  
"verdict": "string",
  
  
  
"message": "string"
  
  
},
  
  
"method": {
  
  
  
"rules": [
  
  
  
  
{
  
  
  
  
  
"rule": "string",
  
  
  
  
  
"weight": 0,
  
  
  
  
  
"available": true
  
  
  
  
}
  
  
  
],
  
  
  
"resolutionMinutes": 0,
  
  
  
"window": {
  
  
  
  
"start": "string",
  
  
  
  
"end": "string"
  
  
  
},
  
  
  
"candidates": 0,
  
  
  
"events": 0,
  
  
  
"houseSystem": "string",
  
  
  
"orbDegrees": 0,
  
  
  
"sigmaMinutes": 0,
  
  
  
"transitingPoints": [
  
  
  
  
"string"
  
  
  
],
  
  
  
"requestCost": 0
  
  
}
  
}
}

Playground​

Authorization
Body

Samples​

Powered by VitePress OpenAPI

AstroAPI Documentation