apyhub
GEOLOCATION · STANDARD DATA

Get Planetary Hours API

What it does

Planetary Hours gives you the 24 unequal Chaldean hours for a specific latitude, longitude, and date. Send a date plus lat and lng, and you get the local day ruler, sunrise and sunset in UTC, and a full hour-by-hour schedule.

Each hour item includes its index, period (day or night), ruling planet in Chaldean order, and start_utc / end_utc timestamps. The response also echoes back the input date, lat, and lng, so you can store or audit the calculation without keeping the original request separately.

Use Planetary Hours when you need location-aware timing for astrology tools, ritual planners, or any application that depends on sunrise/sunset-based day partitions. Because the hours are unequal, the schedule is derived from the actual daylight and nighttime length at the requested coordinates rather than a fixed 60-minute clock.

It is a good fit for apps that need a deterministic planetary timetable for a given place and date, with enough detail to render a calendar, timeline, or hourly planner from the API response.

GET
Get Planetary Hours
http://localhost:8080/creightonnick0/get-planetary-hours/v1/lunar/planetary-hours

QUICKSTART

GUIDE

Quickstart

Get planetary hours for a specific date and location by passing the required query parameters.

curl -X GET "http://localhost:8080/creightonnick0/get-planetary-hours/v1/lunar/planetary-hours?date=2026-07-26&lat=51.4779&lng=-0.0015" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with date (string), lat (number), lng (number), day_ruler (string enum), sunrise_utc (string date-time), sunset_utc (string date-time), and hours (array) fields. Each item in hours is an object with index (integer), period (string enum), ruler (string enum), start_utc (string date-time), and end_utc (string date-time).

{
  "date": "2026-07-26",
  "lat": 51.4779,
  "lng": -0.0015,
  "day_ruler": "Sun",
  "sunrise_utc": "2026-07-26T04:56:00Z",
  "sunset_utc": "2026-07-26T20:52:00Z",
  "hours": []
}
TRY ITLIVE · 10 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns the 24 unequal planetary hours for a given latitude, longitude, and date, along with the day ruler and the UTC sunrise and sunset times used to divide the day.

Query Parameter(s)

AttributeTypeMandatoryDescription
latNumberYesLatitude in decimal degrees. Minimum -90, maximum 90.
lngNumberYesLongitude in decimal degrees. Minimum -180, maximum 180.
dateStringYesDate in date format (YYYY-MM-DD).

Response

Returns a JSON object with lat and lng number fields, a date string field, a day_ruler string field, sunrise_utc and sunset_utc date-time string fields, and an hours array of objects. Each object in hours contains index (integer), period (day or night), ruler (one of the planetary ruler strings), start_utc (date-time string), and end_utc (date-time string).

AttributeTypeMandatoryDescription
latNumberYesLatitude in decimal degrees.
lngNumberYesLongitude in decimal degrees.
dateStringYesDate in date format (YYYY-MM-DD).
day_rulerENUMYesPlanetary ruler for the day. Allowed values: Sun, Venus, Mercury, Moon, Saturn, Jupiter, Mars.
sunrise_utcStringYesSunrise time in UTC as a date-time string.
sunset_utcStringYesSunset time in UTC as a date-time string.
hoursObject ArrayYesArray of 24 planetary-hour objects. Each item includes index, period, ruler, start_utc, and end_utc.

Query parameters

Name
Type
Description
latREQUIRED
number
lngREQUIRED
number
dateREQUIRED
string
▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.