---
title: "Planetary hours (GET)"
method: GET
path: "/v1/western/planetary-hours"
---

# Planetary hours (GET)

`GET /v1/western/planetary-hours`

## Request

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

Same answer as the POST route with the same fields as query parameters; cacheable (public, 10 minutes). Current-moment flags such as is_current may lag by up to the cache age.

## Query parameters

- `date` string, required: Date, YYYY-MM-DD (local civil date at the place).
- `location` string, nullable: City name, used when latitude/longitude/timezone are not given.
- `latitude` number, nullable: Latitude in decimal degrees, north positive.
- `longitude` number, nullable: Longitude in decimal degrees, east positive.
- `timezone` string, nullable: IANA timezone, e.g. Asia/Kolkata.

## 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)