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
  }'

Three 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. 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."

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"
  }'

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.