---
title: "Fixed star position calculations"
method: POST
path: "/ephemeris/fixed-stars"
tags: ["ephemeris"]
---

# Fixed star position calculations

`POST /ephemeris/fixed-stars`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/ephemeris/fixed-stars`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-OpenEphemeris-API-Key`
  - API key in header `X-API-Key`
  - API key in header `X-Service-Key`

Calculate positions for fixed stars and galactic reference points at a specific moment. Supports individual names, predefined groups (royal_stars, behenian, ptolemaic, 15_fixed_stars, galactic), and magnitude filtering. Discover the current group list at GET /catalogs/fixed-stars/groups. Returns ecliptic coordinates, proper motion, and metadata for each entry. 🤖 AI-optimized output available — add `format=llm` to reduce payload ~60%.

## Query parameters

- `output_mode` string, nullable
- `format` string

## Headers

- `authorization` string, nullable
- `X-API-Key` string, nullable
- `X-OpenEphemeris-API-Key` string, nullable
- `apikey` string, nullable

## Request body

- FixedStarsCalculationRequest: Request for fixed star position calculations.
  - `date_time` DateTimeInput, required: Date/time input in ISO-8601, component, or Julian day form. A value that states a clock time must also state its zone, either as a suffix on the string or via the `timezone` field below.
    - `components` object: Date/time components (year, month, day, and optionally hour, minute, second). If hour/minute are present, pass `timezone` alongside them; without it the request is rejected with 400 ambiguous_datetime. Omit the clock entirely and the date resolves to 12:00 UTC.
    - `iso` string: ISO-8601 datetime (supported range 1550–2650 CE, JPL DE440). If it states a clock time it must carry its zone: either a 'Z'/±HH:MM suffix on the string ("1987-07-15T09:01:00-05:00"), or a `timezone` passed alongside it. A zone-less clock time is rejected with 400 ambiguous_datetime — it is not read as UTC. A date-only value ("1987-07-15") has no clock to be ambiguous about and resolves to 12:00 UTC.
    - `julian_day` number, double: Julian Day Number (always UTC-based, so it needs no zone)
    - `timezone` TimezoneInput: Timezone input using IANA names or UTC offsets.
      - `fold_preference` 'earlier' | 'later': Which occurrence to use when the naive local datetime falls in a fall-back fold (a repeated hour): 'earlier' (default — first occurrence) or 'later'. Only meaningful for naive datetimes; the response reports datetime_status=ambiguous_fold either way so the ambiguity can be surfaced to the user.
      - `iana_name` string: IANA timezone name
      - `time_standard` 'auto' | 'standard' | 'daylight': How to interpret a naive local datetime when this zone is applied. 'auto' (default): resolve through the historical-correction overlay where one covers the region/era, then IANA tzdata. 'standard': force the zone's standard (non-daylight) offset — for callers who KNOW the recorded time was standard time regardless of what tzdata believes. 'daylight': force standard+1h. Forcing either marks the resolution tz_confidence=client_override. Ignored when the datetime carries its own Z/±HH:MM suffix or when utc_offset is used.
      - `utc_offset` number: UTC offset in hours
  - `latitude` number: Observer latitude in degrees (-90 to 90). Supply together with longitude to include the chart angles (ASC, MC, DSC, IC) in the conjunction scan. Without it, only planetary conjunctions are returned.
  - `longitude` number: Observer longitude in degrees (-180 to 180). Supply together with latitude to include the chart angles (ASC, MC, DSC, IC) in the conjunction scan.
  - `max_magnitude` number: Filter stars by maximum magnitude
  - `min_magnitude` number: Filter stars by minimum magnitude (lower = brighter)
  - `orb` number: Conjunction orb in degrees. Default 1.0.
  - `star_groups` string[]: Predefined star groups. Valid values are derived from the catalog: royal_stars, behenian, ptolemaic, 15_fixed_stars, galactic (the galactic and supergalactic poles and centers, the Galactic Anticenter, Great Attractor, Shapley and Virgo Supercluster centers). Discover them at GET /catalogs/fixed-stars/groups.
  - `star_names` string[]: Specific fixed stars to calculate. Accepts catalog/display names (e.g., 'Regulus') and catalog ids (e.g., 'regulus', 'deneb_algedi').
  - `strict_catalog_ids` boolean: When true, reject any unknown star/group identifier instead of silently skipping. Use /catalogs/fixed-stars and /catalogs/fixed-stars/groups to discover valid identifiers.

## Response `200`

Successful Response

- FixedStarsCalculationResponse: Response from fixed stars calculation endpoint.
  - `angles` object: The chart angle longitudes used for the conjunction scan, in degrees: asc, mc, dsc, ic. Present only when latitude and longitude were supplied. Returned so a caller can verify that a star-to-angle conjunction refers to the angle it expects.
  - `calculation_time` string, date-time, required: Timestamp of calculation
  - `julian_day` number, double, required: Julian Day used for calculation
  - `metadata` object: Additional calculation metadata
  - `stars` FixedStarCalculationResult[], required: Calculated star positions
    - `conjunctions` FixedStarConjunction[]: Chart points within orb of this star. Angles (ASC, MC, DSC, IC) appear only when latitude and longitude were supplied on the request; otherwise this lists planetary conjunctions only.
      - `point` string, required: The conjunct point: a planet name (e.g. 'Sun') or an angle ('ASC', 'MC', 'DSC', 'IC').
      - `point_longitude` number, required: Ecliptic longitude of the conjunct point in degrees (0-360).
      - `point_type` 'planet' | 'angle', required: Which kind of point this is: 'planet' or 'angle'. Angles are location-dependent; planets are not.
      - `separation` number, required: Absolute angular separation between the star and the point, in degrees.
    - `constellation` string: Constellation
    - `distance` number, required: Distance in AU
    - `latitude` number, required: Ecliptic latitude in degrees
    - `longitude` number, required: Ecliptic longitude in degrees
    - `magnitude` number: Visual magnitude
    - `name` string, required: Star name
    - `spectral_class` string: Spectral classification
    - `speed_latitude` number, required: Speed in latitude (degrees/day)
    - `speed_longitude` number, required: Speed in longitude (degrees/day)
    - `traditional_name` string: Traditional/alternative name
  - `success` boolean: Calculation success status

## Other responses

- `400`: Bad Request
- `422`: Unprocessable Entity - Invalid input format
- `500`: Internal Server Error

---

[API](https://skmtc.dev/openephemeris/apis/open-ephemeris-api.md) · [All operations](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/revisions/d195a769cb89?raw)