Fixed Stars Detailed Positions

What is the Fixed Stars Details endpoint?

You need calculated positions for specific fixed stars in a natal chart. The Fixed Stars Details endpoint takes birth data plus a comma-separated list of star identifiers and returns an object for each requested star with sign, exact ecliptic degree, house placement, element, and modality. Pair it with Fixed Stars List for the catalog.

This endpoint is part of the Natal Chart API.

Why does this endpoint exist?

You are layering fixed stars onto a natal chart and you need their exact ecliptic positions for the birth datetime. Precession shifts star positions about 1 degree every 72 years, so a per-chart calculation is more accurate than a static lookup. This endpoint computes positions for whichever stars you pick, in one call.

What inputs does it need?

You pass standard birth data plus a star_list parameter, a comma-separated string of star identifiers from the Fixed Stars List catalog. The catalog is your allowlist; any name not in the list will not resolve. Authentication uses a Bearer token in the Authorization header alongside the body's api_key field.

What does the response data look like?

You get an envelope with status, code, message, and data. The data array carries one entry per requested star, each shaped like the celestial body objects used by Planetary Positions. The same renderer you use for planets handles fixed stars without changes.

What does a real response look like?

Below is the response for a sample birth (24 May 2023, 14:40:43 IST, New Delhi) querying four well-known traditional stars: Sirius, Aldebaran, Algol, and Regulus. The endpoint returns one entry per requested star with the full set of position fields, ready to render on a wheel chart or feed into conjunction-detection logic.

{
  "status": "success",
  "code": 200,
  "message": "Request successful",
  "data": [
    {
      "name": "Sirius",
      "full_degree": "104.4753275",
      "sign": "Cancer",
      "sign_no": 4,
      "longitude": "14:0:31",
      "speed": "0.0000382",
      "is_retro": "false",
      "house": 10,
      "element": "Water",
      "modality": "Cardinal"
    },
    {
      "name": "Aldebaran",
      "full_degree": "70.0709879",
      "sign": "Gemini",
      "sign_no": 3,
      "longitude": "10:0:16",
      "speed": "0.0000382",
      "is_retro": "false",
      "house": 9,
      "element": "Air",
      "modality": "Mutable"
    },
    {
      "name": "Algol",
      "full_degree": "56.4312951",
      "sign": "Taurus",
      "sign_no": 2,
      "longitude": "26:0:53",
      "speed": "0.0000382",
      "is_retro": "false",
      "house": 8,
      "element": "Earth",
      "modality": "Fixed"
    },
    {
      "name": "Regulus",
      "full_degree": "150.1011545",
      "sign": "Virgo",
      "sign_no": 6,
      "longitude": "0:0:4",
      "speed": "0.0000382",
      "is_retro": "false",
      "house": 11,
      "element": "Earth",
      "modality": "Mutable"
    }
  ]
}

What can you build with this endpoint?

You use Fixed Stars Details whenever your product needs fixed-star placements rendered or analyzed alongside planets. The two-step flow (List then Details) keeps the catalog stable while per-chart calculations stay fresh.

1. Fixed-star wheel chart overlays. Plot user-selected stars on the zodiac wheel using full_degree, with distinct glyphs from planet bodies.
2. Conjunction-with-star detectors. Cross-reference each star's full_degree against planet positions to surface "Sun conjunct Sirius" style observations.
3. Royal-star highlights. Pre-fetch the four "royal stars" (Aldebaran, Regulus, Antares, Fomalhaut) and render them as a fixed panel.
4. User-curated star pickers. Combine with the Fixed Stars List autocomplete so users add or remove stars dynamically.

How accurate is the calculation?

You are computing ecliptic positions for celestial bodies that change very slowly. Star positions come from Swiss Ephemeris with NASA JPL ephemeris data, arc-second accurate, and adjusted for precession at the birth datetime. The speed field is near zero on every star (around 0.0000382 degrees per day), reflecting how slowly fixed stars shift relative to planets.

House placement follows the house_system parameter and your birth time, same as planets.

How does this relate to the parent API?

You are extending the standard birth chart with calculated fixed-star positions. This endpoint complements the Natal Chart API by providing per-chart positions for any subset of supported stars in the same shape Planetary Positions uses.

Pair with Fixed Stars List for the full flow: List provides the catalog (call once, cache), Details provides the calculation (call per chart). Combine with Planetary Positions for star-planet conjunction detection.

Summary

The Fixed Stars Details endpoint returns calculated positions for any subset of the 721 supported fixed stars. Pass standard birth data plus a star_list, and the response delivers star objects shaped like standard planet bodies. Pair with Fixed Stars List for the catalog and Planetary Positions for star-planet conjunction features.