Planetary Hours

Endpoint POST https://starsapi.com/api/v3/western/natal/planetary-hours

Overview

Determines which planetary hour the native was born in and returns the full 24-hour planetary hours table for the birth date. Planetary hours follow the Chaldean order (Saturn → Jupiter → Mars → Sun → Venus → Mercury → Moon) and are calculated from actual sunrise and sunset times at the birth location.

Day hours and night hours have unequal durations — in summer, day hours are longer; in winter, shorter. The response includes the exact duration in minutes for both day and night hours.

This endpoint does not require a house system or ephemeris computation — it uses only the Sun’s rise/set times for the given date and location.

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. Required for sunrise/sunset calculation.
`longitude`	number	Yes	Decimal degrees.
`timezone`	string	Yes	IANA timezone. Times are returned in this timezone.

Note: house_system and node_type are not applicable — this endpoint uses solar position only, no chart computation.

Response shape

`data.birth_hour`

Field	Type	Description
`ruler`	string	Planet ruling the birth hour (e.g. `"Sun"`, `"Venus"`).
`hour_number`	integer	1–24 (1 = first hour after sunrise).
`type`	string	`"day"` (hours 1–12) or `"night"` (hours 13–24).

Other fields

Field	Type	Description
`day_ruler`	string	Planet that rules the day of the week (Sunday = Sun, Monday = Moon, etc.).
`day_of_week`	string	Weekday name.
`sunrise`	string	Sunrise time in local timezone (`HH:MM:SS`).
`sunset`	string	Sunset time in local timezone.
`day_hour_duration_minutes`	number	Duration of each day hour in minutes (varies by season).
`night_hour_duration_minutes`	number	Duration of each night hour in minutes.

`data.hours[]`

Full 24-hour table. Each entry:

Field	Type	Description
`hour_number`	integer	1–24.
`ruler`	string	Ruling planet for this hour.
`type`	string	`"day"` or `"night"`.
`start`	string	Hour start time (`HH:MM:SS`).
`end`	string	Hour end time.
`duration_minutes`	number	Duration in minutes.
`is_birth_hour`	boolean	Present and `true` only on the hour containing the birth time.

How planetary hours work

The system divides daylight into 12 equal “hours” and nighttime into 12 equal “hours.” These are not 60-minute hours — in summer, day hours are longer than night hours; in winter, the reverse. At the equinoxes, both equal exactly 60 minutes.

The first day hour begins at sunrise and is ruled by the day ruler (the planet associated with the day of the week). Subsequent hours follow the Chaldean order:

Day	Day ruler	1st hour
Sunday	Sun ☉	Sun
Monday	Moon ☽	Moon
Tuesday	Mars ♂	Mars
Wednesday	Mercury ☿	Mercury
Thursday	Jupiter ♃	Jupiter
Friday	Venus ♀	Venus
Saturday	Saturn ♄	Saturn

Chaldean order: Saturn → Jupiter → Mars → Sun → Venus → Mercury → Moon (then repeats).

Polar regions: at extreme latitudes where the Sun does not rise or set, this endpoint returns a 400 COMPUTE_ERROR since planetary hours cannot be calculated without a distinct sunrise and sunset.

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	`COMPUTE_ERROR`	No sunrise/sunset at this location (polar region).

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

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

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

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

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/western/natal/planetary-hours",
        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/planetary-hours')
payload = {
  'year' => 1990,
  'month' => 5,
  'day' => 20,
  'hour' => 14,
  'minute' => 30,
  'second' => 0,
  'latitude' => 28.6139,
  'longitude' => 77.209,
  'timezone' => 'Asia/Kolkata'
}

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": {
    "birth_hour": {
      "ruler": "Sun",
      "hour_number": 8,
      "type": "day"
    },
    "day_ruler": "Sun",
    "day_of_week": "Sunday",
    "sunrise": "05:27:46",
    "sunset": "19:07:28",
    "day_hour_duration_minutes": 68.3,
    "night_hour_duration_minutes": 51.7,
    "hours": [
      {
        "hour_number": 1,
        "ruler": "Sun",
        "type": "day",
        "start": "05:27:46",
        "end": "06:36:02",
        "duration_minutes": 68.3,
        "is_birth_hour": false
      },
      {
        "hour_number": 8,
        "ruler": "Sun",
        "type": "day",
        "start": "13:25:19",
        "end": "14:33:35",
        "duration_minutes": 68.3,
        "is_birth_hour": true
      }
    ],
    "total_hours": 24
  },
  "meta": { "endpoint": "/api/v3/western/natal/planetary-hours", "version": "3.0" }
}