POST/v1/western/profections

Annual profections

Annual profections for a birth chart and a date: the whole-sign house activated this year, its sign, and the lord of the year (the sign's traditional ruler). Rule: the Ascendant sign is the 1st house at birth and the activated sign moves forward one sign every birthday, so at age N the profected house is (N mod 12) + 1. A birth time is required because the count starts from the Ascendant; without one the request is rejected with a clear message. Includes where the year lord sits natally and the next twelve profection years.

Request parameters

locationoptional

string | null

City name to resolve to lat/lon/tz automatically. Example: 'Mumbai' or 'New Delhi, India'. If provided, latitude, longitude and timezone are not required.

nameoptional

string

Person name associated with the birth record

daterequired

string

Birth date in YYYY-MM-DD format

timerequired

string

Birth time in HH:MM 24-hour format. Required: profections count from the Ascendant sign, which needs the birth time.

latitudeoptional

number | null

Latitude. Required if location not provided.

longitudeoptional

number | null

Longitude. Required if location not provided.

timezoneoptional

string | null

IANA timezone. Required if location not provided (unless utc_offset is given). For dates before the zone adopted a standard time, the birthplace's local mean time (longitude / 15 hours) is used.

utc_offsetoptional

string | null

Optional explicit UTC offset of the birth time, as ±HH:MM or ±HH:MM:SS (e.g. '+04:51:31' for Bombay mean time). Overrides the offset timezone would give. Use it when the birth record states the offset, or for historical local times the IANA database cannot represent.

ayanamsaoptional

string

Ignored on Western endpoints: positions are always tropical (no ayanamsa). Accepted so one birth object can be sent to Vedic and Western endpoints alike.

house_systemoptional

string

House system for the natal house reported under year_lord_natal. Profections themselves always use whole signs.

target_dateoptional

string | null

Date to profect to (YYYY-MM-DD). Defaults to today (UTC).

Response fields

success

boolean

True if the request succeeded

message

string

Human-readable status message

data

object

data.birth_time_provided

boolean

True when a birth time was supplied. False when it was not: house, Ascendant and Moon-dependent results then carry the accuracy limits of an unknown birth time.

data.target_date

string

data.age

integer

Completed years of life on target_date.

data.year_start

string

data.year_end

string

data.ascendant_sign

string

data.ascendant_sign_index

integer

data.profected_house

integer

data.profected_sign

string

data.profected_sign_index

integer

data.year_lord

string

Lord of the year: traditional ruler of the profected sign (Ptolemy, Tetrabiblos I.17).

data.year_lord_natal

YearLordNatalSchema | null

Where the year lord sits in the birth chart.

data.natal_planets_in_profected_sign

array[object]

data.natal_planets_in_profected_sign[].planet

string

data.natal_planets_in_profected_sign[].degree_in_sign

number

data.natal_planets_in_profected_sign[].is_retrograde

boolean

data.upcoming_years

array[object]

This year and the next eleven.

data.upcoming_years[].age

integer

data.upcoming_years[].year_start

string

Birthday that starts this profection year.

data.upcoming_years[].year_end

string

Next birthday (exclusive).

data.upcoming_years[].profected_house

integer

Whole-sign house activated this year, counted from the Ascendant.

data.upcoming_years[].profected_sign

string

data.upcoming_years[].profected_sign_index

integer

data.upcoming_years[].year_lord

string

Traditional ruler of the profected sign (lord of the year).

data.house_system_note

string

Errors

api_key_invalid

Invalid API key format.

api_key_missing

API key is missing. Include it in the Authorization header as 'Bearer YOUR_KEY'.

api_key_not_found

The provided API key was not found. Verify the key in your Asterwise dashboard.

api_key_revoked

This API key has been revoked.

burst_limit_exceeded

Too many requests per minute. Please slow down.

internal_error

Something went wrong on our end. Please try again, or contact [email protected] if the problem persists. Include your request_id when contacting support.

ip_rate_limit_exceeded

Too many requests from this IP address. Please slow down.

monthly_usage_limit_exceeded

Monthly API call limit reached. Upgrade your plan to continue.

payload_too_large

Request body exceeds maximum allowed size of 64KB.

subscription_expired

Your subscription has expired. Please renew at asterwise.com/dashboard to continue.

validation_error

The request couldn't be processed. See the 'details' field for specific field-level issues.

Related endpoints

• Western Secondary Progressions
• Western Solar Arc Directions

Request

POST·application/json

curl

curl -X POST "https://api.asterwise.com/v1/western/profections" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Arjun Mehta","date":"1985-11-12","time":"06:45","latitude":19.076,"longitude":72.8777,"timezone":"Asia/Kolkata","target_date":"2026-01-01"}'

Python

import asterwise
from asterwise.api.western_astrology_api import WesternAstrologyApi
from asterwise.models.profections_request import ProfectionsRequest

configuration = asterwise.Configuration(
    host="https://api.asterwise.com",
    access_token="YOUR_API_KEY",
)

request = ProfectionsRequest(
    name="Arjun Mehta",
    date="1985-11-12",
    time="06:45",
    latitude=19.076,
    longitude=72.8777,
    timezone="Asia/Kolkata",
    target_date="2026-01-01",
)

with asterwise.ApiClient(configuration) as client:
    api = WesternAstrologyApi(client)
    result = api.western_profections(profections_request=request)
    print(result)

TypeScript

import { createClient, createConfig, westernProfections } from 'asterwise';

const client = createClient(createConfig({
  baseUrl: 'https://api.asterwise.com',
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
}));

const result = await westernProfections({
  client,
  body: {
      "name": "Arjun Mehta",
      "date": "1985-11-12",
      "time": "06:45",
      "latitude": 19.076,
      "longitude": 72.8777,
      "timezone": "Asia/Kolkata",
      "target_date": "2026-01-01"
  },
});

console.log(result.data);

Response

200 OK·application/jsonsigned

{
  "success": true,
  "message": "success",
  "data": {
    "target_date": "2026-01-01",
    "age": 40,
    "year_start": "2025-11-12",
    "year_end": "2026-11-12",
    "ascendant_sign": "Scorpio",
    "ascendant_sign_index": 7,
    "profected_house": 5,
    "profected_sign": "Pisces",
    "profected_sign_index": 11,
    "year_lord": "Jupiter",
    "year_lord_natal": {
      "sign": "Aquarius",
      "sign_index": 10,
      "degree_in_sign": 9.616,
      "whole_sign_house": 4,
      "house": 3,
      "is_retrograde": false,
      "dignity": "peregrine"
    },
    "natal_planets_in_profected_sign": [],
    "upcoming_years": [
      {
        "age": 40,
        "year_start": "2025-11-12",
        "year_end": "2026-11-12",
        "profected_house": 5,
        "profected_sign": "Pisces",
        "profected_sign_index": 11,
        "year_lord": "Jupiter"
      },
      {
        "age": 41,
        "year_start": "2026-11-12",
        "year_end": "2027-11-12",
        "profected_house": 6,
        "profected_sign": "Aries",
        "profected_sign_index": 0,
        "year_lord": "Mars"
      },
      "... and 10 more items"
    ],
    "house_system_note": "Profections use whole-sign houses counted from the Ascendant sign; 'house' inside year_lord_natal is the natal house in…"
  }
}