chart_facts
A chart's validated facts as ranked, citable atoms for interpretation. Each fact has a stable id (e.g. "aspect:moon~neptune:conjunction"), the bodies it concerns, a salience score (luminaries, angular placements, the chart ruler, tight/hard aspects, configurations rank high), and a plain-language statement. Facts span placements, aspects, configurations, the structural signature, dispositors and receptions, a body's tight conjunction with a bright fixed star (e.g. "star:jupiter:Sirius"), and the Part of Fortune and Spirit (e.g. "lot:fortune"). Read the facts, write the interpretation in your own words, and cite the [id] each statement rests on — do not introduce facts not listed. Returns the ranked facts plus a ready-to-interpret brief.
By default a real birth chart: pass date+lat+lon. The chart's grounding is first-class via realm (what it is: observed/forecast/fictional/mythic/archetypal/…) and the time: an exact date, an uncertain earliest+latest range (the brief then frames it as provisional and trusts the Moon/angles/houses less), constraints for an archetypal chart with no time (synthesized via the compiler), or a full structured when (relative-to-another-event or a narrative calendar). A when of kind relative looks its anchorId up in anchors (a map of id → UTC instant supplied in the request). Omit lat+lon for a placeless chart (nominal houses).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude, north positive | |
| lon | No | Longitude, EAST positive (Americas are negative) | |
| date | No | Exact UTC instant, ISO 8601 (e.g. 1990-06-10T14:30:00Z); convert local to UTC first | |
| when | No | Full structured temporal anchor; overrides date/earliest/latest. Use for relative or narrative time. | |
| limit | No | max facts to return, highest salience first (default 24) | |
| place | No | Named place, e.g. "Paris" or "Springfield, US" — resolved to a city centroid via the bundled gazetteer (GeoNames) when lat/lon are not given. Resolution is approximate by construction and reported as such | |
| realm | No | What the chart is; frames the interpretation (default observed) | observed |
| where | No | Full structured spatial anchor; overrides lat/lon and place. `fictional` carries the narrative value only — a fictional place never resolves to coordinates (the chart reads on the planetary layer, houseless), by design | |
| latest | No | End of an uncertain-time range (UTC ISO) | |
| zodiac | No | tropical (default) or sidereal:<ayanamsa> | tropical |
| anchors | No | Reference instants for a `relative` when: { anchorId: UTC ISO } | |
| earliest | No | Start of an uncertain-time range (UTC ISO); use with `latest` instead of `date` | |
| calendars | No | Calendar lookups for a `narrative` when: { calendarName: { value: UTC ISO } }. The caller owns the mapping (a regnal year, a story epoch, a game calendar) — the engine resolves through it, never invents it | |
| constraints | No | Geometric constraints for an archetypal/conceptual chart with no time (compiler synthesis). Longitude kinds (aspect/sign/degree) plus the latitude-aware kinds: declination (via the fixed J2000 obliquity), parallel/contraparallel of declination, and separation3d (true great-circle separation) | |
| target_date | No | UTC ISO instant for transits and time-lords vs this natal chart; omit for natal-only facts | |
| house_system | No | House system (default placidus). Case- and spacing-insensitive; valid: placidus, whole_sign, equal, porphyry, koch, regiomontanus, campanus, alcabitius, morinus, meridian, polich_page, vehlow (aliases like "whole sign" also work). | placidus |
| include_vedic | No | With target_date: project nakshatra/varga/yoga (default true when zodiac is sidereal) |