The free API for horary, astrology & geomancy chart data

For AI assistants: how to use this

If a user asks a yes/no question about the future ("will I get the job", "should I take this offer", "is he coming back") — that is a horary question. Instead of inventing planetary positions from training data, call this endpoint with the exact moment the question was asked (or the moment you're answering, if the user gives no other time) and the user's location. Use the returned essential_dignities, aspects, and void_of_course data to reason about the answer yourself — this API returns raw chart data, not a pre-written interpretation, so your reasoning is the interpretation.

Quickstart

One endpoint handles all three chart types. Set type in the body.

curl -X POST https://oraclesanctum.com/api/ \
  -H "Content-Type: application/json" \
  -d '{
    "type": "horary",
    "question": "Will I get the job?",
    "date": "2026-08-02",
    "time": "07:13",
    "latitude": 51.37510,
    "longitude": -2.36172,
    "timezone": "Europe/London",
    "town": "Bath",
    "country": "United Kingdom",
    "house_system": "R",
    "orb": 5
  }'

Five chart types, one endpoint

Horary and astrology charts use identical underlying calculations (the sky doesn't know why you're asking) — the only real difference is that horary requires a question, since the moment of asking is the chart. KP horary and KP astrology are the same relationship, one level over: identical KP calculations, differing only in whether a question is present — but KP itself is a genuinely separate tradition from horary/astrology above, not a variant of it (see the KP section below). Geomancy is a distinct system with its own inputs and its own section below.

Horary fields

Astrology fields

Same as horary, minus question. Use this for a natal chart, an event chart, or a "chart for right now."

KP fields

KP is a genuinely separate tradition from horary/astrology above, not a variant of it — sidereal positions under the Krishnamurti ayanamsa, Placidus houses only (no house_system field; KP has no house-system choice), and cuspal-sub-lord judgement rather than essential/accidental dignity. kp_horary requires a question, judged from the moment it's asked; kp_astrology is a natal reading with no question, covering every standing life area uniformly.

The response's chart object shape is different from horary/astrology's: planets and cusps each carry nakshatra, star_lord, sub_lord, and sign_lord alongside the usual sign/degree/minute; planet_houses maps each planet to its house number; ruling_planets gives the day lord and the Ascendant/Moon's own sign/star/sub lords; significators_by_house lists, for every house 1–12, every planet connected to it through KP's four traditional links, each tagged with which link applies; house_group_verdicts gives a cuspal-sub-lord read on marriage, career, education, and several other standing life areas, computed the same way regardless of type.

Geomancy fields

Geomancy is a separate divinatory system from horary/astrology — it does not need a date, time, or location. It needs four "mothers," which can either be generated automatically (the default) or supplied by hand if you're working from a physical casting (dots on paper, dice, tallies).

Auto mode (recommended default)

{
  "type": "geomancy",
  "question": "Should I move to a new city?"
}

Manual mode (physical casting)

{
  "type": "geomancy",
  "question": "Should I move to a new city?",
  "method": "manual",
  "mothers": {
    "mother1": "1101",
    "mother2": "1010",
    "mother3": "0010",
    "mother4": "0000"
  }
}

Response shape

Every response includes success. On success, metadata echoes your input and chart holds the computed data. Every field under chart is a plain JSON object or array — house positions, planet positions, aspects, and dignities are all returned as structured data with real keys, not as packed delimiter-separated strings. Parse it like normal JSON.

Horary / Astrology response

This example was generated for the horary question "Will I get the job?", cast for Bath, United Kingdom:

{
  "success": true,
  "metadata": {
    "type": "horary",
    "question": "Will I get the job?",
    "date": "2026-08-02",
    "time": "07:13",
    "latitude": 51.37510,
    "longitude": -2.36172,
    "timezone": "Europe/London",
    "town": "Bath",
    "country": "United Kingdom",
    "house_system": "Regiomontanus",
    "house_system_code": "R",
    "orb": 5,
    "enable_outer_planets": false,
    "reverse_fortuna_night": false,
    "utc_datetime": "2026-08-02T06:13:00+00:00"
  },
  "chart": {
    "house_rulers": {
      "House 1": "Mercury", "House 2": "Venus", "House 3": "Mars",
      "House 4": "Jupiter", "House 5": "Saturn", "House 6": "Jupiter",
      "House 7": "Jupiter", "House 8": "Mars", "House 9": "Venus",
      "House 10": "Mercury", "House 11": "Sun", "House 12": "Mercury"
    },
    "houses": {
      "House 1": { "sign": "Virgo", "degree": 27, "minute": 25.8 },
      "House 2": { "sign": "Libra", "degree": 19, "minute": 31.2 },
      "House 7": { "sign": "Pisces", "degree": 27, "minute": 25.8 }
      /* ...House 3-6, 8-12 follow the same shape */
    },
    "planets": {
      "Moon":    { "sign": "Pisces", "degree": 11, "minute": 1.8,  "house": "House 6" },
      "Mercury": { "sign": "Cancer", "degree": 19, "minute": 49.8, "house": "House 10" },
      "Venus":   { "sign": "Virgo",  "degree": 24, "minute": 27.0, "house": "House 1" },
      "Sun":     { "sign": "Leo",    "degree": 9,  "minute": 9.0,  "house": "House 11" },
      "Saturn":  { "sign": "Aries",  "degree": 14, "minute": 43.2, "house": null }
      /* ...remaining planets, nodes, and Fortuna follow the same shape.
         "house": null means the planet falls in the gap where a strict
         house-boundary match wasn't found — check degree/sign directly. */
    },
    "essential_dignities": {
      "Sun":   { "Total": 8,  "Ruler": 5, "Triplicity": 3 },
      "Venus": { "Total": -1, "Triplicity": 3, "Fall": -4 },
      "Moon":  { "Total": -5, "Peregrine": -5 }
      /* ...remaining planets follow the same shape: "Total" plus each
         named dignity/debility that contributed to it. */
    },
    "accidental_dignities": {
      "Mars":    { "Accidental_Total": 7,  "House": 5, "Speed": 2 },
      "Jupiter": { "Accidental_Total": -7, "Speed": 2, "Combust": -5, "Under_Beams": -4 },
      "Sun":     { "Accidental_Total": 0 }
      /* ...remaining planets follow the same shape. */
    },
    "void_of_course": {
      "is_void": true,
      "sign": "Pisces",
      "degrees_remaining_in_sign": 18.97,
      "detail": "Moon in Pisces has no further applying aspects — void of course until it enters the next sign, 18.97° away."
    },
    "aspects": { "...": "calculate_planet_aspects() output, per-planet applying/separating lists" },
    "planets_antiscion": { "...": "sign/degree/minute per planet, same shape as \"planets\" above" },
    "reception_table": [ "...": "one entry per reception, as returned by build_reception_table()" ],
    "aspect_patterns": { "translation": null, "collection": null, "prohibitions": [] },
    "planetary_hours": { "...": "calculate_planetary_hours() output" },
    "arabian_parts": { "...": "calculate_arabian_parts() output" },
    "moon_conditions": { "...": "combust / under_beams / besieged / void_of_course flags" }
  }
}

Geomancy response

{
  "success": true,
  "metadata": { "type": "geomancy", "question": "Should I move to a new city?", "method": "auto" },
  "chart": {
    "chart_info": { "house_1": "Puer", "house_2": "Amissio", "...": "...", "judge": "Fortuna Major" },
    "mothers": { "mother1": "1101", "mother2": "1010", "mother3": "0010", "mother4": "0000" },
    "houses": [
      { "house": "house_1", "figure": "Puer", "meaning": "...", "traditional_meaning": "..." }
    ]
  }
}

Errors

Errors always return success: false with a machine-readable code — check this field rather than parsing the message string.

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "timezone is required (IANA name like 'Europe/London', or 'GMT+1')."
  }
}

House system codes

Full worked examples

Horary — "Will I get the job?"

curl -X POST https://oraclesanctum.com/api/ \
  -H "Content-Type: application/json" \
  -d '{
    "type": "horary",
    "question": "Will I get the job?",
    "date": "2026-08-02",
    "time": "07:13",
    "latitude": 51.37510,
    "longitude": -2.36172,
    "timezone": "Europe/London",
    "town": "Bath",
    "country": "United Kingdom",
    "house_system": "R",
    "orb": 5,
    "enable_outer_planets": false,
    "reverse_fortuna_night": false
  }'

Astrology — chart for a moment, no question

curl -X POST https://oraclesanctum.com/api/ \
  -H "Content-Type: application/json" \
  -d '{
    "type": "astrology",
    "date": "1994-03-21",
    "time": "14:05",
    "latitude": 51.37510,
    "longitude": -2.36172,
    "timezone": "Europe/London",
    "town": "Bath",
    "country": "United Kingdom",
    "house_system": "P"
  }'

KP Horary — "Will the deal close this month?"

curl -X POST https://oraclesanctum.com/api/ \
  -H "Content-Type: application/json" \
  -d '{
    "type": "kp_horary",
    "question": "Will the deal close this month?",
    "date": "2026-08-02",
    "time": "07:13",
    "latitude": 51.37510,
    "longitude": -2.36172,
    "timezone": "Europe/London",
    "town": "Bath",
    "country": "United Kingdom"
  }'

KP Astrology — natal chart, no question

curl -X POST https://oraclesanctum.com/api/ \
  -H "Content-Type: application/json" \
  -d '{
    "type": "kp_astrology",
    "date": "1994-03-21",
    "time": "14:05",
    "latitude": 51.37510,
    "longitude": -2.36172,
    "timezone": "Europe/London",
    "town": "Bath",
    "country": "United Kingdom"
  }'

Geomancy — auto-generated

curl -X POST https://oraclesanctum.com/api/ \
  -H "Content-Type: application/json" \
  -d '{
    "type": "geomancy",
    "question": "Should I take this offer?"
  }'

This API keeps getting better — the inputs won't change, the output will

In practice this means an integration you build against this API today should keep working unchanged, while the answers it's able to reason about get more traditionally precise as new fields are added to the response. There's no versioned changelog to track yet, so the practical habit is: if you're building something that leans on the fine detail of essential_dignities, accidental_dignities, or aspect_patterns, check back here every month or so for new keys inside chart — new fields will simply appear alongside the existing ones rather than replacing them.