Skip to content

Rectification ​

Rectification is the search for a birth time that is not on the record — or not on it to the minute. It is the most expensive handwork in the trade, and most of those hours go into something a computer does better: taking hundreds of candidate times, working out the chart each one implies, and comparing all of them against the same list of dated events.

POST /api/calc/rectification does that comparison. You give it a birth date, a place, how uncertain the time is, and the life events you can date. It gives back a ranking of candidate times, with the reasoning per candidate, and a statement about how much the evidence actually separated them.

What this is and is not

There is no validated ground truth for rectification. No astrological technique is known to recover a birth time, and this endpoint does not claim to. What it does is rank candidate times by how well each fits the rules you turned on, and show you why — a structured, repeatable way of working, not an oracle.

Three consequences, and they are part of the response format:

  1. There is never one answer. candidates is always a ranking.
  2. The reasoning comes with it. Every candidate lists what each rule contributed and on what grounds, so you can read the ranking and reject it.
  3. Flatness is reported. When the evidence separates nothing, discrimination.verdict says none and the ranking is arbitrary. Show that to whoever is reading it. An answer that crowns the accidental winner of a tie is an answer that lies.

Required Module

rectification:calc, from module:rectification. Included in Deluxe, and available separately. It is deliberately not part of the Calculations bundle.

Why a birth time is findable at all ​

Almost nothing in a chart moves with the birth time, and that is the whole opening.

Moves with the timeHow fast
Ascendant~1° per 4 minutes
Midheaven~1° per 4 minutes
House cusps and everything placed in a housefollows the angles
Moon~0.55° per hour
Anything derived from the ascendant (Fortune, Spirit, profections)follows the ascendant
Every other planetnegligible — the Sun covers 0.04° in an hour

So the evidence that can pin a time is angular evidence. A rule that looks at an aspect between two planets gives near enough the same score to every candidate in the window: it contributes nothing and dilutes what the other rules found. Every rule in this endpoint is angle-sensitive, and that is the single sharpest decision in its design.

A request ​

bash
curl -X POST "https://api.astroapi.cloud/api/calc/rectification" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "dateTime": "1978-03-22T15:00",
    "location": {
      "latitude": 52.37,
      "longitude": 4.89,
      "timezone": "Europe/Amsterdam"
    },
    "windowMinutes": 120,
    "resolutionMinutes": 1,
    "sigmaMinutes": 45,
    "events": [
      { "date": "2003-06-14", "type": "marriage",       "description": "married in Utrecht" },
      { "date": "2006-02-01", "type": "child-born",     "description": "first child" },
      { "date": "2009-09-30", "type": "job-loss" },
      { "date": "2011-05-12", "type": "relocation",     "description": "moved to Rotterdam" },
      { "date": "2014-11-03", "type": "career-change" },
      { "date": "2019-01-21", "type": "bereavement",    "description": "father died" }
    ]
  }'

Parameters ​

ParameterTypeRequiredDescription
dateTimestringYesBirth date and stated time, YYYY-MM-DDTHH:mm, local clock time at location. The date is fixed; the time is the centre of the search
locationobjectYeslatitude, longitude and an IANA timezone
eventsarrayYes1 to 25 dated events. See the taxonomy below
windowMinutesnumberNoHalf-width of the search, 1–720. Default 120, so ±2 hours
resolutionMinutesnumberNoMinutes between candidates, 1–60. Default 1
sigmaMinutesnumberNoSpread of the prior around the stated time. Default 60
rulesarrayNoWhich rules to score with. Defaults to all implemented rules
orbDegreesnumberNoOrb for a contact with an angle, 0.1–5. Default 1
transitingPointsarrayNoTransiting bodies the angular rules look at. Defaults to the slow bodies
maxCandidatesnumberNoHow many candidates come back, 1–200. Default 20
houseSystemstringNoDefault placidus

An event is { date, type, description?, weight? }. date is YYYY-MM-DD or YYYY-MM-DDTHH:mm; a bare date is taken as 12:00 UTC. description is your own wording — it is carried into the evidence lines and never interpreted. weight (0–5, default 1) says how much this event counts against the others.

The window and the resolution together are a limit

The search is capped at 1441 candidates, which is exactly ±12 hours at one minute: the grid is symmetric around the stated time and includes it, so the count is 2 × (window ÷ resolution) + 1. Anything past that is rejected with a 400 telling you so — never quietly narrowed. A whole day fits at a 4-minute resolution (361 candidates), which is the right trade when the time is completely unknown: find the region first, then run a second, finer search inside it.

The rules ​

RuleWhat it looks forWeight
transit-to-angleA transiting body on an angle on the event date3.0
house-placementA transiting body in a house the event type is about1.5
solar-arc-to-angleA solar arc direction reaching an angle, either way round2.0
progressed-moonThe progressed Moon on an angle, or in a matching house1.0
stated-timeThe time you gave, as a normal prior1.0
profectionAnnual profections and zodiacal releasingnot yet available

transit-to-angle is the heaviest, because the angles are the fastest thing in the chart. A transiting body within a degree of an angle pins the birth time to about eight minutes; nothing else here comes close. The question is asked backwards from the usual one — not "when does Saturn reach my midheaven" but "given that it happened on 3 May 2019, which midheaven would that be" — which needs no crossing search at all.

house-placement is coarse on purpose. A house is thirty degrees wide, so it divides the window into blocks of roughly two hours rather than pinning a minute. What it buys is a different kind of evidence: it keeps scoring when no transit happened to land on an angle.

solar-arc-to-angle is as sharp as the first. The arc itself is the same for every candidate — it comes from the Sun, which barely moves in a two-hour window — but the angles it is directed to are not.

progressed-moon is the lightest, and honestly so. The progressed Moon covers a degree a month, far too slow to pin a minute on its own; what ties it to the birth time is that it starts from the natal Moon and meets the candidate's own angles and cusps.

stated-time should stay on. "Around three in the afternoon" is information, and without it the endpoint regularly returns a time six hours away because one transit happened to line up. It is a normal prior: a candidate one sigmaMinutes out gives up half a log unit, one four out gives up eight.

profection is declared but not implemented yet. It is reported as available: false in method.rules rather than quietly scoring zero — a rule that contributes nothing looks exactly like a rule that found nothing, and you should be able to tell those apart.

Why the Moon is not a transiting body by default

Most events are dated to the day, not the minute. A transiting body therefore carries a whole day of uncertainty in its position: ±6.5° for the Moon and ±0.5° for the Sun, against an orb of 1°. A Moon contact with an angle says nothing about the birth time — but it scores, and it scores for some candidate on every event. That is noise dressed as evidence. Saturn moves 0.1° a day; those are the bodies a dated event can actually pin an angle with. If your events are timed to the minute, add the fast bodies through transitingPoints.

The event taxonomy ​

Fixed, and not free text. A description interpreted by a language model would make the same request answer differently on two days, and reproducibility is what this endpoint has to offer.

TypeSubjectHouses (weight)
marriagemarriage or committed partnership7 (1.0), 5 (0.4), 1 (0.3)
separationseparation or divorce7 (1.0), 8 (0.5), 12 (0.3)
child-bornbirth of a child5 (1.0), 4 (0.4), 11 (0.2)
relocationmove of home4 (1.0), 3 (0.4)
emigrationemigration or long stay abroad9 (1.0), 4 (0.6), 3 (0.3)
career-changechange of career or standing10 (1.0), 6 (0.5), 2 (0.3)
job-lossloss of work6 (1.0), 10 (0.6), 12 (0.3)
educationstart of a course of study9 (1.0), 3 (0.5)
illnessillness6 (1.0), 12 (0.6), 8 (0.3)
surgerysurgery8 (1.0), 6 (0.8), 12 (0.4)
accidentaccident or injury6 (0.8), 8 (0.8), 1 (0.6)
bereavementdeath of someone close8 (1.0), 4 (0.4), 12 (0.3)
financial-gainwindfall or substantial gain2 (1.0), 11 (0.5), 8 (0.4)
financial-losssubstantial financial loss2 (1.0), 8 (0.8), 12 (0.4)
public-recognitionpublic recognition10 (1.0), 11 (0.6), 1 (0.3)
otherunclassified—

other scores nothing in house-placement and everything in the angular rules, which is the right behaviour for an event you can date but do not want to classify.

The response ​

json
{
  "data": {
    "statedDateTime": "1978-03-22T14:00:00Z",
    "candidates": [
      {
        "dateTime": "1978-03-22T13:56:00Z",
        "localDateTime": "1978-03-22T14:56",
        "time": "14:56",
        "offsetMinutes": -4,
        "score": 0.081,
        "logScore": 21.4362,
        "ascendant": 132.4188,
        "midheaven": 41.0072,
        "rules": [
          {
            "rule": "transit-to-angle",
            "contribution": 2.41,
            "evidence": "transiting saturn conjunction midheaven, orb 0.21° — married in Utrecht (2003-06-14)"
          },
          {
            "rule": "house-placement",
            "contribution": 1.05,
            "evidence": "transiting jupiter in house 7, which marriage or committed partnership activates — married in Utrecht (2003-06-14)"
          },
          {
            "rule": "stated-time",
            "contribution": -0.0099,
            "evidence": "4 min before the stated time (σ 45 min)"
          }
        ]
      }
    ],
    "discrimination": {
      "entropy": 0.62,
      "effectiveCandidates": 31.4,
      "verdict": "moderate",
      "message": "The evidence narrows 241 candidates to about 31. The evidence favours part of the window, but several candidates remain live. Read the per-rule contributions before preferring one."
    },
    "method": {
      "rules": [
        { "rule": "transit-to-angle", "weight": 3, "available": true },
        { "rule": "house-placement", "weight": 1.5, "available": true },
        { "rule": "solar-arc-to-angle", "weight": 2, "available": true },
        { "rule": "progressed-moon", "weight": 1, "available": true },
        { "rule": "stated-time", "weight": 1, "available": true }
      ],
      "resolutionMinutes": 1,
      "window": { "start": "1978-03-22T12:00:00Z", "end": "1978-03-22T16:00:00Z" },
      "candidates": 241,
      "events": 6,
      "houseSystem": "placidus",
      "orbDegrees": 1,
      "sigmaMinutes": 45,
      "transitingPoints": ["mars", "jupiter", "saturn", "uranus", "neptune", "pluto", "chiron"],
      "requestCost": 16
    }
  }
}

Reading score ​

score is a candidate's share of the total weight over every candidate in the window, not only the ones returned. The shares of all of them sum to 1.

It is a relative weight inside this one ranking. It is not a probability that this is the birth time, and it cannot be compared between two responses: logScore, which it is derived from, depends on how many events you supplied and which rules you turned on.

Reading discrimination ​

This is the part that keeps the endpoint honest, and it is worth putting in front of whoever reads the result.

entropy is the Shannon entropy of the ranking's weights divided by the entropy of a flat distribution over the same candidates. It runs from 0 to 1. effectiveCandidates is the same number expressed as a count: how many candidates the evidence effectively leaves standing.

verdictentropyWhat it means
none≥ 0.99Nothing was separated. The order is arbitrary; treat the list as unsorted
weak≥ 0.95Barely a narrowing. Indicative at best
moderate≥ 0.85Part of the window is favoured, several candidates remain live
strong< 0.85A narrow band, well supported under the rules you chose

Even strong is a statement about the shape of the ranking, not about the truth of the top entry. message is written to be shown as it is.

method ​

Always present, and not decoration: without knowing which rules ran, at what weight, over which window and at what resolution, an outcome cannot be reproduced — and an outcome that cannot be reproduced cannot be used in a consultation. Keep it with the result.

What it costs ​

This is the most expensive route on the API, and it is priced to say so:

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

An everyday question — ±2 hours at one minute, 8 events — counts as 18 requests. The largest possible one counts as 55. A request that fails counts as nothing. What was actually charged comes back in method.requestCost.

The answer is synchronous; there is no job to poll. The search itself is quick — the ephemeris is consulted a few dozen times in total, and the candidates cost nothing but arithmetic after that — so even the largest question answers in well under a second of calculation.

How to use it in practice ​

  1. Start wide and coarse if the time is genuinely unknown. A whole day at 4 minutes (361 candidates) finds the region. Then run ±30 minutes at 1 minute inside it.
  2. Six to ten events beats twenty. Events you can date confidently and classify honestly are worth more than a long list of approximations. A weight below 1 is the right way to include one you are unsure of, rather than leaving it out.
  3. Do not classify an event from the chart. If you pick type because the chart suggested it, the test is circular and the ranking tells you what you already assumed.
  4. Read the evidence before the score. The list exists so you can disagree with it.
  5. Open the top candidates as charts. /api/calc/natal at each candidate's dateTime. The judgement is yours; this endpoint narrows the field it is made in.

What it deliberately does not do ​

  • It does not return one time. Not with a flag, not with a parameter.
  • It does not interpret your event descriptions. A fixed taxonomy, so the same request gives the same answer next month.
  • It does not search an unknown date. The date is fixed; only the time is searched. An unknown date multiplies the search space by hundreds and is a different problem.
  • It does not explain its own winner with a language model. The rules are arithmetic and tables; a model asked to say why candidate 3 won would invent a story to fit a number.

AstroAPI Documentation