Symbolic Directions

Symbolic Directions: 1 Year = 1 Degree

POST/api/v1/western/directions/primary

Use this page for the simple zodiacal direction technique where each year of life advances a point by exactly one degree. In the API this is the primary directions endpoint with method=zodiacal, direction=direct, and key=ptolemy.

Full URL

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

Related Routes

/directions/primary/calendar/directions/primary/search

Exact Settings

method: zodiacal

Use symbolic zodiacal arcs instead of mundane in-mundo directions.

direction: direct

Move the promissor forward through the zodiac.

key: ptolemy

Apply the fixed Ptolemaic key: 1.0 degree per year.

Minimal Request

This returns exact direction rows over the requested date range. The request below is the same checked-in sample used for the live response.

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": "Symbolic Directions 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": "zodiacal",
    "direction": "direct",
    "key": "ptolemy",
    "promissors": [
      "sun",
      "moon",
      "mercury",
      "venus",
      "mars"
    ],
    "significators": [
      "asc",
      "mc",
      "sun",
      "moon"
    ],
    "aspects": [
      "conjunction",
      "sextile",
      "square",
      "trine",
      "opposition"
    ],
    "orb_years": 1,
    "include_natal_reference": false
  },
  "range": {
    "start_date": "2026-01-01",
    "end_date": "2030-12-31",
    "limit": 20
  }
}'

Ptolemy, Naibod, Or Custom

For this specific technique, use key=ptolemy. It is exactly 1.0 degree per year.

key=naibod is close, but not identical. It uses the mean solar arc rate, roughly 0.9856 degrees per year. Use it only when you intentionally want Naibod timing.

You can also express the same fixed key explicitly with a custom key:

{
  "settings": {
    "method": "zodiacal",
    "direction": "direct",
    "key": "custom",
    "custom_key_deg_per_year": 1.0
  }
}

Calendar Variant

Use the calendar route when the UI needs a compact feed of exact symbolic directions instead of full event rows. The response example below is generated from this request.

curl -X POST "https://api.freeastroapi.com/api/v1/western/directions/primary/calendar" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
  "natal": {
    "name": "Symbolic Directions 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": "zodiacal",
    "direction": "direct",
    "key": "ptolemy",
    "promissors": [
      "sun",
      "moon",
      "mercury",
      "venus",
      "mars"
    ],
    "significators": [
      "asc",
      "mc",
      "sun",
      "moon"
    ],
    "aspects": [
      "conjunction",
      "square",
      "trine",
      "opposition"
    ],
    "orb_years": 1,
    "include_natal_reference": false
  },
  "range": {
    "start_date": "2026-01-01",
    "end_date": "2026-12-31",
    "limit": 20
  }
}'

Response Fields To Check

Field	Meaning
meta.key_deg_per_year	Confirms the applied direction key. Ptolemy returns 1.0.
directions[].age_years	Age at exact perfection, derived from arc / key.
directions[].arc_deg	Directed arc in zodiacal degrees.
directions[].directed_longitude_deg	Promissor longitude after symbolic direction.
directions[].active_window	Orb window around the exact direction, controlled by orb_years.

Real Request

This checked-in request uses a timed London natal chart and the fixed Ptolemaic key. It is generated from the same payload used by the example curl command.

{
  "natal": {
    "name": "Symbolic Directions 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": "zodiacal",
    "direction": "direct",
    "key": "ptolemy",
    "promissors": [
      "sun",
      "moon",
      "mercury",
      "venus",
      "mars"
    ],
    "significators": [
      "asc",
      "mc",
      "sun",
      "moon"
    ],
    "aspects": [
      "conjunction",
      "sextile",
      "square",
      "trine",
      "opposition"
    ],
    "orb_years": 1,
    "include_natal_reference": false
  },
  "range": {
    "start_date": "2026-01-01",
    "end_date": "2030-12-31",
    "limit": 20
  }
}

Real Response

This response was generated from the local backend primary-directions implementation with the request above. It confirms key_deg_per_year: 1 and returns exact symbolic direction rows.

{
  "meta": {
    "endpoint": "primary_directions",
    "version": "v1",
    "method": "zodiacal",
    "calculation_method": "zodiacal_ptolemy_key_symbolic_zodiacal",
    "zodiac_type": "tropical",
    "direction": "direct",
    "key": "ptolemy",
    "key_deg_per_year": 1,
    "range_start": "2026-01-01",
    "range_end": "2030-12-31",
    "generated_at": "2026-05-19T16:59:59.930337+00:00",
    "warnings": [
      "Zodiacal directions are symbolic arc directions unless a named zodiacal primary-direction method is selected."
    ]
  },
  "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"
    ],
    "significators": [
      "asc",
      "mc",
      "sun",
      "moon"
    ],
    "aspects": [
      "conjunction",
      "sextile",
      "square",
      "trine",
      "opposition"
    ],
    "orb_years": 1,
    "search_step_deg": 0.25,
    "secondary_motion": "none",
    "latitude_doctrine": "none",
    "bounds_system": "egyptian",
    "include_bounds": false,
    "include_bound_promissors": false,
    "include_antiscia": false,
    "include_contra_antiscia": false,
    "include_mundane_parallels": false
  },
  "directions": [
    {
      "id": "pd.direct.moon.square.mc.2026-08-13T18:47:00.430412Z",
      "date": "2026-08-13",
      "exact_datetime_utc": "2026-08-13T18:47:00.430412Z",
      "exact_datetime_local": "2026-08-13T19:47:00.430412+01:00",
      "age_years": 36.6148,
      "direction": "direct",
      "promissor": "moon",
      "significator": "mc",
      "aspect": {
        "name": "square",
        "angle_deg": 90
      },
      "arc_deg": 36.614835,
      "arc_group_id": "pdg.zodiacal.direct.moon.2026-08-13T18:47:00.430412Z.36.614835",
      "key": "ptolemy",
      "key_deg_per_year": 1,
      "promissor_natal_longitude_deg": 333.267655,
      "directed_longitude_deg": 9.88249,
      "significator_longitude_deg": 279.88249,
      "measurement": "zodiacal",
      "orb_years": 1,
      "active_window": {
        "from": "2025-08-13",
        "exact": "2026-08-13",
        "to": "2027-08-14",
        "from_datetime_utc": "2025-08-13T12:58:15.300812Z",
        "exact_datetime_utc": "2026-08-13T18:47:00.430412Z",
        "to_datetime_utc": "2027-08-14T00:35:45.560012Z",
        "from_datetime_local": "2025-08-13T13:58:15.300812+01:00",
        "exact_datetime_local": "2026-08-13T19:47:00.430412+01:00",
        "to_datetime_local": "2027-08-14T01:35:45.560012+01:00"
      },
      "interpretation_key": "primary_direction.direct.square.moon.mc"
    },
    {
      "id": "pd.direct.moon.square.sun.2027-07-20T02:30:41.783478Z",
      "date": "2027-07-20",
      "exact_datetime_utc": "2027-07-20T02:30:41.783478Z",
      "exact_datetime_local": "2027-07-20T03:30:41.783478+01:00",
      "age_years": 37.5466,
      "direction": "direct",
      "promissor": "moon",
      "significator": "sun",
      "aspect": {
        "name": "square",
        "angle_deg": 90
      },
      "arc_deg": 37.546606,
      "arc_group_id": "pdg.zodiacal.direct.moon.2027-07-20T02:30:41.783478Z.37.546606",
      "key": "ptolemy",
      "key_deg_per_year": 1,
      "promissor_natal_longitude_deg": 333.267655,
      "directed_longitude_deg": 10.814261,
      "significator_longitude_deg": 280.814261,
      "measurement": "zodiacal",
      "orb_years": 1,
      "active_window": {
        "from": "2026-07-19",
        "exact": "2027-07-20",
        "to": "2028-07-19",
        "from_datetime_utc": "2026-07-19T20:41:56.653878Z",
        "exact_datetime_utc": "2027-07-20T02:30:41.783478Z",
        "to_datetime_utc": "2028-07-19T08:19:26.913078Z",
        "from_datetime_local": "2026-07-19T21:41:56.653878+01:00",
        "exact_datetime_local": "2027-07-20T03:30:41.783478+01:00",
        "to_datetime_local": "2028-07-19T09:19:26.913078+01:00"
      },
      "interpretation_key": "primary_direction.direct.square.moon.sun"
    },
    {
      "id": "pd.direct.mercury.conjunction.moon.2027-08-06T17:13:33.433592Z",
      "date": "2027-08-06",
      "exact_datetime_utc": "2027-08-06T17:13:33.433592Z",
      "exact_datetime_local": "2027-08-06T18:13:33.433592+01:00",
      "age_years": 37.5948,
      "direction": "direct",
      "promissor": "mercury",
      "significator": "moon",
      "aspect": {
        "name": "conjunction",
        "angle_deg": 0
      },
      "arc_deg": 37.594829,
      "arc_group_id": "pdg.zodiacal.direct.mercury.2027-08-06T17:13:33.433592Z.37.594829",
      "key": "ptolemy",
      "key_deg_per_year": 1,
      "promissor_natal_longitude_deg": 295.672825,
      "directed_longitude_deg": 333.267655,
      "significator_longitude_deg": 333.267655,
      "measurement": "zodiacal",
      "orb_years": 1,
      "active_window": {
        "from": "2026-08-06",
        "exact": "2027-08-06",
        "to": "2028-08-05",
        "from_datetime_utc": "2026-08-06T11:24:48.303992Z",
        "exact_datetime_utc": "2027-08-06T17:13:33.433592Z",
        "to_datetime_utc": "2028-08-05T23:02:18.563192Z",
        "from_datetime_local": "2026-08-06T12:24:48.303992+01:00",
        "exact_datetime_local": "2027-08-06T18:13:33.433592+01:00",
        "to_datetime_local": "2028-08-06T00:02:18.563192+01:00"
      },
      "interpretation_key": "primary_direction.direct.conjunction.mercury.moon"
    }
  ]
}

Real Calendar Response

This compact event feed is generated from the calendar request above and is useful for timeline or alert-style interfaces.

{
  "meta": {
    "endpoint": "primary_directions",
    "version": "v1",
    "method": "zodiacal",
    "calculation_method": "zodiacal_ptolemy_key_symbolic_zodiacal",
    "zodiac_type": "tropical",
    "direction": "direct",
    "key": "ptolemy",
    "key_deg_per_year": 1,
    "range_start": "2026-01-01",
    "range_end": "2026-12-31",
    "generated_at": "2026-05-19T16:59:59.931677+00:00",
    "warnings": [
      "Zodiacal directions are symbolic arc directions unless a named zodiacal primary-direction method is selected."
    ]
  },
  "events": [
    {
      "date": "2026-08-13",
      "exact_datetime_utc": "2026-08-13T18:47:00.430412Z",
      "exact_datetime_local": "2026-08-13T19:47:00.430412+01:00",
      "type": "primary_direction",
      "title": "Moon direct square Midheaven",
      "direction_id": "pd.direct.moon.square.mc.2026-08-13T18:47:00.430412Z",
      "interpretation_key": "primary_direction.direct.square.moon.mc"
    }
  ]
}

Astrologer Note

This page documents the timing-row workflow for fixed one-degree-per-year symbolic directions. If you need a full chart where every planet, angle, and house cusp is visibly advanced by the same arc, use this endpoint for timing and see the related Quotidian chart docs for the current arc-based chart response. Quotidian uses a solar-arc basis, so it is not identical to the fixed Ptolemaic key.

Primary Directions

Full classical and symbolic direction options.

Progressions

Secondary, converse, tertiary, quotidian, and quaternary charts.