---
title: "Calculate Primary Directions"
method: POST
path: "/predictive/primary-directions"
tags: ["predictive"]
---

# Calculate Primary Directions

`POST /predictive/primary-directions`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/predictive/primary-directions`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-OpenEphemeris-API-Key`
  - API key in header `X-API-Key`
  - API key in header `X-Service-Key`

Placidus semi-arc primary directions. Promissors are the Sun through Saturn and their Ptolemaic aspects; significators default to the Ascendant, Midheaven, Sun, Moon and Part of Fortune. Two methods: `placidus_mundane` (the promissor's body, mundane aspects by semi-arc proportion) and `placidus_zodiacal` (the promissor's aspect degree on the ecliptic, without latitude). Every event names the method that produced it and gives the arc, the age under the Ptolemy and Naibod keys, and the date each key implies. Uses the true obliquity of the birth date. Placidus semi-arcs do not exist at or inside the polar circle; such births return 422.

## Request body

- PrimaryDirectionsRequest
  - `format` 'json' | 'llm': Response format: json | llm.
  - `fortune_formula` 'sect' | 'ptolemy': How the Part of Fortune is computed. `sect` (default): Asc + Moon − Sun by day, Asc + Sun − Moon by night, the usual Hellenistic and medieval reversal. `ptolemy`: Asc + Moon − Sun for every chart, with no night reversal, as Ptolemy gave it. Affects only the Part of Fortune significator; `planets[]` echoes the formula on the Fortune entry when this field is sent. The mundane lot of Placidus (from the Moon's declination) is not offered.
  - `include_aspects` number[]: Aspect angles in degrees (0–180). The conjunction is always included. Every aspect other than 0 and 180 is returned on both sides, sinister and dexter.
  - `include_converse` boolean: Also return converse directions in Ptolemy's sense: the significator is carried by primary motion to the promissor (or its aspect). For an angle, the degree on that angle is carried. Not a backward-turning sky.
  - `max_age_years` number, double: Drop events whose Naibod age exceeds this.
  - `methods` string[]: `placidus_mundane`: the promissor's body (with latitude) is carried to the significator's Placidus mundane position; aspects are mundane (a square is three Placidus houses). `placidus_zodiacal`: the promissor's aspect degree on the ecliptic, without latitude, is carried to the significator's mundane position (significators also without latitude).
  - `significators` string[]: Points that receive directions. `fortune` is the Part of Fortune by sect (day: Asc + Moon − Sun; night: Asc + Sun − Moon), as an ecliptic point. Add `mercury`…`saturn` to direct to the other planets. A body also receives directions of its own aspects (the Sun to the square of its natal place), never of its own body.
  - `subject` SubjectRequest, required: Subject identity and birth data used to compute a chart.
    - `birth_datetime` DateTimeInput, required: Date/time input in ISO-8601, component, or Julian day form. A value that states a clock time must also state its zone, either as a suffix on the string or via the `timezone` field below.
      - `components` object: Date/time components (year, month, day, and optionally hour, minute, second). If hour/minute are present, pass `timezone` alongside them; without it the request is rejected with 400 ambiguous_datetime. Omit the clock entirely and the date resolves to 12:00 UTC.
      - `iso` string: ISO-8601 datetime (supported range 1550–2650 CE, JPL DE440). If it states a clock time it must carry its zone: either a 'Z'/±HH:MM suffix on the string ("1987-07-15T09:01:00-05:00"), or a `timezone` passed alongside it. A zone-less clock time is rejected with 400 ambiguous_datetime — it is not read as UTC. A date-only value ("1987-07-15") has no clock to be ambiguous about and resolves to 12:00 UTC.
      - `julian_day` number, double: Julian Day Number (always UTC-based, so it needs no zone)
      - `timezone` TimezoneInput: Timezone input using IANA names or UTC offsets.
        - `fold_preference` 'earlier' | 'later': Which occurrence to use when the naive local datetime falls in a fall-back fold (a repeated hour): 'earlier' (default — first occurrence) or 'later'. Only meaningful for naive datetimes; the response reports datetime_status=ambiguous_fold either way so the ambiguity can be surfaced to the user.
        - `iana_name` string: IANA timezone name
        - `time_standard` 'auto' | 'standard' | 'daylight': How to interpret a naive local datetime when this zone is applied. 'auto' (default): resolve through the historical-correction overlay where one covers the region/era, then IANA tzdata. 'standard': force the zone's standard (non-daylight) offset — for callers who KNOW the recorded time was standard time regardless of what tzdata believes. 'daylight': force standard+1h. Forcing either marks the resolution tz_confidence=client_override. Ignored when the datetime carries its own Z/±HH:MM suffix or when utc_offset is used.
        - `utc_offset` number: UTC offset in hours
    - `birth_location` BirthLocation, required: Location context for birth data: coordinates plus timezone.
      - `city` string: City name
      - `country` string: Country
      - `elevation` number: Elevation in meters. Accepted and echoed back unchanged; it does not affect planetary positions, which are computed geocentrically. Elevation changes results only where it is taken as the `elev` query parameter: /eclipse/solar/local (local circumstances) and /time/solar-event plus /ephemeris/agro/* (horizon rise/set times).
      - `latitude` CoordinateInput, required: Flexible coordinate input supporting multiple formats.
        - `components` object: Separate degree components with direction
        - `decimal` number: Decimal degrees (-90 to 90 for lat, -180 to 180 for lon)
        - `dms` string: Degrees, minutes, seconds string (e.g., '40°42'46"N')
      - `location_name` string: Birthplace display name (e.g. "Dallas, TX"). Never affects calculations — coordinates and timezone are the only location facts the engine reads. Echoed back verbatim where the response carries an echo block: as subject.location_name on chart routes that echo a subject (natal, draconic, progressed, synastry, natal-transits, overlay, natal/batch items, predictive transit-chart), inside search_summary on /electional/natal-angle-crossings, metadata on /acg/midpoints, and natal on /human-design/transit-chart. Omitted from the response when not sent.
      - `longitude` CoordinateInput, required: Flexible coordinate input supporting multiple formats.
        - `components` object: Separate degree components with direction
        - `decimal` number: Decimal degrees (-90 to 90 for lat, -180 to 180 for lon)
        - `dms` string: Degrees, minutes, seconds string (e.g., '40°42'46"N')
      - `region` string: State/region
      - `timezone` TimezoneInput, required: Timezone input using IANA names or UTC offsets.
        - `fold_preference` 'earlier' | 'later': Which occurrence to use when the naive local datetime falls in a fall-back fold (a repeated hour): 'earlier' (default — first occurrence) or 'later'. Only meaningful for naive datetimes; the response reports datetime_status=ambiguous_fold either way so the ambiguity can be surfaced to the user.
        - `iana_name` string: IANA timezone name
        - `time_standard` 'auto' | 'standard' | 'daylight': How to interpret a naive local datetime when this zone is applied. 'auto' (default): resolve through the historical-correction overlay where one covers the region/era, then IANA tzdata. 'standard': force the zone's standard (non-daylight) offset — for callers who KNOW the recorded time was standard time regardless of what tzdata believes. 'daylight': force standard+1h. Forcing either marks the resolution tz_confidence=client_override. Ignored when the datetime carries its own Z/±HH:MM suffix or when utc_offset is used.
        - `utc_offset` number: UTC offset in hours
    - `gender` string: Gender (optional)
    - `name` string, required: Subject name
    - `notes` string: Additional notes

## Response `200`

Successful Response

- PrimaryDirectionsResponse
  - `calculation_metadata` object: Optional calculation provenance metadata (timing, engine flags, ayanamsa, etc.). Free-form; present when the handler attaches it.
  - `directions` PrimaryDirectionEvent[]
    - `age_naibod` number, double: Age in years under Naibod's key, 0°59′08.33″ = 1 year.
    - `age_ptolemy` number, double: Age in years under Ptolemy's key, 1° = 1 year.
    - `arc` number, double: Arc of direction in degrees of right ascension.
    - `aspect_deg` number, double: Aspect in degrees; 0 is the conjunction.
    - `aspect_name` string: conjunction, sextile, square, trine, opposition, or `aspect` for another angle.
    - `aspect_side` 'sinister' | 'dexter': Side of the promissor's aspect: sinister is cast forward in the order of signs, dexter backward. Absent for the conjunction and opposition.
    - `date_naibod` string, date-time: Birth instant plus age_naibod tropical years (365.24219 days), ISO 8601 UTC.
    - `date_ptolemy` string, date-time: Birth instant plus age_ptolemy tropical years (365.24219 days), ISO 8601 UTC.
    - `is_converse` boolean: True when the significator is carried to the promissor.
    - `method` 'placidus_mundane' | 'placidus_zodiacal': The method that produced this event.
    - `promittor_id` integer: Body ID of the promissor (0 Sun … 6 Saturn).
    - `promittor_name` string
    - `significator_id` integer: 25 Ascendant, 27 Midheaven, 24 Part of Fortune, else the body ID.
    - `significator_name` string
  - `geo_lat` number, double: Birth latitude (°).
  - `obliquity` number, double: True obliquity of the ecliptic at birth (°).
  - `planets` PrimaryDirectionPlanet[]: Every point used: the significators, then the promissors.
    - `circumpolar` boolean: Never rises or sets at the birth latitude. A circumpolar point has no semi-arc proportion and takes part in no directions.
    - `declination` number, double: Declination (°).
    - `dsa` number, double: Diurnal semi-arc (°).
    - `fortune_formula` 'sect' | 'ptolemy': Only on the Part of Fortune, and only when the request sent `fortune_formula`: the formula that produced its longitude, `sect` or `ptolemy`. Absent from a request that did not send the field.
    - `id` integer
    - `is_above_horizon` boolean
    - `latitude` number, double: Ecliptic latitude (°).
    - `longitude` number, double: Ecliptic longitude (°).
    - `mundane_position` number, double: Placidian mundane position: −90 Ascendant, 0 Midheaven, 90 Descendant, 180 IC. One Placidus house is 30.
    - `name` string
    - `nsa` number, double: Nocturnal semi-arc (°).
    - `oa` number, double: Oblique ascension under the birth latitude: RA − ascensional difference (°).
    - `ra` number, double: Right ascension (°).
  - `ramc` number, double: Right ascension of the Midheaven at birth (°).

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/openephemeris/apis/open-ephemeris-api.md) · [All operations](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/revisions/d195a769cb89?raw)