What shipped

POST /api/v3/electional/personal-hours went live today. Give it a birth chart and a date, and it returns a ranked timeline of that day, favorable windows, caution windows, one headline peak, broken down by life area if you want, in the person's own local time and in UTC.

The classical planetary hours endpoint still exists and is untouched. It divides daylight and night into 12 unequal segments each, assigns a ruling planet to each segment by the Chaldean order, and hands back the same 24 rulers to every person standing in the same city on the same day. That's correct traditional technique, and it's genuinely useful for things like "is this a Mercury hour for signing a contract." But it has a hard ceiling: it knows nothing about the person asking. Two clients in the same city get the identical hour list, whether one has Mars rising in Scorpio and the other has Mars in fall, combust, in the twelfth.

Personal Power Hours removes that ceiling. It takes the same 24-hour Chaldean spine and re-scores every hour against the native's own natal chart, then lays real-time transits on top. The result is a timeline that's different for every single person, computed from their own dignities, their own sect, their own chart ruler, and the sky as it moves against their own natal points today.

Why classical planetary hours can't do this

The problem with planetary hours as a personalization tool isn't the technique. It's the input. A Chaldean hour ruler is picked by a fixed rotation (Saturn, Jupiter, Mars, Sun, Venus, Mercury, Moon) that starts from the day-of-week ruler and repeats. That rotation is identical for every observer in a given location and time zone. It answers "whose hour is it" but never "is this a good hour for this Mercury, in this chart."

A Mercury hour is a fine hour to write and negotiate if you're a person whose natal Mercury is in Virgo, angular, unafflicted. It's a much weaker hour if your natal Mercury is retrograde, combust, and in the twelfth house. Classical planetary hours can't see the difference. They rank the sky, not the person.

Personal Power Hours scores each hour by the condition of its ruling planet inside one specific chart: essential dignity (domicile down through fall), accidental strength (angular versus cadent, houses of joy), sect (is the planet in its own sect or out of it, using the same day/night geometric test used across the platform), and the planet's benefic or malefic nature. On top of that, if the hour's ruler happens to be the chart ruler, the ruler of the native's own Ascendant, that hour gets a deliberate boost. That's the mechanism behind what we call the signature window: the hour of the day that is structurally "yours," the way your rising sign is yours, computed once from your birth chart and consistent day to day in how it's weighted (though its clock position moves with the Chaldean rotation).

The two-layer model

Two layers combine into a single favorability curve across the day.

The first layer is the spine: the 24 unequal Chaldean hours, each given a score from minus one to plus one based on its ruling planet's condition in the native's chart, as described above, plus a small check against the ruler's current sky state (retrograde, combust, or cazimi right now). This layer is slow-moving and structural. It's why the same person tends to have a recognizable "good hour" and "bad hour" shape to their day even before any transit gets involved.

The second layer is the overlay: sharp, short-lived events stacked on top of the spine. The transiting Moon is the dominant overlay signal, because it moves roughly 13 degrees a day and triggers aspects to natal points on a timescale of minutes, not weeks. We compute exact hit times and orb windows for the transiting Moon against every relevant natal point, using the same transit-activation engine that powers the rest of the platform, not a separate implementation. Faster planets (Sun, Mercury, Venus, Mars) contribute the same way. Rotational triggers add a third overlay signal: the exact instants when the rising degree or the Midheaven degree, both of which move a full 360 degrees every day, conjunct a natal point. Those are narrow, sensitive minutes, and they're informational markers rather than standalone peaks; a rotational trigger can sharpen a window the spine and Moon overlay have already flagged as favorable, but it can't manufacture a peak window on its own.

Void-of-course Moon damps the overlay's positive contributions to 40% of normal strength rather than zeroing them out. That reflects the traditional reading of void Moon: initiatives started during a void tend not to come to much, but the day underneath a void isn't dead, it's just quieter than it looks on paper. A void period never suppresses the spine, only the overlay.

Hard transits from Mars or Saturn to natal points, and an hour whose ruling planet is combust or under the sunbeams, both feed caution windows. Every caution window is anchored to a specific event, hour-split, and duration-capped, so a long stretch of merely low spine score reads as background, not as a red flag stretching across half the afternoon.

What you get back

A response carries a day_quality flag first: active, quiet, voc_dominated, or polar_degraded. This is the part we spent the most engineering effort protecting. If nothing in a given day clears the threshold for a genuine peak, the endpoint reports quiet and returns the best of a mediocre lot, honestly labeled. It does not manufacture a fake headline window to make the response look more exciting than the day actually is. If you're building a "your best hour today" push notification, that honesty matters: a user who gets told every single day is a peak day stops believing the app within a couple of weeks.

Below the quality flag: a peak_window (the single best moment of the day), up to five favorable_windows, up to three caution_windows, the signature_window tied to the chart ruler, informational angular_triggers, and per_area_best, which reruns the ranking re-weighted toward a specific life area (career, relationships, health, and eleven others) so you can answer "what's my best hour today for a hard conversation" separately from "what's my best hour for a first date." Every window carries local time with UTC offset, the equivalent UTC timestamp, the ruling planet, a 0-100 score, a short tone label, activity tags, and the specific drivers that produced the score, so you're not stuck explaining a number with nothing behind it.

Here's a trimmed example, natal chart for a New York native, checked against July 25, 2026:

json

1{
2  "target_date": "2026-07-25",
3  "location": { "timezone": "America/New_York", "lat": 40.7128, "lng": -74.006 },
4  "chart_ruler": "Mercury",
5  "day_quality": "active",
6  "peak_window": {
7    "start_local": "2026-07-25T09:14:00-04:00",
8    "end_local": "2026-07-25T10:02:00-04:00",
9    "start_utc": "2026-07-25T13:14:00Z",
10    "end_utc": "2026-07-25T14:02:00Z",
11    "ruling_planet": "Mercury",
12    "score": 91,
13    "tone": "sharp, communicative, well-timed",
14    "activity_tags": ["negotiation", "writing", "pitching"],
15    "drivers": ["chart_ruler_bonus", "in_sect", "moon_applying_trine_natal_sun"]
16  },
17  "signature_window": {
18    "ruling_planet": "Mercury",
19    "note": "Your chart ruler's hour, roughly 9:14-10:02am local today"
20  },
21  "caution_windows": [
22    {
23      "start_local": "2026-07-25T15:40:00-04:00",
24      "end_local": "2026-07-25T16:20:00-04:00",
25      "ruling_planet": "Mars",
26      "score": 22,
27      "drivers": ["transiting_mars_square_natal_moon", "void_of_course_moon"]
28    }
29  ],
30  "per_area_best": {
31    "career": { "start_local": "2026-07-25T09:14:00-04:00", "score": 91 },
32    "relationships": { "start_local": "2026-07-25T18:05:00-04:00", "score": 74 }
33  }
34}

That native has Mercury as chart ruler, so the 9:14-10:02am Mercury hour is already carrying a structural bonus from the spine before the Moon's applying trine to natal Sun adds an overlay boost, which is why it clears to a 91 and gets flagged as the day's peak. The 3:40pm caution window is a different mechanism entirely: a hard Mars-square-Moon transit landing during a void-of-course period. Two separate reasons, both surfaced in drivers rather than left for you to reverse-engineer.

Who this is for

Anyone building a "best time to..." feature is currently faking the personalization layer or skipping it. TimePassages and Astro Gold will show you a list of the day's transits, unranked, and leave the interpretation to you. The Pattern gives you a mood blurb tied loosely to a transit but with no minute-level structure underneath it and nothing tied to your actual chart ruler or dignities. Co-Star's daily card reads as generic astrology-flavored copy more often than a computed ranking. None of the four will tell you which specific 45-minute window today is structurally yours versus which one is borrowed from a transit that will be gone by lunch.

That gap is the opportunity for the apps we hear from most: dating apps that want a "your best window to message someone today" feature instead of a generic daily horoscope card, productivity and habit apps that want to suggest a deep-work block tied to something more specific than a coin flip, ritual and wellness apps building "best time to meditate, journal, or set an intention" prompts, and astrologer-run practices that want to hand clients a daily timing sheet without doing the chart math by hand every morning. All four of those currently either omit personalization entirely or hand-wave it with a Sun-sign horoscope. This endpoint is the layer that was missing.

It's also deterministic. Same chart, same date, same location in, same response out, every time, no randomness anywhere in the pipeline. That matters if you're caching responses, running the endpoint in a batch job overnight for every user in your database, or debugging a support ticket where a user is asking why the app told them 9am was their peak hour. You can recompute the exact same answer and show your work.

Travel and time zones

Planetary hours resolve against the location you send, and the endpoint threads a real time-zone-aware datetime through the whole pipeline rather than assuming server-local time (a fix that was a prerequisite for this launch, since the classical planetary-hours calculation had been running on a naive local clock internally). Send a location_override for a traveling user and you get correct hours for wherever they actually are, in their local offset, alongside the UTC timestamp for your own storage and comparisons. Two edge cases are called out honestly in the response rather than silently degraded: charts without a known birth time lose the Ascendant, so the endpoint falls back to overlay-only scoring and flags that the spine is generic rather than personal, and charts above 66.5 degrees latitude, where the unequal-hour system breaks down near the poles, get day_quality: "polar_degraded" with a flat baseline spine instead of a spine pretending precision it doesn't have.

How to integrate

bash

1curl -X POST https://api.astrology-api.io/api/v3/electional/personal-hours \
2  -H "Authorization: Bearer $ASTROLOGY_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "subject": {
6      "birth_date": "1990-03-14",
7      "birth_time": "07:22:00",
8      "birth_location": { "lat": 40.7128, "lng": -74.0060, "timezone": "America/New_York" }
9    },
10    "target_date": "2026-07-25",
11    "life_area": "career",
12    "granularity": "standard",
13    "include_caution": true
14  }'

Response shape matches the electional endpoints already documented on the Electional Astrology API page: { success, data, metadata }, with data holding everything shown in the example above.

Where to learn more

Related product: /p/electional
Classical technique for comparison: /p/planetary-hours
Interactive demo: /demo

Pricing

Personal Power Hours is available on the same tiers as the rest of the electional endpoints, Professional ($37/mo) and above. See /pricing for the full table.

What's next

This is Phase 1: the spine scorer, Moon overlay, void-of-course suppression, Mars/Saturn caution, life-area filtering, and honest day-quality reporting. Phase 2, already scoped, adds the fast-planet overlay for Sun, Mercury, and Venus, angular-trigger detection at full resolution, Moon speed and phase modulation, and a granularity: "fine" mode for sub-minute windows. A weekly roll-up sibling endpoint is on the roadmap after that.

Feedback welcome via /contact.

Personal Power Hours: Natal-Personalized Intraday Timing API

What shipped

Why classical planetary hours can't do this

The two-layer model

What you get back

Who this is for

Travel and time zones

How to integrate

Where to learn more

Pricing

What's next

Oleg Kopachovets

More from Astrology API

Electional Astrology API V1 Launch: Automated Auspicious Timing

Chinese Name Analysis API Launch: 五格剖象法 Scoring with BaZi Synergy

Birth Time Rectification API V1 Launch: Automated Chart Correction