ephemeris

Fixed star position calculations

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%.

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

Query parameters

output_modestring nullable

Deprecated: use preset+format. Accepts full|simple|llm.

formatstring

Headers

authorizationstring nullable
X-API-Keystring nullable
X-OpenEphemeris-API-Keystring nullable
apikeystring nullable

Request body

latitudenumber

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.

longitudenumber

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_magnitudenumber

Filter stars by maximum magnitude

min_magnitudenumber

Filter stars by minimum magnitude (lower = brighter)

orbnumber

Conjunction orb in degrees. Default 1.0.

star_groupsstring[]

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_namesstring[]

Specific fixed stars to calculate. Accepts catalog/display names (e.g., 'Regulus') and catalog ids (e.g., 'regulus', 'deneb_algedi').

strict_catalog_idsboolean

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.

Example request

{
  "date_time": {
    "iso": "2023-12-07T15:30:00Z"
  },
  "latitude": 32.7767,
  "longitude": -96.797,
  "orb": 1,
  "star_names": [
    "Regulus",
    "Spica",
    "Aldebaran"
  ]
}

Response

Successful Response

anglesobject

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_timestring date-time required

Timestamp of calculation

julian_daynumber double required

Julian Day used for calculation

metadataobject

Additional calculation metadata

successboolean

Calculation success status

Changes

No recorded changes to this operation across all 1 revision of this API.