Fixed Stars List

What is the Fixed Stars List endpoint?

You need the catalog of fixed star identifiers the system supports before you can query individual star positions. The Fixed Stars List endpoint takes only your API key and returns an array of 721 fixed star names you can then pass to the Fixed Stars Details endpoint to retrieve calculated positions for any subset.

This endpoint is part of the Natal Chart API.

Why does this endpoint exist?

You are building a fixed-stars feature and you do not know which star identifiers the system supports. The catalog covers 721 named stars: well-known ones like Sirius, Aldebaran, and Algol, plus less-common entries identified by Bayer designations or catalog numbers. This endpoint exposes the full identifier set so your UI can offer a searchable dropdown, an autocomplete, or a "browse all" view without hard-coding any star names client-side.

What inputs does it need?

You pass only your API key. Unlike most Natal Chart API endpoints, this one takes no birth data. The catalog is static, so a single call returns the same list regardless of date, time, or location. Authentication uses a Bearer token in the Authorization header alongside the body's api_key field.

That is the entire payload. Cache the response on your side; the catalog is stable, so a single fetch covers all subsequent feature work.

What does the response data look like?

You get an envelope with status, code, message, and data. The data field is a flat array of 721 string identifiers, sorted alphabetically. Each string is the canonical name you pass to the Fixed Stars Details endpoint to query that star's position.

Identifiers cover three naming conventions: traditional names ("Sirius", "Aldebaran", "Regulus"), Bayer designations ("Alphard", "Markab"), and catalog references ("A3558", "109Vir"). Your UI can group or filter by naming convention, or simply present the full list as a searchable picker.

What does a real response look like?

Below is a slice of the response showing both ends of the alphabetical order. The full payload contains 721 entries, sorted alphabetically. Cache the array client-side after the first fetch so subsequent UI features (search, autocomplete, validation) work without additional round trips.

{
  "status": "success",
  "code": 200,
  "message": "Request successful",
  "data": [
    "109Vir",
    "A3558",
    "Abhijit",
    "Acamar",
    "Achernar",
    "Acrux",
    "Aculeus",
    "...truncated, 711 more entries...",
    "ZubenElgenubi",
    "ZubenEschamali",
    "Zubeneshamali",
    "ZubenHakrabi"
  ]
}

What can you build with this endpoint?

You use the Fixed Stars List as the lookup catalog that powers any UI involving fixed stars. The catalog stays the same across requests, so a single call covers all subsequent feature work in your application.

1. Searchable star picker. Render the array as an autocomplete or combobox so users select stars by name. Combine with Fixed Stars Details to fetch calculated positions for the selection.
2. Cached client-side catalog. Fetch once on app boot, store in localStorage or IndexedDB, and reuse for every star-related feature without round-tripping to the API.
3. Fixed-star filter UI. Pre-filter the list to only "named" stars (Sirius, Aldebaran, etc.) for beginner UI, while exposing the full 721-entry catalog for advanced practitioners.
4. Validation layer. Use the catalog as an allowlist when accepting user-submitted star names, rejecting unknown identifiers before they reach the Fixed Stars Details endpoint.

How accurate is the calculation?

You are not computing anything here. This endpoint is a static catalog lookup, so accuracy questions do not apply in the usual sense. The catalog itself reflects the supported identifier set across the underlying Swiss Ephemeris fixed-star database, so any name returned by this endpoint will resolve correctly when passed to Fixed Stars Details.

If a name appears in the list but Fixed Stars Details returns an error for it, that is a data inconsistency worth reporting through the dashboard support channel.

How does this relate to the parent API?

You are using this endpoint as a setup step before querying Fixed Stars Details. This endpoint complements the Natal Chart API by providing the canonical identifier catalog needed to drive star-specific feature UI.

Most Natal Chart endpoints return calculated chart data tied to a birth instant. This one is different: it returns a static reference list. Pair it with Fixed Stars Details (the calculation endpoint) for any UI that needs to surface or compute fixed star positions in a natal chart.

Summary

The Fixed Stars List endpoint returns the full catalog of 721 supported fixed star identifiers as a flat array. It takes only your API key, has no birth data input, and the response is stable so you can cache it client-side. Use it whenever your product needs a star picker, an autocomplete, or a validation allowlist before calling the Fixed Stars Details endpoint for actual positions.