House Cusps

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

Overview

Returns the 12 house cusps plus Ascendant and Midheaven (MC) for any of the 25 Swiss Ephemeris house systems. The Ascendant and MC are astronomical points (horizon and meridian) — they remain identical across all house systems. What changes between systems is the intermediate cusps (houses 2, 3, 5, 6, 8, 9, 11, 12).

Each cusp includes absolute tropical longitude, sign, sign number, and degree within sign in both decimal and DMS formats.

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 (−90 to 90).
`longitude`	number	Yes	Decimal degrees (−180 to 180).
`timezone`	string	Yes	IANA timezone.
`house_system`	string	No	Default `placidus`. All 25 systems accepted. See full list.
`node_type`	string	No	`true`, `mean`, or `both`. Default `true`.
`compare_systems`	array	No	Array of additional house system names to compare. See below.

Comparing house systems

Pass compare_systems to compute cusps for multiple house systems in a single call:

{
  "house_system": "placidus",
  "compare_systems": ["koch", "whole_sign", "equal"]
}

The response includes a comparison object keyed by system name, each containing house_cusps, ascendant, and midheaven. Useful for apps that let users toggle between systems without re-calling the API.

Response shape

`data.house_system`

Human-readable name of the primary house system (e.g. "Placidus", "Whole Sign").

`data.house_cusps.{1–12}`

Each cusp object:

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 zodiac symbol.
`degree_in_sign`	number	0–29.99.
`degree_in_sign_dms`	string	DMS within sign.

`data.comparison` (optional)

Only present when compare_systems is sent. Object keyed by system name, each with house_cusps, ascendant, midheaven.

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.
400	`INVALID_PARAM`	Invalid `house_system`.
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/houses" \
  -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"
    }'

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

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

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

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

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": {
    "house_system": "Placidus",
    "ascendant": {
      "longitude": 179.9737,
      "sign": "Virgo",
      "sign_number": 6,
      "degree_in_sign_dms": "29°58'25\""
    },
    "midheaven": {
      "longitude": 89.9726,
      "sign": "Gemini",
      "sign_number": 3,
      "degree_in_sign_dms": "29°58'22\""
    },
    "house_cusps": {
      "1":  { "longitude": 179.9737, "sign": "Virgo",       "sign_number": 6,  "degree_in_sign_dms": "29°58'25\"" },
      "2":  { "longitude": 207.9953, "sign": "Libra",       "sign_number": 7,  "degree_in_sign_dms": "27°59'51\"" },
      "3":  { "longitude": 238.4344, "sign": "Scorpio",     "sign_number": 8,  "degree_in_sign_dms": "28°26'04\"" },
      "4":  { "longitude": 269.9726, "sign": "Sagittarius", "sign_number": 9,  "degree_in_sign_dms": "29°58'22\"" },
      "5":  { "longitude": 301.5106, "sign": "Aquarius",    "sign_number": 11, "degree_in_sign_dms": "1°30'38\""  },
      "6":  { "longitude": 331.9475, "sign": "Pisces",      "sign_number": 12, "degree_in_sign_dms": "1°56'51\""  },
      "7":  { "longitude": 359.9737, "sign": "Pisces",      "sign_number": 12, "degree_in_sign_dms": "29°58'25\"" },
      "8":  { "longitude": 27.9953,  "sign": "Aries",       "sign_number": 1,  "degree_in_sign_dms": "27°59'51\"" },
      "9":  { "longitude": 58.4344,  "sign": "Taurus",      "sign_number": 2,  "degree_in_sign_dms": "28°26'04\"" },
      "10": { "longitude": 89.9726,  "sign": "Gemini",      "sign_number": 3,  "degree_in_sign_dms": "29°58'22\"" },
      "11": { "longitude": 121.5106, "sign": "Leo",         "sign_number": 5,  "degree_in_sign_dms": "1°30'38\""  },
      "12": { "longitude": 151.9475, "sign": "Virgo",       "sign_number": 6,  "degree_in_sign_dms": "1°56'51\""  }
    }
  },
  "meta": {
    "endpoint": "/api/v3/western/natal/houses",
    "version": "3.0",
    "response_time_ms": 3
  }
}