Natal Planets

Endpoint POST https://starsapi.com/api/v3/western/natal/planets

Overview

Returns tropical positions for 15 celestial bodies and points: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, Chiron, Black Moon Lilith (Mean Apogee), North Node, South Node, and Part of Fortune. Each body includes absolute longitude, sign placement, degree within sign (both decimal and DMS), daily speed, retrograde flag, element, modality, modern/traditional ruler, and house placement.

The Part of Fortune is a calculated Arabic lot using the classical formula: ASC + Moon − Sun for day charts, ASC + Sun − Moon for night charts. It carries an is_calculated_point: true flag and shows which formula was applied.

Node type: defaults to true (True/Osculating Node), which is standard in Western astrology. Pass node_type: "mean" for Mean Node, or "both" to receive both.

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	Birth second. Default `0`.
`latitude`	number	Yes	Decimal degrees (−90 to 90).
`longitude`	number	Yes	Decimal degrees (−180 to 180).
`timezone`	string	Yes	IANA timezone (e.g. `America/New_York`).
`house_system`	string	No	Any of 25 supported systems. Default `placidus`. Affects house placement of planets. See house systems.
`node_type`	string	No	`true`, `mean`, or `both`. Default `true`.

Response shape

`data.ascendant` / `data.midheaven`

Field	Type	Description
`longitude`	number	Absolute tropical longitude (0–360).
`longitude_dms`	string	Degrees, minutes, seconds notation.
`sign`	string	Zodiac sign name.
`sign_number`	integer	Sign number (1=Aries through 12=Pisces).
`sign_symbol`	string	Unicode zodiac symbol.
`degree_in_sign`	number	Decimal degree within sign (0–29.99).
`degree_in_sign_dms`	string	DMS degree within sign.

`data.planets.{name}`

Each of the 15 bodies includes:

Field	Type	Description
`longitude`	number	Absolute tropical longitude (0–360).
`longitude_dms`	string	DMS notation.
`sign`	string	Zodiac sign.
`sign_number`	integer	1–12.
`sign_symbol`	string	Unicode symbol.
`degree_in_sign`	number	0–29.99.
`degree_in_sign_dms`	string	DMS within sign.
`speed`	number	Daily motion in degrees (negative = retrograde).
`is_retrograde`	boolean	True if planet is in retrograde motion.
`element`	string	`Fire`, `Earth`, `Air`, or `Water`.
`modality`	string	`Cardinal`, `Fixed`, or `Mutable`.
`ruler_modern`	string	Modern ruler of the sign (includes Uranus, Neptune, Pluto).
`ruler_traditional`	string	Traditional ruler (classical 7 planets only).
`house`	integer	House number (1–12) under the selected house system.

Part of Fortune additionally includes is_calculated_point: true and formula showing which formula was used.

`data.total_planets`

Integer count of bodies returned (currently 15).

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	A required field is absent.
400	`INVALID_DATE`	Invalid calendar date or year outside range.
400	`INVALID_TIME`	Hour/minute/second outside valid range.
400	`INVALID_TIMEZONE`	Not a valid IANA identifier.
400	`INVALID_COORDINATE`	Latitude or longitude out of range.
500	`EPHEMERIS_ERROR`	Swiss Ephemeris computation failed.

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/western/natal/planets" \
  -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"
    }'

const response = await fetch(
  'https://starsapi.com/api/v3/western/natal/planets',
  {
    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'
    })
  }
);
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/planets',
    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'
    }
)
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',
];

$ch = curl_init('https://starsapi.com/api/v3/western/natal/planets');
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/planets'),
    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',
    }),
  );
  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/planets"
    )!)
    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"
        }
        """.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"
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/western/natal/planets")
        .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",
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/western/natal/planets",
        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/planets')
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'
}

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": {
    "ascendant": {
      "longitude": 179.9737,
      "longitude_dms": "179°58'25\"",
      "sign": "Virgo",
      "sign_number": 6,
      "sign_symbol": "♍",
      "degree_in_sign": 29.9737,
      "degree_in_sign_dms": "29°58'25\""
    },
    "midheaven": {
      "longitude": 89.9726,
      "longitude_dms": "89°58'22\"",
      "sign": "Gemini",
      "sign_number": 3,
      "sign_symbol": "♊",
      "degree_in_sign": 29.9726,
      "degree_in_sign_dms": "29°58'22\""
    },
    "planets": {
      "Sun": {
        "longitude": 59.0927,
        "longitude_dms": "59°5'34\"",
        "sign": "Taurus",
        "sign_number": 2,
        "sign_symbol": "♉",
        "degree_in_sign": 29.0927,
        "degree_in_sign_dms": "29°05'34\"",
        "speed": 0.962639,
        "is_retrograde": false,
        "element": "Earth",
        "modality": "Fixed",
        "ruler_modern": "Venus",
        "ruler_traditional": "Venus",
        "house": 9
      },
      "Part of Fortune": {
        "longitude": 122.348,
        "sign": "Leo",
        "degree_in_sign_dms": "2°20'53\"",
        "house": 11,
        "is_calculated_point": true,
        "formula": "ASC + Moon - Sun (day)"
      }
    },
    "total_planets": 15
  },
  "meta": {
    "endpoint": "/api/v3/western/natal/planets",
    "version": "3.0",
    "response_time_ms": 12
  }
}