---
title: "Planetary hours"
method: POST
path: "/v1/western/planetary-hours"
tags: ["Western Astrology"]
---

# Planetary hours

`POST /v1/western/planetary-hours`

## Request

- Base URL: `https://api.asterwise.com`
- URL: `https://api.asterwise.com/v1/western/planetary-hours`
- Auth: HTTP bearer

The 24 planetary hours for a date and place, with the planet ruling each hour. Sunrise to sunset and sunset to the next sunrise are each split into 12 equal parts, so hours are longer by day in summer and shorter in winter. The first hour after sunrise belongs to the planet of the weekday (Sunday Sun, Monday Moon, Tuesday Mars, Wednesday Mercury, Thursday Jupiter, Friday Venus, Saturday Saturn); the rest follow the Chaldean order Saturn, Jupiter, Mars, Sun, Venus, Mercury, Moon. Same calculation as /v1/astro/panchanga/hora, with Western naming and both local and UTC times.

## Request body

- PlanetaryHoursRequest: Date plus place (location, or latitude/longitude/timezone).
  - `date` string, required: Date in YYYY-MM-DD format
  - `location` string, nullable: City name. Example: 'Mumbai'
  - `latitude` number, nullable: Latitude in decimal degrees, north positive. Use with longitude and timezone instead of location.
  - `longitude` number, nullable: Longitude in decimal degrees, east positive. Use with latitude and timezone instead of location.
  - `timezone` string, nullable: IANA timezone string

## Response `200`

Successful Response

- ApiResponsePlanetaryHoursResponse
  - `success` boolean: True if the request succeeded
  - `message` string: Human-readable status message
  - `data` PlanetaryHoursResponse, required
    - `status` 'ok' | 'no_sunrise': ok, or no_sunrise when the place has no sunrise or sunset on that date (polar latitudes): the hour fields are then null.
    - `status_detail` string, nullable: Plain-English reason when status is not ok.
    - `date` string, required
    - `weekday` string, nullable: Weekday of the date, e.g. Sunday.
    - `day_ruler` string, nullable: Planet of the weekday; it rules the first hour after sunrise.
    - `convention` string, nullable: unequal_seasonal: day and night each split into 12 equal parts from real sunrise and sunset.
    - `sunrise_local` string, nullable
    - `sunset_local` string, nullable
    - `next_sunrise_local` string, nullable
    - `sunrise_utc` string, nullable
    - `sunset_utc` string, nullable
    - `next_sunrise_utc` string, nullable
    - `day_hour_minutes` number, nullable: Length of one day hour in minutes.
    - `night_hour_minutes` number, nullable: Length of one night hour in minutes.
    - `hours` PlanetaryHour[], nullable: The 24 hours; null when status is no_sunrise.
      - `hour` integer, required: 1–12 are day hours (sunrise to sunset), 13–24 night hours.
      - `period` 'day' | 'night', required
      - `planet` string, required: Planet ruling this hour.
      - `start_local` string, required: Start, local time with UTC offset (ISO 8601).
      - `end_local` string, required: End, local time with UTC offset (ISO 8601).
      - `start_utc` string, required: Start in UTC (ISO 8601 with Z).
      - `end_utc` string, required: End in UTC (ISO 8601 with Z).
      - `length_minutes` number, required
      - `is_current` boolean, required: True if the current moment falls in this hour.

## Other responses

- `401`: Authentication failed
- `403`: Authorization failed
- `404`: Resource not found
- `413`: Payload too large
- `422`: Validation error
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream provider error
- `503`: Service unavailable

---

[API](https://skmtc.dev/asterwise/apis/asterwise-api.md) · [All operations](https://skmtc.dev/asterwise/apis/asterwise-api/llms.txt) · [OpenAPI document](https://skmtc.dev/asterwise/apis/asterwise-api/revisions/3c4bbb1194e2?raw)