Primary Directions

Western Timing

Primary Directions

Calculate primary-direction timing rows from a natal chart over a date range. The default method is Regiomontanus in-mundo, with explicit Campanus, topocentric, Placidus semiarc, Placidus under-the-pole zodiacal, and symbolic zodiacal modes available.

Supported classical options include exact event datetimes, Moon secondary motion correction, latitude doctrine controls, house-cusp significators, Lot of Fortune, antiscia, contra-antiscia, Egyptian/Ptolemaic bounds, syzygy, south node, and opt-in mundane parallels.

Endpoint

POST

https://api.freeastroapi.com/api/v1/western/directions/primary

Related routes

/directions/primary/exact-aspects/directions/primary/search/directions/primary/calendar

Classical Method Support

regiomontanus_in_mundo, campanus_in_mundo, topocentric_in_mundo, and placidus_semiarc_in_mundo return mundane table directions.
placidus_under_pole_zodiacal and zodiacal return zodiacal table directions.
Every event keeps date and adds exact_datetime_utc plus exact_datetime_local when the natal timezone is usable.
Use explicit Placidus variants; ambiguous placidus requests are rejected so clients choose the doctrine intentionally.
The production response cap is range.limit: 300. Use smaller limits for timeline widgets and paginated UIs.

Looking For 1 Year = 1 Degree?

Use the symbolic directions setup: method=zodiacal, direction=direct, and key=ptolemy. It applies the fixed Ptolemaic key of exactly one degree per year.

Open Symbolic Directions

Code Examples

curl -X POST "https://api.freeastroapi.com/api/v1/western/directions/primary" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
  "natal": {
    "name": "Documentation Sample",
    "datetime": "1990-01-01 12:00",
    "time_known": true,
    "location": {
      "city": "London",
      "lat": 51.5074,
      "lng": -0.1278,
      "tz_str": "Europe/London"
    }
  },
  "settings": {
    "method": "regiomontanus_in_mundo",
    "direction": "both",
    "key": "naibod",
    "secondary_motion": "moon",
    "latitude_doctrine": "both",
    "bounds_system": "egyptian",
    "include_bounds": true,
    "include_natal_reference": false,
    "promissors": [
      "sun",
      "moon",
      "mercury",
      "venus",
      "mars",
      "jupiter",
      "saturn"
    ],
    "significators": [
      "asc",
      "mc",
      "dc",
      "ic",
      "sun",
      "moon",
      "lot_of_fortune"
    ],
    "aspects": [
      "conjunction",
      "sextile",
      "square",
      "trine",
      "opposition"
    ],
    "orb_years": 1
  },
  "range": {
    "start_date": "2026-01-01",
    "end_date": "2030-12-31",
    "limit": 5
  }
}'

Request Parameters

Parameter	Type	Req	Description
natal.datetime	string	Yes	Birth datetime. Naive local strings are interpreted using natal.location.tz_str.
natal.time_known	boolean	No	Required when angles, house cusps, or Lot of Fortune are requested. Default: true.
natal.location	object	Yes	Natal city and coordinates. City-only requests are resolved when possible.
settings.method	string	No	regiomontanus_in_mundo, campanus_in_mundo, topocentric_in_mundo, placidus_semiarc_in_mundo, placidus_under_pole_zodiacal, or zodiacal. Default: regiomontanus_in_mundo.
settings.direction	string	No	direct, converse, or both. Default: direct.
settings.key	string	No	naibod, ptolemy, or custom. Default: naibod.
settings.custom_key_deg_per_year	number	No	Required when settings.key is custom.
settings.secondary_motion	boolean\|string	No	false/none, true/moon. all_planets is reserved for a future experimental mode.
settings.latitude_doctrine	string	No	none, promissor, significator, both, or bianchini. Default: both for in-mundo methods, none for zodiacal methods.
settings.bounds_system	string	No	egyptian or ptolemaic. Default: egyptian.
settings.include_bounds	boolean	No	Adds term/bound lord metadata for promissor, significator, and directed positions.
settings.include_bound_promissors	boolean	No	Generates term cusp promissors such as term_aries_1 using the selected bounds system.
settings.include_antiscia	boolean	No	Generates antiscion_<point> selectable points for planets, Lot of Fortune, angles, and syzygy where available.
settings.include_contra_antiscia	boolean	No	Generates contra_antiscion_<point> selectable points.
settings.include_mundane_parallels	boolean	No	Enables parallel and contra_parallel for in-mundo methods.
settings.include_natal_reference	boolean	No	Include the resolved natal point table. Default: true; set false for compact API responses.
settings.promissors	array[string]	No	Directed natal points. Defaults to Sun through Saturn. Supports planets, south_node, syzygy, lot_of_fortune, antiscia/contra-antiscia, and optional term cusps. Angles and house cusps are not promissors.
settings.significators	array[string]	No	Reference natal points. Supports asc, mc, dc, ic, house_1 through house_12, planets, south_node, syzygy, lot_of_fortune, and generated classical points.
settings.aspects	array[string]	No	conjunction, sextile, square, trine, opposition. With include_mundane_parallels=true: parallel, contra_parallel.
settings.orb_years	number	No	Calendar activation window around exact directions. Default: 1.
range.start_date	string	Yes	Search start as YYYY-MM-DD or ISO datetime.
range.end_date	string	Yes	Search end as YYYY-MM-DD or ISO datetime.
range.limit	integer	No	Maximum returned rows. Default: 100, max: 300.

Real Request

This checked-in request uses a timed London natal chart, Regiomontanus in-mundo, Moon secondary motion, both-latitude doctrine, Egyptian bounds, and a compact five-row limit.

{
  "natal": {
    "name": "Documentation Sample",
    "datetime": "1990-01-01 12:00",
    "time_known": true,
    "location": {
      "city": "London",
      "lat": 51.5074,
      "lng": -0.1278,
      "tz_str": "Europe/London"
    }
  },
  "settings": {
    "method": "regiomontanus_in_mundo",
    "direction": "both",
    "key": "naibod",
    "secondary_motion": "moon",
    "latitude_doctrine": "both",
    "bounds_system": "egyptian",
    "include_bounds": true,
    "include_natal_reference": false,
    "promissors": [
      "sun",
      "moon",
      "mercury",
      "venus",
      "mars",
      "jupiter",
      "saturn"
    ],
    "significators": [
      "asc",
      "mc",
      "dc",
      "ic",
      "sun",
      "moon",
      "lot_of_fortune"
    ],
    "aspects": [
      "conjunction",
      "sextile",
      "square",
      "trine",
      "opposition"
    ],
    "orb_years": 1
  },
  "range": {
    "start_date": "2026-01-01",
    "end_date": "2030-12-31",
    "limit": 5
  }
}

Real Response

This response was generated from the local backend implementation with the request above. It shows exact UTC/local event datetimes, active windows, Regiomontanus mundane positions, and bound lord metadata.

{
  "meta": {
    "endpoint": "primary_directions",
    "version": "v1",
    "method": "regiomontanus_in_mundo",
    "calculation_method": "regiomontanus_in_mundo_naibod_key_diurnal_armc_house_position_lunar_secondary_motion_both_latitude",
    "zodiac_type": "tropical",
    "direction": "both",
    "key": "naibod",
    "key_deg_per_year": 0.985647362,
    "range_start": "2026-01-01",
    "range_end": "2030-12-31",
    "generated_at": "2026-05-14T00:00:00Z",
    "warnings": [
      "In-mundo directions are computed as classical table rows with the selected primary-direction house system; zodiacal directions remain available with method=zodiacal.",
      "Secondary motion correction is applied astronomically to the Moon promissor using the directed arc converted from sidereal time to UT."
    ]
  },
  "input": {
    "birth_datetime": "1990-01-01 12:00",
    "birth_location": {
      "city": "London",
      "lat": 51.5074,
      "lng": -0.1278,
      "tz_str": "Europe/London"
    },
    "time_known": true,
    "promissors": [
      "sun",
      "moon",
      "mercury",
      "venus",
      "mars",
      "jupiter",
      "saturn"
    ],
    "significators": [
      "asc",
      "mc",
      "dc",
      "ic",
      "sun",
      "moon",
      "lot_of_fortune"
    ],
    "aspects": [
      "conjunction",
      "sextile",
      "square",
      "trine",
      "opposition"
    ],
    "orb_years": 1,
    "search_step_deg": 0.25,
    "secondary_motion": "moon",
    "latitude_doctrine": "both",
    "bounds_system": "egyptian",
    "include_bounds": true,
    "include_bound_promissors": false,
    "include_antiscia": false,
    "include_contra_antiscia": false,
    "include_mundane_parallels": false
  },
  "directions": [
    {
      "id": "pd.direct.saturn.trine.moon.2027-05-28T23:01:50.388898Z",
      "date": "2027-05-28",
      "exact_datetime_utc": "2027-05-28T23:01:50.388898Z",
      "exact_datetime_local": "2027-05-29T00:01:50.388898+01:00",
      "age_years": 37.4038,
      "direction": "direct",
      "promissor": "saturn",
      "significator": "moon",
      "aspect": {
        "name": "trine",
        "angle_deg": 120
      },
      "arc_deg": 36.866994,
      "arc_group_id": "pdg.mundane.direct.saturn.2027-05-28T23:01:50.388898Z.36.866994",
      "key": "naibod",
      "key_deg_per_year": 0.985647362,
      "promissor_natal_longitude_deg": 285.657498,
      "directed_longitude_deg": 285.657498,
      "significator_longitude_deg": 333.267655,
      "measurement": "mundane",
      "house_system": "regiomontanus",
      "promissor_natal_mundane_position": 282.675724,
      "directed_mundane_position": 214.161957,
      "significator_mundane_position": 334.161957,
      "promissor_bound": {
        "system": "egyptian",
        "sign": "capricorn",
        "index": 3,
        "lord": "venus",
        "start_deg": 284,
        "end_deg": 292
      },
      "significator_bound": {
        "system": "egyptian",
        "sign": "pisces",
        "index": 1,
        "lord": "venus",
        "start_deg": 330,
        "end_deg": 342
      },
      "directed_bound": {
        "system": "egyptian",
        "sign": "capricorn",
        "index": 3,
        "lord": "venus",
        "start_deg": 284,
        "end_deg": 292
      },
      "orb_years": 1,
      "active_window": {
        "from": "2026-05-28",
        "exact": "2027-05-28",
        "to": "2028-05-28",
        "from_datetime_utc": "2026-05-28T17:13:05.259298Z",
        "exact_datetime_utc": "2027-05-28T23:01:50.388898Z",
        "to_datetime_utc": "2028-05-28T04:50:35.518498Z",
        "from_datetime_local": "2026-05-28T18:13:05.259298+01:00",
        "exact_datetime_local": "2027-05-29T00:01:50.388898+01:00",
        "to_datetime_local": "2028-05-28T05:50:35.518498+01:00"
      },
      "interpretation_key": "primary_direction.direct.trine.saturn.moon"
    },
    {
      "id": "pd.converse.saturn.sextile.lot_of_fortune.2027-07-27T23:53:26.349170Z",
      "date": "2027-07-27",
      "exact_datetime_utc": "2027-07-27T23:53:26.349170Z",
      "exact_datetime_local": "2027-07-28T00:53:26.349170+01:00",
      "age_years": 37.5682,
      "direction": "converse",
      "promissor": "saturn",
      "significator": "lot_of_fortune",
      "aspect": {
        "name": "sextile",
        "angle_deg": 60
      },
      "arc_deg": 37.029008,
      "arc_group_id": "pdg.mundane.converse.saturn.2027-07-27T23:53:26.349170Z.37.029008",
      "key": "naibod",
      "key_deg_per_year": 0.985647362,
      "promissor_natal_longitude_deg": 285.657498,
      "directed_longitude_deg": 285.657498,
      "significator_longitude_deg": 77.397434,
      "measurement": "mundane",
      "house_system": "regiomontanus",
      "promissor_natal_mundane_position": 282.675724,
      "directed_mundane_position": 342.60122,
      "significator_mundane_position": 42.60122,
      "promissor_bound": {
        "system": "egyptian",
        "sign": "capricorn",
        "index": 3,
        "lord": "venus",
        "start_deg": 284,
        "end_deg": 292
      },
      "significator_bound": {
        "system": "egyptian",
        "sign": "gemini",
        "index": 4,
        "lord": "mars",
        "start_deg": 77,
        "end_deg": 84
      },
      "directed_bound": {
        "system": "egyptian",
        "sign": "capricorn",
        "index": 3,
        "lord": "venus",
        "start_deg": 284,
        "end_deg": 292
      },
      "orb_years": 1,
      "active_window": {
        "from": "2026-07-27",
        "exact": "2027-07-27",
        "to": "2028-07-27",
        "from_datetime_utc": "2026-07-27T18:04:41.219570Z",
        "exact_datetime_utc": "2027-07-27T23:53:26.349170Z",
        "to_datetime_utc": "2028-07-27T05:42:11.478770Z",
        "from_datetime_local": "2026-07-27T19:04:41.219570+01:00",
        "exact_datetime_local": "2027-07-28T00:53:26.349170+01:00",
        "to_datetime_local": "2028-07-27T06:42:11.478770+01:00"
      },
      "interpretation_key": "primary_direction.converse.sextile.saturn.lot_of_fortune"
    },
    {
      "id": "pd.converse.jupiter.trine.mc.2027-10-31T09:31:58.251733Z",
      "date": "2027-10-31",
      "exact_datetime_utc": "2027-10-31T09:31:58.251733Z",
      "exact_datetime_local": "2027-10-31T09:31:58.251733+00:00",
      "age_years": 37.8294,
      "direction": "converse",
      "promissor": "jupiter",
      "significator": "mc",
      "aspect": {
        "name": "trine",
        "angle_deg": 120
      },
      "arc_deg": 37.28646,
      "arc_group_id": "pdg.mundane.converse.jupiter.2027-10-31T09:31:58.251733Z.37.286460",
      "key": "naibod",
      "key_deg_per_year": 0.985647362,
      "promissor_natal_longitude_deg": 95.148794,
      "directed_longitude_deg": 95.148794,
      "significator_longitude_deg": 279.88249,
      "measurement": "mundane",
      "house_system": "regiomontanus",
      "promissor_natal_mundane_position": 78.877261,
      "directed_mundane_position": 150,
      "significator_mundane_position": 270,
      "promissor_bound": {
        "system": "egyptian",
        "sign": "cancer",
        "index": 1,
        "lord": "mars",
        "start_deg": 90,
        "end_deg": 97
      },
      "significator_bound": {
        "system": "egyptian",
        "sign": "capricorn",
        "index": 2,
        "lord": "jupiter",
        "start_deg": 277,
        "end_deg": 284
      },
      "directed_bound": {
        "system": "egyptian",
        "sign": "cancer",
        "index": 1,
        "lord": "mars",
        "start_deg": 90,
        "end_deg": 97
      },
      "orb_years": 1,
      "active_window": {
        "from": "2026-10-31",
        "exact": "2027-10-31",
        "to": "2028-10-30",
        "from_datetime_utc": "2026-10-31T03:43:13.122133Z",
        "exact_datetime_utc": "2027-10-31T09:31:58.251733Z",
        "to_datetime_utc": "2028-10-30T15:20:43.381333Z",
        "from_datetime_local": "2026-10-31T03:43:13.122133+00:00",
        "exact_datetime_local": "2027-10-31T09:31:58.251733+00:00",
        "to_datetime_local": "2028-10-30T15:20:43.381333+00:00"
      },
      "interpretation_key": "primary_direction.converse.trine.jupiter.mc"
    },
    {
      "id": "pd.converse.jupiter.sextile.ic.2027-10-31T09:31:58.251733Z",
      "date": "2027-10-31",
      "exact_datetime_utc": "2027-10-31T09:31:58.251733Z",
      "exact_datetime_local": "2027-10-31T09:31:58.251733+00:00",
      "age_years": 37.8294,
      "direction": "converse",
      "promissor": "jupiter",
      "significator": "ic",
      "aspect": {
        "name": "sextile",
        "angle_deg": 60
      },
      "arc_deg": 37.28646,
      "arc_group_id": "pdg.mundane.converse.jupiter.2027-10-31T09:31:58.251733Z.37.286460",
      "key": "naibod",
      "key_deg_per_year": 0.985647362,
      "promissor_natal_longitude_deg": 95.148794,
      "directed_longitude_deg": 95.148794,
      "significator_longitude_deg": 99.88249,
      "measurement": "mundane",
      "house_system": "regiomontanus",
      "promissor_natal_mundane_position": 78.877261,
      "directed_mundane_position": 150,
      "significator_mundane_position": 90,
      "promissor_bound": {
        "system": "egyptian",
        "sign": "cancer",
        "index": 1,
        "lord": "mars",
        "start_deg": 90,
        "end_deg": 97
      },
      "significator_bound": {
        "system": "egyptian",
        "sign": "cancer",
        "index": 2,
        "lord": "venus",
        "start_deg": 97,
        "end_deg": 103
      },
      "directed_bound": {
        "system": "egyptian",
        "sign": "cancer",
        "index": 1,
        "lord": "mars",
        "start_deg": 90,
        "end_deg": 97
      },
      "orb_years": 1,
      "active_window": {
        "from": "2026-10-31",
        "exact": "2027-10-31",
        "to": "2028-10-30",
        "from_datetime_utc": "2026-10-31T03:43:13.122133Z",
        "exact_datetime_utc": "2027-10-31T09:31:58.251733Z",
        "to_datetime_utc": "2028-10-30T15:20:43.381333Z",
        "from_datetime_local": "2026-10-31T03:43:13.122133+00:00",
        "exact_datetime_local": "2027-10-31T09:31:58.251733+00:00",
        "to_datetime_local": "2028-10-30T15:20:43.381333+00:00"
      },
      "interpretation_key": "primary_direction.converse.sextile.jupiter.ic"
    },
    {
      "id": "pd.direct.saturn.sextile.sun.2028-10-19T11:15:59.846321Z",
      "date": "2028-10-19",
      "exact_datetime_utc": "2028-10-19T11:15:59.846321Z",
      "exact_datetime_local": "2028-10-19T12:15:59.846321+01:00",
      "age_years": 38.7988,
      "direction": "direct",
      "promissor": "saturn",
      "significator": "sun",
      "aspect": {
        "name": "sextile",
        "angle_deg": 60
      },
      "arc_deg": 38.241964,
      "arc_group_id": "pdg.mundane.direct.saturn.2028-10-19T11:15:59.846321Z.38.241964",
      "key": "naibod",
      "key_deg_per_year": 0.985647362,
      "promissor_natal_longitude_deg": 285.657498,
      "directed_longitude_deg": 285.657498,
      "significator_longitude_deg": 280.814261,
      "measurement": "mundane",
      "house_system": "regiomontanus",
      "promissor_natal_mundane_position": 282.675724,
      "directed_mundane_position": 212.165018,
      "significator_mundane_position": 272.165018,
      "promissor_bound": {
        "system": "egyptian",
        "sign": "capricorn",
        "index": 3,
        "lord": "venus",
        "start_deg": 284,
        "end_deg": 292
      },
      "significator_bound": {
        "system": "egyptian",
        "sign": "capricorn",
        "index": 2,
        "lord": "jupiter",
        "start_deg": 277,
        "end_deg": 284
      },
      "directed_bound": {
        "system": "egyptian",
        "sign": "capricorn",
        "index": 3,
        "lord": "venus",
        "start_deg": 284,
        "end_deg": 292
      },
      "orb_years": 1,
      "active_window": {
        "from": "2027-10-20",
        "exact": "2028-10-19",
        "to": "2029-10-19",
        "from_datetime_utc": "2027-10-20T05:27:14.716721Z",
        "exact_datetime_utc": "2028-10-19T11:15:59.846321Z",
        "to_datetime_utc": "2029-10-19T17:04:44.975921Z",
        "from_datetime_local": "2027-10-20T06:27:14.716721+01:00",
        "exact_datetime_local": "2028-10-19T12:15:59.846321+01:00",
        "to_datetime_local": "2029-10-19T18:04:44.975921+01:00"
      },
      "interpretation_key": "primary_direction.direct.sextile.saturn.sun"
    }
  ]
}