---
title: "Calculate classical unequal planetary hours for one local date"
method: POST
path: "/api/astro/planetary-hours"
tags: ["Calculations"]
---

# Calculate classical unequal planetary hours for one local date

`POST /api/astro/planetary-hours`

## Request

- Base URL: `https://api.cosmicephemeris.com`
- URL: `https://api.cosmicephemeris.com/api/astro/planetary-hours`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Divides local sunrise-to-sunset and sunset-to-next-sunrise into twelve equal temporal intervals each, assigning rulers through the documented Chaldean order beginning with the civil weekday ruler. Solar events use the existing apparent DE440 center at a fixed -50 arcminute horizon. Dates without exactly one ordered sunrise, sunset, and following sunrise reject; no polar fallback, electional ranking, interpretation, or advice. One standard quota unit per admitted request; failed or timed-out admitted attempts are not refunded.
Historical mode uses an explicit BCE/CE date object and UT1 conventions. Its response is the versioned historical envelope, not the modern UTC envelope. Read result for calculation fields and metadata for limits and uncertainty.

## Request body

- union
  - PlanetaryHoursRequest
    - `date` string, date, required: Valid Gregorian YYYY-MM-DD local civil date, inclusive 1800-01-01 through 2200-12-31. Calendar validity and timezone conversion are checked by the server.
    - `timezone` string, nullable, required: IANA timezone name (for example America/New_York). Omission, null, or empty string means UTC for a birth input. Nonexistent or ambiguous local clock-change times return 400; provide the known UTC date/time with timezone UTC instead.
    - `lat` number, required
    - `lon` union, required: WGS84 decimal longitude, east positive, within [-180,180]. JSON numbers are recommended; numeric strings are accepted then checked for finiteness/range.
      - number
      - string
  - HistoricalPlanetaryHoursRequest: Explicit historical mode, 1000 BCE (BC)–2500 CE (AD). No year zero, implicit calendar, UTC or IANA zone. Preserve tool-specific mathematical, geographic and search limits; calendar/time conventions and estimated Delta-T are not certified historical accuracy.
    - `date` HistoricalDate, required: Explicit civil date, 1000 BCE (BC)–2500 CE (AD); no year zero. Calendar validity is checked by the server. Available only on documented connected historical operations, with explicit UT1/fixed-offset conventions.
      - `year` integer, required
      - `era` 'BCE' | 'CE', required: Display BCE (BC) / CE (AD); API values remain BCE / CE. No year zero.
      - `month` integer, required
      - `day` integer, required
      - `calendar` 'proleptic_gregorian' | 'proleptic_julian', required: Explicit choice; applies the selected calendar rules throughout history without a regional adoption switch.
    - `timezone` string, required: Explicit UT1 or fixed offset UT1+/-HH:MM[:SS], within 14 hours. Local clock minus offset yields UT1, not UTC. No IANA timezone inference. Original offset spelling is preserved.
    - `lat` number, required
    - `lon` union, required: WGS84 decimal longitude, east positive, within [-180,180]. JSON numbers are recommended; numeric strings are accepted then checked for finiteness/range.
      - number
      - string

## Response `200`

Twenty-four contiguous unequal planetary-hour intervals.

- union
  - PlanetaryHoursResponse
    - `status` 'current', required
    - `type` 'planetary_hours', required
    - `input` object, required
    - `day_ruler` 'saturn' | 'jupiter' | 'mars' | 'sun' | 'venus' | 'mercury' | 'moon', required
    - `solar_events` object, required
    - `hours` PlanetaryHour[], required
      - `sequence` integer, required
      - `period` 'day' | 'night', required
      - `period_hour` integer, required
      - `ruler` 'saturn' | 'jupiter' | 'mars' | 'sun' | 'venus' | 'mercury' | 'moon', required
      - `start_utc` string, date-time, required: Normalized UTC timestamp; fractional seconds may be present.
      - `end_utc` string, date-time, required: Normalized UTC timestamp; fractional seconds may be present.
      - `start_local` string, date-time, required: ISO 8601 timestamp with Z or an explicit numeric UTC offset. Prefer RFC 3339, e.g. 2026-01-01T00:00:00Z. Naive local timestamps are rejected. The server normalizes offsets to UTC before comparing ordering, duration and the inclusive 1800-01-01 through 2200-12-31 UTC-date bounds.
      - `end_local` string, date-time, required: ISO 8601 timestamp with Z or an explicit numeric UTC offset. Prefer RFC 3339, e.g. 2026-01-01T00:00:00Z. Naive local timestamps are rejected. The server normalizes offsets to UTC before comparing ordering, duration and the inclusive 1800-01-01 through 2200-12-31 UTC-date bounds.
      - `duration_seconds` number, required
    - `metadata` object, required
  - HistoricalPlanetaryHoursPlanetaryHoursResponse
    - `schema` 'cosmicephemeris-historical-calculation-v1', required
    - `status` 'historical', required
    - `type` 'planetary-hours', required
    - `input` HistoricalPlanetaryHoursRequest, required: Explicit historical mode, 1000 BCE (BC)–2500 CE (AD). No year zero, implicit calendar, UTC or IANA zone. Preserve tool-specific mathematical, geographic and search limits; calendar/time conventions and estimated Delta-T are not certified historical accuracy.
      - `date` HistoricalDate, required: Explicit civil date, 1000 BCE (BC)–2500 CE (AD); no year zero. Calendar validity is checked by the server. Available only on documented connected historical operations, with explicit UT1/fixed-offset conventions.
        - `year` integer, required
        - `era` 'BCE' | 'CE', required: Display BCE (BC) / CE (AD); API values remain BCE / CE. No year zero.
        - `month` integer, required
        - `day` integer, required
        - `calendar` 'proleptic_gregorian' | 'proleptic_julian', required: Explicit choice; applies the selected calendar rules throughout history without a regional adoption switch.
      - `timezone` string, required: Explicit UT1 or fixed offset UT1+/-HH:MM[:SS], within 14 hours. Local clock minus offset yields UT1, not UTC. No IANA timezone inference. Original offset spelling is preserved.
      - `lat` number, required
      - `lon` union, required: WGS84 decimal longitude, east positive, within [-180,180]. JSON numbers are recommended; numeric strings are accepted then checked for finiteness/range.
        - number
        - string
    - `result` object, required: Complete historical calculation adapter result. Times are explicit UT1 date records, never UTC strings; derived times may include fractional seconds and years outside the input range.
    - `metadata` object, required
      - `time_standard` 'UT1', required
      - `historical_accuracy_certified` unknown, required
      - `warnings` string[], required

## Other responses

- `400`: Invalid request, malformed JSON, out-of-range date/location, unknown model, invalid timezone or ambiguous/nonexistent clock-change time. Invalid attempts reaching quota reservation consume one unit.
- `401`: Missing, invalid, revoked API key or unavailable activated key owner. Dashboard cookies do not authenticate calculation routes.
- `403`: Origin not allowed by production CORS policy. Server-to-server requests can omit Origin.
- `429`: Monthly quota exhausted, per-user two-request concurrency reached, or nginx rate/connection admission refused. Retry-After: 2 is sent for application per-user concurrency only, not a promise that monthly quota resets in two seconds.
- `502`: Engine unavailable, unsuccessful internal server response or invalid upstream JSON. No engine internals are exposed.
- `503`: Four-request global calculation pool full (Retry-After: 2), maintenance or upstream service unavailable.
- `504`: Application engine timeout: 15 seconds normally; planetary events, house ingresses, aspect windows, event calendar, eclipse geometry, electional search, and event-rule search use 30 seconds; Nakshatra Timeline plus the explicitly enumerated readiness, robustness, location, uncertainty, and electional-audit family use 60 seconds. Timer includes response-body parsing; an admitted timeout consumes quota.

---

[API](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api.md) · [All operations](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api/revisions/f041e924cea3?raw)