Fixed Stars

Endpoint POST https://starsapi.com/api/v3/western/natal/fixed-stars

Overview

Checks conjunctions between natal planets and 30 major fixed stars. Star positions are precession-corrected to the birth year (J2000.0 epoch + annual precession of ~50.29″ per year). Also checks conjunctions with the Ascendant and Midheaven.

Fixed star conjunctions are considered active only at very tight orbs — the default is 1°, configurable up to 3°. Results are sorted by orb (tightest first).

The catalog includes the four Royal Stars (Regulus, Aldebaran, Antares, Fomalhaut), Algol, Sirius, Spica, Vega, and 22 other astrologically significant stars. Each star includes traditional planetary nature and keywords.

Authentication

Method	Example
Header (recommended)	`X-Api-Key: am_live_xxxxxxxxxxxx`
Bearer	`Authorization: Bearer am_live_xxxxxxxxxxxx`
Query	`?api_key=am_live_xxxxxxxxxxxx`

Request body

Field	Type	Required	Description
`year`	integer	Yes	Birth year (1800–2400).
`month`	integer	Yes	Birth month (1–12).
`day`	integer	Yes	Birth day.
`hour`	integer	Yes	Birth hour (0–23).
`minute`	integer	Yes	Birth minute (0–59).
`second`	integer	No	Default `0`.
`latitude`	number	Yes	Decimal degrees.
`longitude`	number	Yes	Decimal degrees.
`timezone`	string	Yes	IANA timezone.
`house_system`	string	No	Default `placidus`.
`node_type`	string	No	`true`, `mean`, or `both`. Default `true`.
`orb`	number	No	Conjunction orb in degrees (0–3). Default `1`. Fixed stars are traditionally read at very tight orbs.

Response shape

`data.conjunctions[]`

Field	Type	Description
`planet`	string	Planet or point name (includes `"Ascendant"`, `"Midheaven"`).
`planet_longitude`	number	Planet’s tropical longitude.
`star`	string	Fixed star name.
`star_longitude`	number	Star’s precession-corrected tropical longitude.
`star_sign`	string	Zodiac sign of the star.
`star_degree`	string	DMS degree within sign.
`orb`	number	Actual angular separation in degrees.
`magnitude`	number	Visual magnitude (lower = brighter; Sirius = −1.5).
`nature`	string	Traditional planetary nature (e.g. `"Mars-Jupiter"`).
`keywords`	string	Astrological keywords for this star.

Other fields

Field	Type	Description
`total_conjunctions`	integer	Number of conjunctions found.
`orb_used`	number	Orb applied (degrees).
`precession_offset`	number	Degrees of precession applied from J2000.0 to birth year.
`star_epoch`	string	Description of the epoch correction.
`stars_checked`	integer	Total stars in the catalog (30).

Star catalog (30 stars)

Positions shown are approximate J2000.0 tropical longitudes. The API applies precession correction for the birth year.

Star	~J2000 position	Mag	Nature	Keywords
Regulus ★	29°50′ Leo	1.4	Mars-Jupiter	Royal star — success, fame, power
Aldebaran ★	9°47′ Gemini	0.9	Mars	Royal star — integrity, honor, eloquence
Antares ★	9°46′ Sagittarius	1.1	Mars-Jupiter	Royal star — obsessive, reckless courage
Fomalhaut ★	3°52′ Pisces	1.2	Venus-Mercury	Royal star — fame, idealism, mysticism
Algol	26°10′ Taurus	2.1	Saturn-Jupiter	Intensity, transformation, danger
Sirius	14°05′ Cancer	−1.5	Jupiter-Mars	Ambition, fame, pride, wealth
Spica	23°50′ Libra	1.0	Venus-Mars	Brilliance, wealth, honor
Vega	15°19′ Capricorn	0.0	Venus-Mercury	Idealism, refinement, hope
Arcturus	24°14′ Libra	0.0	Jupiter-Mars	Fortune through travel, prosperity
Betelgeuse	28°45′ Gemini	0.4	Mars-Mercury	Martial honors, fortune

★ = Royal Star. Full catalog of 30 stars checked in every call. See the API response for all star positions.

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	Required field absent.
400	`INVALID_DATE`	Invalid date.
400	`INVALID_TIME`	Time outside range.
400	`INVALID_TIMEZONE`	Not valid IANA.
400	`INVALID_COORDINATE`	Out of range.
400	`INVALID_PARAM`	Invalid `house_system` or `orb` outside 0–3.
500	`EPHEMERIS_ERROR`	Computation failed.

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/western/natal/fixed-stars" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "house_system": "placidus",
        "node_type": "true",
        "orb": 1
    }'

const response = await fetch(
  'https://starsapi.com/api/v3/western/natal/fixed-stars',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      year: 1990,
      month: 5,
      day: 20,
      hour: 14,
      minute: 30,
      second: 0,
      latitude: 28.6139,
      longitude: 77.209,
      timezone: 'Asia/Kolkata',
      house_system: 'placidus',
      node_type: 'true',
      orb: 1
    })
  }
);
const result = await response.json();

if (result.success) {
  console.log(result.data);
}

import requests
import os

response = requests.post(
    'https://starsapi.com/api/v3/western/natal/fixed-stars',
    headers={'X-Api-Key': os.environ['STARSAPI_KEY']},
    json={
        'year': 1990,
        'month': 5,
        'day': 20,
        'hour': 14,
        'minute': 30,
        'second': 0,
        'latitude': 28.6139,
        'longitude': 77.209,
        'timezone': 'Asia/Kolkata',
        'house_system': 'placidus',
        'node_type': 'true',
        'orb': 1
    }
)
result = response.json()

if result['success']:
    print(result['data'])

<?php
$payload = [
    'year' => 1990,
    'month' => 5,
    'day' => 20,
    'hour' => 14,
    'minute' => 30,
    'second' => 0,
    'latitude' => 28.6139,
    'longitude' => 77.209,
    'timezone' => 'Asia/Kolkata',
    'house_system' => 'placidus',
    'node_type' => 'true',
    'orb' => 1,
];

$ch = curl_init('https://starsapi.com/api/v3/western/natal/fixed-stars');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . getenv('STARSAPI_KEY'),
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['success']) {
    print_r($data['data']);
}

import 'package:http/http.dart' as http;
import 'dart:convert';

Future<Map<String, dynamic>> getAscendant() async {
  final response = await http.post(
    Uri.parse('https://starsapi.com/api/v3/western/natal/fixed-stars'),
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'year': 1990,
      'month': 5,
      'day': 20,
      'hour': 14,
      'minute': 30,
      'second': 0,
      'latitude': 28.6139,
      'longitude': 77.209,
      'timezone': 'Asia/Kolkata',
      'house_system': 'placidus',
      'node_type': 'true',
      'orb': 1,
    }),
  );
  return jsonDecode(response.body);
}

import Foundation

func getAscendant() async throws -> [String: Any] {
    var request = URLRequest(url: URL(string:
        "https://starsapi.com/api/v3/western/natal/fixed-stars"
    )!)
    request.httpMethod = "POST"
    request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-Api-Key")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = """
        {
            "year": 1990,
            "month": 5,
            "day": 20,
            "hour": 14,
            "minute": 30,
            "second": 0,
            "latitude": 28.6139,
            "longitude": 77.209,
            "timezone": "Asia/Kolkata",
            "house_system": "placidus",
            "node_type": "true",
            "orb": 1
        }
        """.data(using: .utf8)

    let (data, _) = try await URLSession.shared.data(for: request)
    return try JSONSerialization.jsonObject(with: data) as! [String: Any]
}

import okhttp3.*
import org.json.JSONObject

val client = OkHttpClient()
val JSON = "application/json; charset=utf-8".toMediaType()

fun getAscendant(callback: (JSONObject) -> Unit) {
    val payload = """
    {
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "house_system": "placidus",
        "node_type": "true",
        "orb": 1
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/western/natal/fixed-stars")
        .addHeader("X-Api-Key", "YOUR_API_KEY")
        .post(payload.toRequestBody(JSON))
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onResponse(call: Call, response: Response) {
            callback(JSONObject(response.body!!.string()))
        }
        override fun onFailure(call: Call, e: java.io.IOException) {
            e.printStackTrace()
        }
    })
}

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    payload, _ := json.Marshal(map[string]interface{}{
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "house_system": "placidus",
        "node_type": "true",
        "orb": 1,
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/western/natal/fixed-stars",
        bytes.NewBuffer(payload))
    req.Header.Set("X-Api-Key", os.Getenv("STARSAPI_KEY"))
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result["data"])
}

require 'net/http'
require 'json'

uri = URI('https://starsapi.com/api/v3/western/natal/fixed-stars')
payload = {
  'year' => 1990,
  'month' => 5,
  'day' => 20,
  'hour' => 14,
  'minute' => 30,
  'second' => 0,
  'latitude' => 28.6139,
  'longitude' => 77.209,
  'timezone' => 'Asia/Kolkata',
  'house_system' => 'placidus',
  'node_type' => 'true',
  'orb' => 1
}

req = Net::HTTP::Post.new(uri)
req['X-Api-Key'] = ENV['STARSAPI_KEY']
req['Content-Type'] = 'application/json'
req.body = payload.to_json

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
res = http.request(req)

data = JSON.parse(res.body)
puts data['data'] if data['success']

200 RESPONSE

{
  "status": 200,
  "success": true,
  "data": {
    "conjunctions": [
      {
        "planet": "Sun",
        "planet_longitude": 59.0927,
        "star": "Betelgeuse",
        "star_longitude": 58.3103,
        "star_sign": "Taurus",
        "star_degree": "28°18'37\"",
        "orb": 0.7824,
        "magnitude": 0.4,
        "nature": "Mars-Mercury",
        "keywords": "Martial honors, preferment, fortune"
      },
      {
        "planet": "Neptune",
        "planet_longitude": 284.4182,
        "star": "Vega",
        "star_longitude": 285.1303,
        "star_sign": "Capricorn",
        "star_degree": "15°07'49\"",
        "orb": 0.8545,
        "magnitude": 0.0,
        "nature": "Venus-Mercury",
        "keywords": "Idealism, refinement, hope, changeability"
      }
    ],
    "total_conjunctions": 3,
    "orb_used": 1,
    "precession_offset": -0.1397,
    "star_epoch": "J2000.0 + -10yr precession",
    "stars_checked": 30
  },
  "meta": { "endpoint": "/api/v3/western/natal/fixed-stars", "version": "3.0" }
}