AI-Powered Horary Judgment

Ask a Question in Plain Language. Get an AI-Judged Horary Answer

POST a question to /horary/ask.

The API classifies it, runs the full traditional analysis, and returns a plain-language answer with a confidence band. Under 2 seconds end-to-end.

View Demo

<2s

Ask → Answer

AI-Powered

Classify + Summarize

Output Languages

High / Med / Low

Confidence Bands

Used by 2,800+ developers and astrologers

William Lilly + Bonatti methodology

Swiss Ephemeris precision

Premium Feature

Horary Astrology is a premium feature available starting from the Ultra plan.

You have to hand-code 1000+ years of judgment rules: radicality, void-of-course Moon, essential and accidental dignities, reception, perfection, translation and collection of light, prohibition, frustration
You need to parse free-text questions and route them to the right house and significator scheme. Marriage goes to the 7th, fertility to the 5th, litigation to the 7th, lost objects to the 2nd
You have to disambiguate "will I marry her" from "will we get back together." Same house, different sub-rules
You need a sane way to express uncertainty when the chart says "yes, but barely"
And you have to do all of this in five languages without inventing a translation pipeline

Ship horary with

POST a plain-language question to /horary/ask. The AI classifier picks the category and subcategory from 10 few-shot examples per language
The judgment engine runs the full traditional rule set: radicality flags, VOC handling, dignities, perfection, translation/collection of light, prohibition, frustration
The AI summarizer converts the technical verdict into a plain answer in en, ru, de, fr, or es, with a confidence_band of high, medium, or low
Marriage vs. business partnership, marriage vs. reconciliation: the classifier handles the edge cases that break naive keyword routing
Redis caches classifications for 7 days, so repeat questions skip the LLM round trip

Production Metrics

Real numbers from the new /horary/ask pipeline

<2s

End-to-End (classify + judge + summarize)

en / ru / de / fr / es

Summary Languages

7-day TTL

Classifier Cache (Redis)

confidence_band

Returned Per Answer

What Ships in the New Horary Pipeline

AI classification, AI summary, typed flags, multilingual output

/horary/ask Endpoint

POST a plain-language question. Get classification, judgment, and a summary back in one response.

AI Question Classifier

10 few-shot examples per language. Handles marriage vs. business partnership and marriage vs. reconciliation.

AI Summarizer

Turns the technical Judgment object into a 2–4 sentence plain answer. No prescriptive verbs.

Confidence Band

Every answer returns high / medium / low. Drive UI hedging directly from the field.

Typed Radicality Flags

RadicalityChecker emits a structured flag list. Render in the UI without parsing free text.

VOC Exception Signs

Lilly exceptions (Taurus, Cancer, Sagittarius, Pisces) mitigate the VOC verdict instead of vetoing it.

Bonatti VOC Severity

Mild vs. standard severity exposed as a flag for Bonatti-strict audiences.

Turned-Chart Analysis

Optional subject_role parameter routes the question through derived houses via turn_house_cusps.

Marriage Subcategories

Marriage, marriage.reconciliation, and business_partnership get separate judgment lenses.

Multilingual Summaries

en, ru, de, fr, es. Same pipeline, different output language.

Redis Classifier Cache

sha256 question key with a 7-day TTL. Repeat questions skip the LLM round trip.

Perfection Conflict Resolution

When frustration is active, the summary suppresses translation_of_light callouts to avoid contradictory messages.

Extended Lunar Sequence

45° lookahead tracking every Moon aspect for full timing context.

Secondary Perfection

Translation of Light, Collection of Light, Prohibition, and Frustration analyzed on every chart.

Explicit Perfection Flags

Opt in with include_perfection_analysis on /horary/aspects and get a typed perfection_type: direct, translation_of_light, collection_of_light, or none, plus a perfection_order ranking. No more inferring the verdict from raw aspect data.

Ranking Answers for Comparative Questions

A multi-party question like "who needs me more, my husband or my lover" now returns answer_type: "ranking" with a real comparison object, instead of a forced yes/no on the wrong question.

7-Language Judgment Reasoning

judgment.reasoning, key_factors, and each significator's reason now render in en, ru, de, fr, es, it, and pt, not just English.

Essential & Accidental Dignities

Domicile, exaltation, triplicity, terms, faces + house, aspect, retrograde, combustion.

Regiomontanus Houses

Traditional horary house system as the default, not the Placidus most general-purpose APIs ship.

Visual Chart Engine (/horary/figure + /horary/render)

figure returns the wheel as structured data: planet positions, house cusps, significators, aspects. render returns the same chart already drawn as SVG, PNG, JPG, WEBP, or PDF.

The Speculum

The classical horary technique table printed beside the figure: dignities, considerations, and antiscia in one place, on by default. Most horary APIs skip it.

Five-Column Dignity Table

Every significator's full essential-dignity row: domicile ruler, exaltation ruler, triplicity ruler, term ruler, and face ruler, not just the strongest rung.

Turned Figures for Third Parties

Ask about a child, parent, or spouse and the wheel turns with subject_role. Radix angles stay put; each significator carries both the radix and derived house number.

Carried Light, Drawn Differently

Translation of light gets its own line style on the rendered figure, distinct from applying and separating aspects, so a carried connection is never mistaken for a direct one.

Lost-Item Location Questions

Ask where a missing object is and the classifier routes it to a dedicated location analysis instead of a generic yes/no on the missing_item category.

Significators: Rule and Placement Together

Every significator now reports the house it rules and the house it physically stands in, closing a gap where only the ruled house showed up.

16-Language Figure Captions

Chart labels render in ar, de, en, es, fr, hi, it, ja, ko, nl, pl, pt, ru, tr, uk, and zh, wider coverage than the 5-language text summaries.

AI Horary API: How /horary/ask Turns a Plain Question into a Judged Answer

The new flagship endpoint, explained

Horary astrology answers a specific question by casting a chart for the moment the question is asked, then judging the chart against a thousand years of accumulated rules. The hard part for developers has always been the rules themselves: radicality, void-of-course Moon, dignities, reception, the four ways a matter perfects or fails to perfect. The new /horary/ask endpoint hides all of that behind a single POST. You send a question in plain English (or Russian, German, French, Spanish). An AI classifier picks the right category and subcategory using ten few-shot examples per language. The judgment engine runs the full traditional analysis with typed radicality flags and Bonatti-graded void-of-course severity. An AI summarizer turns the technical verdict into a plain answer with a confidence_band of high, medium, or low. The whole pipeline returns in under 2 seconds. Classifier results are cached in Redis for 7 days under a sha256 question key, so repeat questions skip the LLM round trip entirely.

How does the /horary/ask endpoint work, step by step?

Four stages, one HTTP call.

Stage 1: you POST a question string and the querent's location + timestamp.

Stage 2: the AI classifier reads the question and assigns it to one of the traditional categories (marriage, business partnership, fertility, property, litigation, health, lost objects, employment, travel, and the rest), plus a subcategory when relevant (for example marriage.reconciliation for estranged-spouse questions).

Stage 3: the judgment engine casts the chart, identifies significators, runs radicality checks, evaluates dignities, looks for perfection, and emits a typed Judgment object with radicality_flags, voc_treatment, perfection details, and a confidence_band.

Stage 4: the AI summarizer takes the Judgment object and writes a plain-language answer in the requested output language.

The summarizer prompt forbids prescriptive verbs (no "you must do X"), elevates radicality flags as mandatory caveats, and suppresses translation_of_light callouts when frustration is also present in the same chart.

Four stages, one POST, under 2 seconds end-to-end

1 min read

How accurate is the AI classifier and what does it actually do?

The classifier reads the raw question and decides which house and significator scheme the judgment engine should use.

It runs on 10 few-shot examples per supported language (en, ru, de, fr, es) and handles the edge cases that break naive keyword routing.

"Will my business partner buy me out?" goes to business partnership (7th house, but different sub-rules from marriage).

"Will my husband and I get back together?" goes to marriage.reconciliation, not a fresh marriage question.

Same 7th house, different judgment lens.

"Will I get pregnant this year?" goes to fertility (5th house, with the Bonatti fruitful-sign overlay).

The classifier also returns alternatives with confidence scores, so you can show "we read this as a marriage question, was that right?" in your UI.

The result is cached in Redis under a sha256 of the normalized question with a 7-day TTL, so the second identical question costs zero LLM tokens.

10 few-shot examples per language, Redis-cached for 7 days

1 min read

What does confidence_band mean in the response?

Every Judgment object returns a confidence_band field with one of three values.

High means the chart is radical, significators are dignified or well-placed, perfection is clean, and no major radicality flags are active.

You can show the answer to the user without hedging.

Medium means the answer is supported but with caveats: perhaps a moderate VOC mitigation, a separating aspect that still completes, or a Translation of Light doing the work instead of direct perfection.

Low means the chart has serious radicality warnings, the Moon is void without an exception sign, or the judgment depends on contested factors like Bonatti-mild VOC severity.

Use the band to drive UI: high gets a confident headline, medium gets an explainer paragraph, low surfaces the radicality flags and suggests re-asking when the querent has more clarity.

Three bands: high (ship it), medium (caveat), low (re-ask)

1 min read

How does the API handle radicality and Void of Course Moon?

Radicality is the traditional check on whether a chart is fit to judge at all.

The RadicalityChecker emits a typed RadicalityFlag list, so you can render them in the UI without parsing free text.

The list covers early/late ascendant, Saturn in the 7th, Moon void of course, malefics afflicting significators, and the rest of the classical battery.

Void of Course Moon is the tricky one.

The naive rule says "nothing will come of the matter," but Lilly himself listed exception signs (Taurus, Cancer, Sagittarius, Pisces) where a VOC Moon is mitigated, not negated.

The MoonCalculator honors this and emits voc_exception_sign + voc_effective_strength so the judgment engine can downgrade rather than veto.

The RadicalityChecker description cites the exception sign by name.

Bonatti's severity layer (mild vs.

standard) is also exposed as a flag, so apps targeting a Bonatti-strict audience can surface it explicitly.

Typed radicality flags, Lilly exception signs, Bonatti severity grading

1 min read

What are turned charts and when do you need subject_role?

A turned chart re-roots the houses so you can ask about someone other than the querent.

The classic case: the querent is asking about their child's marriage.

The querent's 5th house (children) becomes the radical 1st for the analysis, and every other house turns from there.

The child's 7th (their spouse) is the querent's 11th.

The /horary/ask endpoint accepts an optional subject_role parameter for this.

Set it to "child" and the engine uses the turn_house_cusps utility to derive the right cusps before significator selection.

The same mechanism handles "will my brother's lawsuit succeed" (3rd → 1st) or "will my partner's mother recover" (7th → 4th from radical = 10th).

If you leave subject_role unset, the chart is read radically for the querent.

Optional subject_role parameter for derived-house questions

1 min read

Why a multilingual summarizer matters for horary apps

Horary verdicts are dense.

A raw Judgment object lists significators, aspects, dignities, radicality flags, perfection type, and timing, none of which a paying user wants to parse.

The summarizer takes that object and writes a 2 to 4 sentence plain answer in the user's language.

Five languages ship today: English, Russian, German, French, and Spanish.

Each has its own prompt template with language-specific phrasing rules.

The prompt forbids prescriptive verbs in every language.

The API tells you what the chart says, not what you should do.

It also elevates radicality flags into the visible answer when confidence_band is medium or low, so users see the caveats before the verdict.

When a chart has both translation_of_light and frustration active, the prompt suppresses the translation callout because frustration overrides it, a small detail that prevents contradictory messages in the summary.

5 languages, prompt-enforced caveats, no prescriptive verbs

1 min read

How does the new visual chart engine work?

A horary API that returns text alone can't build the interfaces astrologers actually want: a drawn wheel with role tags, dignity tables, and applying-versus-separating shown at a glance, not buried in a JSON blob.

Two endpoints close that gap.

POST /horary/figure returns the chart as structured data: every planet with degree and minute, speed, retrogradation, and solar condition; every house cusp with its span and interceptions; every significator with the house it rules, the house it stands in, and its full dignity row; every aspect, applying and separating, each with its own orb.

Draw your own wheel from that model, in your own UI, at your own resolution.

POST /horary/render skips the drawing step for you: same builder, same data, but the output is an already-rendered SVG (or PNG, JPG, WEBP, PDF) with significator role tags on the glyphs, applying and separating aspects told apart by weight and dash rather than a legend, and the house system named on the face.

Both endpoints support subject_role, so a turned chart for a child or parent draws correctly, with radix angles staying put and derived house numbers riding beside the significators.

Two new endpoints, one shared builder: figure model or rendered image

1 min read

What is the speculum, and what changed in significator reporting?

Lilly's own charts were never just a wheel; beside every figure sat a speculum, the technical table where the actual judgment happens: essential dignities, aspect status, and reception for each significator, side by side.

The API computes this by default on both /horary/figure and /horary/render (toggle it off with include_speculum: false if you only want the wheel).

The dignity rows in the speculum are the full five-column breakdown: domicile ruler, exaltation ruler, triplicity ruler, term ruler, and face ruler, per planet, not a simplified "strong or weak" label.

Significator reporting also closed a real gap this month: every significator now returns both the house it rules and the house it physically stands in, so an app can render "Mars, lord of the 7th, is himself sitting in the 10th" without a second lookup.

Two more pieces shipped alongside this: carried light (translation of light) now gets its own visual treatment on the drawn figure, distinct from applying and separating aspects, and lost-item questions ("where is my ring") now route to a dedicated location analysis instead of a generic yes/no on the missing_item category.

Five-column dignity rows, rule-and-placement reporting, dedicated lost-item routing

1 min read

Use Cases

Astrology Apps

Wire /horary/ask to a question box. User types, app returns a confidence-banded answer in their language. Charge $5–15 per reading.

Relationship Platforms

Marriage, reconciliation, and business-partnership classification handle the cases that confuse simple keyword routers.

Career Platforms

Employment, litigation, and property categories cover the high-stakes decisions users actually pay to ask about.

Multilingual Markets

Ship the same endpoint to en, ru, de, fr, and es audiences without building a translation pipeline.

Report & PDF Generators

Render the figure straight to PDF or high-res PNG for client reports and printed readings, no separate charting library needed.

Technical Specifications

Flagship Endpoint	POST /horary/ask: question in, judged answer out
End-to-End Latency	<2s for classify + judge + summarize
Classifier Few-Shot Examples	10 per supported language
Classifier Languages	en, ru, de, fr, es
Summarizer Languages	en, ru, de, fr, es
Classifier Cache	Redis, sha256 question key, 7-day TTL
Confidence Band	Enum: high \| medium \| low
Radicality Flags	Typed RadicalityFlag list (RadicalityChecker)
VOC Exception Signs	Lilly: Taurus, Cancer, Sagittarius, Pisces (mitigated)
VOC Severity	Bonatti mild vs. standard, exposed as flag
VOC Fields	voc_exception_sign, voc_effective_strength, voc_treatment
Marriage Subcategories	marriage, marriage.reconciliation, business_partnership
Turned Charts	Optional subject_role param + turn_house_cusps utility
Summarizer Rules	No prescriptive verbs; radicality flags elevated as caveats
Perfection Suppression	translation_of_light hidden when frustration is also active
Question Categories	14 traditional categories (Lilly/Bonatti)
Ephemeris Source	Swiss Ephemeris
House System	Regiomontanus (traditional horary default)
Lunar Sequence	Extended 45° lookahead with intervening analysis
Secondary Perfection	Translation, Collection, Prohibition, Frustration
Output Format	JSON: classification + judgment + summary
Chart Model Endpoint	POST /horary/figure: points, cusps, significators, aspects, moon state
Chart Rendering Endpoint	POST /horary/render: svg, png, jpg, webp, pdf
Speculum	Five-column dignity table + considerations + antiscia, on by default
Dignity Table Columns	Domicile ruler, exaltation ruler, triplicity ruler, term ruler, face ruler
Figure Caption Languages	16: ar, de, en, es, fr, hi, it, ja, ko, nl, pl, pt, ru, tr, uk, zh
Turned Figures	subject_role turns the wheel; radix angles stay, both house numbers shown
Lost-Item Questions	Dedicated location analysis for the missing_item category
Significator Reporting	House ruled AND house occupied, reported per significator

Why /horary/ask Beats Hand-Wired Horary Logic

Feature	Astrology API	Others
Plain-Language Question Input	POST a string, done	You parse and route yourself
Question Classification	AI classifier, 10 few-shot per language	Manual keyword rules
Marriage vs. Business Partnership	Disambiguated automatically	Same 7th house, wrong rules
Marriage vs. Reconciliation	marriage.reconciliation subcategory	Not modeled
Output Summary	AI summarizer in 5 languages	Raw JSON, you write the copy
Confidence Reporting	confidence_band: high / medium / low	Boolean yes/no only
Radicality Flags	Typed flag list	Free-text or absent
VOC Exception Signs	Lilly exceptions mitigate, don't veto	Hard veto
Bonatti VOC Severity	Mild vs. standard, exposed	Not supported
Turned Charts	subject_role param + turn_house_cusps	You compute manually
Classifier Caching	Redis, sha256 key, 7d TTL	None; pay per call
End-to-End Latency	<2s including LLM calls	3–8s or sync-only
Multilingual Summaries	en, ru, de, fr, es	English only
Prescriptive-Verb Guard	Prompt forbids "you must"	No guard
Perfection Conflict Handling	Frustration suppresses translation callout	Both shown, user confused
Lunar Sequence	45° extended lookahead	Next aspect only
Secondary Perfection	All 4 types analyzed	Direct perfection only
House System	Regiomontanus default	Placidus default (wrong for horary)
Price Per Reading	$0.02 via API	$0.10–0.50
Visual Chart Output	SVG/PNG/JPG/WEBP/PDF from the same figure model	Text or JSON only, draw it yourself
Speculum	Five-column dignity table, on by default	Not offered

Pairs Well With

Cazimi & Combust API

Combust significators are a make-or-break factor in horary judgment. Get the exact orbs and cazimi status.

Electional Astrology API

Once horary says yes, electional picks the optimal moment to act.

Traditional Astrology API

Full dignity tables, sect, antiscia, and the rest of the classical toolkit.

Fertility Astrology API

5th-house specialist for pregnancy and conception questions, with Bonatti fruitful-sign overlay.

Arabic Parts API

97+ Arabic parts including the lots that horary judgment depends on.

Natal Chart API

Generate the querent's natal chart for context alongside the horary verdict.

References & Standards

Swiss Ephemeris (DE431-based) — astronomical calculations source
NASA JPL Planetary Ephemerides — underlying ephemeris dataset
International Astronomical Union (IAU) — body designation and nomenclature standards
IANA Time Zone Database — timezone & DST resolution

Premium Feature

Horary Astrology is a premium feature available starting from the Ultra plan.

Horary Astrology: 2 credits per request

See how many requests you get with each plan

Per-endpoint credit cost

Horary AI Ask (/horary/ask)10 credits per request
Horary Astrology2 credits per request

Simple, Transparent Pricing

Start free, scale as you grow. No hidden fees, no surprises.

Ultra

$37/month

For professional astrology applications

Credit math ↓

All premium endpoints
23 house systems
Advanced AI interpretations
Priority support

High Volume Plans

For enterprise-scale applications

Business

$99/month

For high-volume applications

Credit math ↓

ALL endpoints
White-label ready
Custom AI fine-tuning
Phone support

UNLIMITED

Enterprise

$399+per month

Unlimited requests with dedicated infrastructure

Dedicated server infrastructure
Sub-300ms guaranteed
24/7 dedicated support
99.99% uptime SLA

All plans include comprehensive documentation and SDKs

Questions? Talk to our team

Horary API FAQ

What is the speculum and does your API compute it?

Round Out the Traditional Stack

Horary judgment depends on planetary condition, timing, and the wider classical toolkit. Add

Ship a Question Box.

POST a question. Get back a classified, judged, summarized answer with a confidence band, in under 2 seconds, in 5 languages. No rule-engine wiring on your side.

Start Free Now

30-day money-back guarantee

Free migration assistance

No setup fees

Ask a Question in Plain Language. Get an AI-Judged Horary Answer

Building Horary by Hand Is a 1000-Year Rabbit Hole

One Endpoint. The API Handles the Rest.

Production Metrics

What Ships in the New Horary Pipeline

/horary/ask Endpoint

AI Question Classifier

AI Summarizer

Confidence Band

Typed Radicality Flags

VOC Exception Signs

Bonatti VOC Severity

Turned-Chart Analysis

Marriage Subcategories

Multilingual Summaries

Redis Classifier Cache

Perfection Conflict Resolution

Extended Lunar Sequence

Secondary Perfection

Explicit Perfection Flags

Ranking Answers for Comparative Questions

7-Language Judgment Reasoning

Essential & Accidental Dignities

Regiomontanus Houses

Visual Chart Engine (/horary/figure + /horary/render)

The Speculum

Five-Column Dignity Table

Turned Figures for Third Parties

Carried Light, Drawn Differently

Lost-Item Location Questions

Significators: Rule and Placement Together

16-Language Figure Captions

AI Horary API: How /horary/ask Turns a Plain Question into a Judged Answer

How does the /horary/ask endpoint work, step by step?

How accurate is the AI classifier and what does it actually do?

What does confidence_band mean in the response?

How does the API handle radicality and Void of Course Moon?

What are turned charts and when do you need subject_role?

Why a multilingual summarizer matters for horary apps

How does the new visual chart engine work?

What is the speculum, and what changed in significator reporting?

Use Cases

Astrology Apps

Relationship Platforms

Career Platforms

Multilingual Markets

Report & PDF Generators

Technical Specifications

Why /horary/ask Beats Hand-Wired Horary Logic

Pairs Well With

Cazimi & Combust API

Electional Astrology API

Traditional Astrology API

Fertility Astrology API

Arabic Parts API

Natal Chart API

References & Standards

Horary Astrology: 2 credits per request

Simple, Transparent Pricing

Ultra

Business

Enterprise

Horary API FAQ

How does /horary/ask work?

What's the difference between /horary/ask and /horary/chart?

How accurate is the AI classifier?

What does confidence_band mean in the response?

Can I get answers in languages other than English?

How does the API handle Void of Course Moon in Lilly exception signs?

What is a turned chart and when do I need subject_role?

Does the API consider Bonatti's VOC severity?

Is the question cached?

How does the summarizer avoid sounding like a fortune teller?

What happens when both translation_of_light and frustration are active?

What are the 14 horary question categories?

How fast is end-to-end latency?

Can I use the API without the AI layer?

How much does the horary astrology API cost?

Do you support traditional horary house systems?

What is radicality and what flags does the API emit?