Monthly and Yearly Profections

POST/api/v1/western/profections/annual

The profections endpoint is annual-first: every request returns the yearly profection summary for the target year, and monthly profections are added through include=monthly_profections. The same route can also expand the payload with natal time-lord details, activated-house planets, and time-lord aspects.

Endpoint: POST /api/v1/western/profections/annual

In the live production contract, the yearly summary sits at profection.annual and monthly periods appear at profection.monthly_profections only when requested.

Request Parameters

Parameter	Type	Req	Description
name	string	No	Display name for the chart subject. Defaults to `User` if omitted.
year	number	Yes	Birth year.
month	number	Yes	Birth month from 1 to 12.
day	number	Yes	Birth day of month.
hour	number	No	Birth hour in local civil time. Defaults to `12`.
minute	number	No	Birth minute in local civil time. Defaults to `0`.
time_known	boolean	No	When false, house-based profection outputs are reduced and monthly profections are omitted.
city	string	Yes	Birth city. Used for geocoding fallback and response labeling.
lat	number	No	Latitude for the natal location. Strongly recommended for deterministic results.
lng	number	No	Longitude for the natal location. Strongly recommended for deterministic results.
tz_str	string	No	IANA timezone such as `Europe/London` or `AUTO`, matching the natal endpoint style.
annual_profection.year	number	Yes	Target profection year. The annual summary covers the birthday-to-birthday profection period for that year.
annual_profection.settings.zodiac_type	string	No	Tropical or Sidereal. The live sample uses Tropical.
annual_profection.settings.sidereal_ayanamsa	string	No	Optional sidereal ayanamsa when `zodiac_type` is Sidereal.
annual_profection.settings.orb_policy	object	No	Aspect orb configuration used for `time_lord_aspects`, with `default_orb_deg` and optional `by_aspect_deg` overrides.
include	query string	No	CSV or repeated query values. Supported values: `monthly_profections`, `natal_time_lord_details`, `activated_house_planets`, `time_lord_aspects`.

curl -X POST "https://api.freeastroapi.com/api/v1/western/profections/annual?include=monthly_profections,natal_time_lord_details,activated_house_planets,time_lord_aspects" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
    "name": "Live Docs Example",
    "year": 1990,
    "month": 1,
    "day": 1,
    "hour": 12,
    "minute": 0,
    "time_known": true,
    "city": "London",
    "lat": 51.5074,
    "lng": -0.1278,
    "tz_str": "Europe/London",
    "annual_profection": {
        "year": 2024,
        "settings": {
            "zodiac_type": "Tropical",
            "orb_policy": {
                "default_orb_deg": 6.0,
                "by_aspect_deg": {}
            }
        }
    }
}'

Response Excerpt

This live sample was captured from production on April 14, 2026. The top-level response groups aremeta, subject, and profection.

{
  "meta": {
    "report_id": "85d989d1-3aba-4689-a1d6-4dc16c6b356c",
    "generated_at": "2026-04-14T16:07:09.832157Z",
    "engine": {
      "name": "AnnualProfectionsEngine",
      "version": "2.0.0"
    },
    "calculation": {
      "zodiac_type": "Tropical",
      "profection_method": "whole_sign",
      "orb_policy": {
        "default_orb_deg": 6,
        "by_aspect_deg": {}
      },
      "includes": [
        "activated_house_planets",
        "monthly_profections",
        "natal_time_lord_details",
        "time_lord_aspects"
      ]
    },
    "annual_profection": {
      "target_year": 2024,
      "age_at_start": 34,
      "period": {
        "start": "2024-01-01T12:00:00+00:00",
        "end": "2025-01-01T12:00:00+00:00"
      }
    },
    "natal_reference": {
      "natal_datetime": "1990-01-01T12:00:00+00:00",
      "natal_location": {
        "city": "London",
        "lat": 51.5074,
        "lng": -0.1278,
        "timezone": "Europe/London"
      },
      "time_known": true
    },
    "warnings": []
  },
  "subject": {
    "name": "Live Docs Example",
    "datetime": "1990-01-01T12:00:00+00:00",
    "location": {
      "city": "London",
      "lat": 51.5074,
      "lng": -0.1278,
      "timezone": "Europe/London"
    },
    "settings": {
      "house_system": "whole_sign",
      "zodiac_type": "Tropical",
      "time_known": true
    }
  },
  "profection": {
    "annual": {
      "age": 34,
      "activated_house": 11,
      "activated_sign_name": "Aquarius",
      "activated_sign_id": "aquarius",
      "time_lord_name": "Saturn",
      "time_lord_id": "saturn",
      "period": {
        "start": "2024-01-01T12:00:00+00:00",
        "end": "2025-01-01T12:00:00+00:00"
      },
      "notes": []
    },
    "monthly_profections": [
      {
        "month_index": 1,
        "activated_house": 11,
        "activated_sign_name": "Aquarius",
        "activated_sign_id": "aquarius",
        "time_lord_name": "Saturn",
        "time_lord_id": "saturn",
        "period": {
          "start": "2024-01-01T12:00:00+00:00",
          "end": "2024-02-01T12:00:00+00:00"
        }
      },
      {
        "month_index": 2,
        "activated_house": 12,
        "activated_sign_name": "Pisces",
        "activated_sign_id": "pisces",
        "time_lord_name": "Jupiter",
        "time_lord_id": "jupiter",
        "period": {
          "start": "2024-02-01T12:00:00+00:00",
          "end": "2024-03-01T12:00:00+00:00"
        }
      },
      {
        "month_index": 3,
        "activated_house": 1,
        "activated_sign_name": "Aries",
        "activated_sign_id": "aries",
        "time_lord_name": "Mars",
        "time_lord_id": "mars",
        "period": {
          "start": "2024-03-01T12:00:00+00:00",
          "end": "2024-04-01T12:00:00+00:00"
        }
      },
      {
        "month_index": 4,
        "activated_house": 2,
        "activated_sign_name": "Taurus",
        "activated_sign_id": "taurus",
        "time_lord_name": "Venus",
        "time_lord_id": "venus",
        "period": {
          "start": "2024-04-01T12:00:00+00:00",
          "end": "2024-05-01T12:00:00+00:00"
        }
      },
      {
        "month_index": 5,
        "activated_house": 3,
        "activated_sign_name": "Gemini",
        "activated_sign_id": "gemini",
        "time_lord_name": "Mercury",
        "time_lord_id": "mercury",
        "period": {
          "start": "2024-05-01T12:00:00+00:00",
          "end": "2024-06-01T12:00:00+00:00"
        }
      },
      {
        "month_index": 6,
        "activated_house": 4,
        "activated_sign_name": "Cancer",
        "activated_sign_id": "cancer",
        "time_lord_name": "Moon",
        "time_lord_id": "moon",
        "period": {
          "start": "2024-06-01T12:00:00+00:00",
          "end": "2024-07-01T12:00:00+00:00"
        }
      },
      {
        "month_index": 7,
        "activated_house": 5,
        "activated_sign_name": "Leo",
        "activated_sign_id": "leo",
        "time_lord_name": "Sun",
        "time_lord_id": "sun",
        "period": {
          "start": "2024-07-01T12:00:00+00:00",
          "end": "2024-08-01T12:00:00+00:00"
        }
      },
      {
        "month_index": 8,
        "activated_house": 6,
        "activated_sign_name": "Virgo",
        "activated_sign_id": "virgo",
        "time_lord_name": "Mercury",
        "time_lord_id": "mercury",
        "period": {
          "start": "2024-08-01T12:00:00+00:00",
          "end": "2024-09-01T12:00:00+00:00"
        }
      },
      {
        "month_index": 9,
        "activated_house": 7,
        "activated_sign_name": "Libra",
        "activated_sign_id": "libra",
        "time_lord_name": "Venus",
        "time_lord_id": "venus",
        "period": {
          "start": "2024-09-01T12:00:00+00:00",
          "end": "2024-10-01T12:00:00+00:00"
        }
      },
      {
        "month_index": 10,
        "activated_house": 8,
        "activated_sign_name": "Scorpio",
        "activated_sign_id": "scorpio",
        "time_lord_name": "Mars",
        "time_lord_id": "mars",
        "period": {
          "start": "2024-10-01T12:00:00+00:00",
          "end": "2024-11-01T12:00:00+00:00"
        }
      },
      {
        "month_index": 11,
        "activated_house": 9,
        "activated_sign_name": "Sagittarius",
        "activated_sign_id": "sagittarius",
        "time_lord_name": "Jupiter",
        "time_lord_id": "jupiter",
        "period": {
          "start": "2024-11-01T12:00:00+00:00",
          "end": "2024-12-01T12:00:00+00:00"
        }
      },
      {
        "month_index": 12,
        "activated_house": 10,
        "activated_sign_name": "Capricorn",
        "activated_sign_id": "capricorn",
        "time_lord_name": "Saturn",
        "time_lord_id": "saturn",
        "period": {
          "start": "2024-12-01T12:00:00+00:00",
          "end": "2025-01-01T12:00:00+00:00"
        }
      }
    ],
    "natal_time_lord_details": {
      "id": "saturn",
      "name": "Saturn",
      "sign_name": "Cap",
      "sign_id": "capricorn",
      "pos": 15.657,
      "abs_pos": 285.657,
      "house": 10,
      "retrograde": false,
      "speed": 0.1183
    },
    "activated_house_planets": [
      {
        "id": "venus",
        "name": "Venus",
        "sign_name": "Aqu",
        "sign_id": "aquarius",
        "pos": 6.222,
        "abs_pos": 306.222,
        "house": 11,
        "retrograde": true
      },
      {
        "id": "north_node",
        "name": "North Node",
        "sign_name": "Aqu",
        "sign_id": "aquarius",
        "pos": 18.435,
        "abs_pos": 318.435,
        "house": 11,
        "retrograde": true
      }
    ],
    "time_lord_aspects": [
      {
        "time_lord_id": "saturn",
        "time_lord_name": "Saturn",
        "other_body_id": "pluto",
        "other_body_name": "Pluto",
        "other_body_sign_name": "Sco",
        "other_body_sign_id": "scorpio",
        "other_body_house": 8,
        "other_body_abs_pos": 227.093,
        "aspect": "sextile",
        "orb": 1.44,
        "deg": 60,
        "is_major": true,
        "is_applying": false
      },
      {
        "time_lord_id": "saturn",
        "time_lord_name": "Saturn",
        "other_body_id": "moon",
        "other_body_name": "Moon",
        "other_body_sign_name": "Pis",
        "other_body_sign_id": "pisces",
        "other_body_house": 12,
        "other_body_abs_pos": 333.268,
        "aspect": "semi_square",
        "orb": 2.61,
        "deg": 45,
        "is_major": false,
        "is_applying": false
      },
      {
        "time_lord_id": "saturn",
        "time_lord_name": "Saturn",
        "other_body_id": "north_node",
        "other_body_name": "North Node",
        "other_body_sign_name": "Aqu",
        "other_body_sign_id": "aquarius",
        "other_body_house": 11,
        "other_body_abs_pos": 318.435,
        "aspect": "semi_sextile",
        "orb": 2.78,
        "deg": 30,
        "is_major": false,
        "is_applying": true
      },
      {
        "time_lord_id": "saturn",
        "time_lord_name": "Saturn",
        "other_body_id": "neptune",
        "other_body_name": "Neptune",
        "other_body_sign_name": "Cap",
        "other_body_sign_id": "capricorn",
        "other_body_house": 10,
        "other_body_abs_pos": 282.038,
        "aspect": "conjunction",
        "orb": 3.62,
        "deg": 0,
        "is_major": true,
        "is_applying": false
      },
      {
        "time_lord_id": "saturn",
        "time_lord_name": "Saturn",
        "other_body_id": "sun",
        "other_body_name": "Sun",
        "other_body_sign_name": "Cap",
        "other_body_sign_id": "capricorn",
        "other_body_house": 10,
        "other_body_abs_pos": 280.814,
        "aspect": "conjunction",
        "orb": 4.84,
        "deg": 0,
        "is_major": true,
        "is_applying": true
      },
      {
        "time_lord_id": "saturn",
        "time_lord_name": "Saturn",
        "other_body_id": "mars",
        "other_body_name": "Mars",
        "other_body_sign_name": "Sag",
        "other_body_sign_id": "sagittarius",
        "other_body_house": 9,
        "other_body_abs_pos": 250,
        "aspect": "semi_sextile",
        "orb": 5.66,
        "deg": 30,
        "is_major": false,
        "is_applying": true
      }
    ]
  }
}

The checked-in live sample is available at frontend/src/app/docs/western/profections/live_response.json.

Response Notes

profection.annual is the yearly profection summary. The current live fields includeactivated_sign_name, time_lord_name, and a single period object withstart and end.

profection.monthly_profections contains 12 month-by-month profection periods wheninclude=monthly_profections is present.

The nested include blocks in the current live API still use some abbreviated sign labels inside fields such assign_name and other_body_sign_name. The checked-in sample preserves those values exactly as production returns them.