POST · WESTERN

Birth Details

Endpoint POST https://starsapi.com/api/v3/western/birth-details

Overview

Returns resolved birth details for Western (tropical) astrology — date, time, weekday, gender, name, location, timezone offset with abbreviation (e.g. IST, EDT, PST), zodiac system, house system, and node type. This endpoint performs no astrological computation — no planets, no houses, no aspects. It exists so your app can confirm and display the native’s birth data independently of any chart calculations.

DST-aware: the timezone_offset and timezone_abbr are computed for the actual birth date/time, so summer births in New York correctly return EDT / -04:00 while winter births return EST / -05:00. Arizona (America/Phoenix) correctly returns MST / -07:00 year-round.

Typical app flow: submit /birth-details on form submit to confirm the input, then call any compute endpoint (planets, houses, aspects, etc.) for actual chart data.

Authentication

MethodExample
Header (recommended)X-Api-Key: am_live_xxxxxxxxxxxx
BearerAuthorization: Bearer am_live_xxxxxxxxxxxx
Query?api_key=am_live_xxxxxxxxxxxx

Request body

FieldTypeRequiredDescription
yearintegerYesBirth year (1800–2400).
monthintegerYesBirth month (1–12).
dayintegerYesBirth day (1–31).
hourintegerYesBirth hour (0–23, 24-hour format).
minuteintegerYesBirth minute (0–59).
secondintegerNoBirth second (0–59). Default 0.
latitudenumberYesSigned decimal latitude (−90 to 90). Positive = North.
longitudenumberYesSigned decimal longitude (−180 to 180). Positive = East.
timezonestringYesIANA timezone identifier (e.g. Asia/Kolkata, America/New_York).
namestringNoNative’s name. Echoed in data.birth_details.name.
genderstringNomale, female, or other. Omitted from response if not sent.
placestringNoBirth place label. Echoed in data.location.place.
house_systemstringNoHouse system to echo. Default placidus. See supported systems.
node_typestringNotrue, mean, or both. Default true. Western astrologers typically use True Node.

Supported house systems

All 25 Swiss Ephemeris house systems are supported. Pass any of the following as house_system:

ValueSystem nameSE code
placidusPlacidusP
kochKochK
porphyryPorphyryO
regiomontanusRegiomontanusR
campanusCampanusC
equalEqual (Ascendant)E
whole_signWhole SignW
meridian / axialMeridian / AxialX
morinusMorinusM
alcabitiusAlcabitiusB
topocentricPolich-Page (Topocentric)T
vehlow_equalVehlow EqualV
krusinskiKrusinski-PisaU
equal_mcEqual (MC)D
equal_ariesEqual (1=Aries)N
sripatiSripatiS
horizontal / azimuthalHorizontal / AzimuthalH
gauquelinGauquelin SectorsG
apcAPC HousesY
pullen_sdPullen SD (Sinusoidal Delta)L
pullen_srPullen SR (Sinusoidal Ratio)Q
sunshineSunshine (Treindl)I
carterCarter Poli-EquatorialF

Response shape

data.birth_details

FieldTypeDescription
datestringResolved birth date (YYYY-MM-DD).
timestringResolved birth time (HH:MM:SS).
daystringWeekday name (e.g. Sunday).
namestringEchoed name, or absent if not sent.
genderstringmale, female, or other. Absent if not sent.

data.location

FieldTypeDescription
latitudenumberDecimal degrees as submitted.
longitudenumberDecimal degrees as submitted.
placestringEchoed place label, or absent if not sent.

Other data fields

FieldTypeDescription
timezonestringIANA timezone as submitted (e.g. Asia/Kolkata).
timezone_offsetstringUTC offset for the birth date/time (e.g. +05:30, -04:00). DST-aware.
timezone_abbrstringTimezone abbreviation for the birth date/time (e.g. IST, EDT, PST). DST-aware.
zodiacstringAlways "tropical" for Western endpoints.
house_systemstringEchoed house system (default placidus). Validated against the 25 supported systems.
node_typestringEchoed node type: true, mean, or both. Default true.

meta

FieldTypeDescription
endpointstringRequest path.
versionstringAPI version (3.0).
response_time_msintegerServer processing time in milliseconds.
timestampstringISO 8601 response timestamp.
credits_remainingintegerRemaining API credits for this billing period.
request_idstringUnique request identifier for debugging.

No zodiac or house_system in meta — these are in data since they describe the chart context, not the API response.

Errors

HTTPCodeCause
400MISSING_FIELDA required field is absent.
400INVALID_DATEYear/month/day combination does not resolve to a real calendar date, or year outside 1800–2400.
400INVALID_TIMEHour, minute, or second outside valid range.
400INVALID_TIMEZONETimezone string is not a valid IANA identifier, or a numeric offset was sent.
400INVALID_COORDINATELatitude outside −90–90 or longitude outside −180–180.
400INVALID_PARAMInvalid house_system value.
400INVALID_JSONRequest body is not valid JSON.
401UNAUTHORIZEDMissing or invalid API key.
405METHOD_NOT_ALLOWEDRequest method is not POST.

See also

  • Natal Planets — 15 tropical positions (Sun–Pluto, Chiron, Lilith, Nodes, Part of Fortune)
  • Planets Advanced — dignities, combust/cazimi, sect, mutual reception
  • Houses — 25 house systems with compare feature
  • Aspects — natal aspects with custom orbs, phase, longitude
  • Chart — signed chart image URL with branding
  • Chart Image — direct PNG rendering
  • Authentication — keys, headers, origin whitelisting
  • Errors reference — universal error codes