Back to Docs

Personal Daily Horoscope

Personal Daily Horoscope

Generates a unique forecast from a natal chart. V3 adds timeline-backed context, exact-hit timing, dominant monthly themes, and optional atomic interpretation blocks on top transits.

Horoscope Demo App

An open-source Next.js app built with this endpoint showing daily personal horoscopes in a clean UI.

Live DemoSource Code
POST/api/v3/horoscope/daily/personal

ℹ️ V3 Timeline: Uses the transit timeline and transit insights engines, then distills them into a daily horoscope response with exact hits, active windows, next shift, dominant topics, and optional interpretation blocks on top-ranked transits.

Endpoint Overview

Accepts full birth details and returns a richer daily layer built from timeline windows and transit insights. Location can be resolved from either city or direct coordinates. This is the best choice when you need exact-hit timing, active windows, monthly context, or explanation blocks on top transits.

Location rule: for all versions, you must send either birth.city or both birth.lat and birth.lng. City is not required when coordinates are already known.

Body Parameters

Parameter
birth
Type
object
Required
Yes
Description
Birth details object. Location can be provided either as city or as lat/lng coordinates.
Parameter
date
Type
string
Required
No
Description
Target date (YYYY-MM-DD). Default: today
Parameter
tz_str
Type
string
Required
No
Description
Timezone string. Default: AUTO
Parameter
include_interpretation_blocks
Type
boolean
Required
No
Description
V3 only. Adds optional atomic interpretation blocks to top transits.
Parameter
birth.year
Type
integer
Required
Yes
Description
Birth year
Parameter
birth.month
Type
integer
Required
Yes
Description
Birth month (1-12)
Parameter
birth.day
Type
integer
Required
Yes
Description
Birth day
Parameter
birth.hour
Type
integer
Required
Yes
Description
Birth hour (0-23)
Parameter
birth.minute
Type
integer
Required
Yes
Description
Birth minute
Parameter
birth.city
Type
string
Required
No
Description
Optional city name for auto-geolocation. Required only if lat/lng are not provided.
Parameter
birth.lat
Type
float
Required
No
Description
Birth latitude. Required together with lng when city is omitted.
Parameter
birth.lng
Type
float
Required
No
Description
Birth longitude. Required together with lat when city is omitted.
Parameter
birth.tz_str
Type
string
Required
No
Description
IANA timezone name, e.g. Europe/London
Parameter
birth.time_known
Type
boolean
Required
No
Description
Set false when birth time is unknown

Example Request

curl -X POST "https://api.freeastroapi.com/api/v3/horoscope/daily/personal" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
    "birth": {
      "year": 1990,
      "month": 5,
      "day": 15,
      "hour": 10,
      "minute": 0,
      "city": "London, UK",
      "lat": 51.5074,
      "lng": -0.1278,
      "tz_str": "Europe/London",
      "time_known": true
    },
    "date": "2026-04-20",
    "include_interpretation_blocks": true
}'

Response Example

Real production example from /api/v3/horoscope/daily/personal, trimmed for readability.

V3
{
  "meta": {
    "request_id": "req_869e5b4f",
    "generated_at": "2026-04-20T13:28:51.233830",
    "settings": {
      "date_resolved": "2026-04-20",
      "version": "v3",
      "include_interpretation_blocks": true
    },
    "engine": {
      "name": "DailyHoroscopeEngine",
      "version": "3.0.0"
    }
  },
  "data": {
    "sign": "taurus",
    "date": "2026-04-20",
    "scores": {
      "overall": 72,
      "love": 86,
      "career": 58,
      "money": 92,
      "health": 53
    },
    "content": {
      "theme": "Sensuality",
      "keywords": ["Stability", "Practicality", "Sensuality", "Focus", "Growth"]
    },
    "personal": {
      "transits_top": [
        {
          "label": "Venus Trine Natal Moon",
          "score": 99.8,
          "exact_at": "2026-04-20T13:42:39Z",
          "transit_planet": { "key": "venus", "label": "Venus" },
          "natal_planet": { "key": "moon", "label": "Moon" },
          "aspect": { "key": "trine", "label": "Trine" },
          "explanation": {
            "main": "Emotional life tends to feel steadier and more nourished, making it easier to give and receive care without overexplaining.",
            "supporting": [
              "Lean into simple rituals: shared meals, warm baths, tidying your space, or calling someone who feels like home.",
              "If feelings surface, name them gently; reassurance lands well and helps closeness grow naturally."
            ],
            "tags": ["emotional-ease", "comfort", "affection", "home", "relationship-support"]
          }
        },
        {
          "label": "Mars Conjunction Natal Midheaven",
          "score": 98.5,
          "exact_at": "2026-04-20T15:01:24Z",
          "transit_planet": { "key": "mars", "label": "Mars" },
          "natal_planet": { "key": "midheaven", "label": "Midheaven" },
          "aspect": { "key": "conjunction", "label": "Conjunction" }
        }
      ],
      "focus_areas": [
        "Background Themes",
        "Relationships & Bonds",
        "Action & Energy"
      ],
      "confidence_score": 95,
      "day_context": {
        "active_windows": [
          {
            "label": "Mars Sextile Natal Descendant",
            "start": "2026-04-04T21:39:22Z",
            "end": "2026-04-20T08:10:46Z",
            "exact_hits": ["2026-04-12T14:27:39Z"]
          },
          {
            "label": "Venus Conjunction Natal Sun",
            "start": "2026-04-12T22:07:30Z",
            "end": "2026-04-26T01:00:28Z",
            "exact_hits": ["2026-04-19T11:16:24Z"]
          }
        ],
        "exact_hits": [
          {
            "timestamp": "2026-04-20T13:42:39Z",
            "label": "Venus Trine Natal Moon"
          },
          {
            "timestamp": "2026-04-20T15:01:24Z",
            "label": "Mars Conjunction Natal Midheaven"
          },
          {
            "timestamp": "2026-04-20T18:26:43Z",
            "label": "Mercury Conjunction Natal Midheaven"
          }
        ],
        "next_shift": {
          "timestamp": "2026-04-20T13:42:39Z",
          "label": "Venus Trine Natal Moon exact",
          "type": "exact_hit"
        },
        "dominant_topics": [
          {
            "title": "Transit Stellium In Taurus",
            "category": "chart_pattern",
            "focus_type": "background_month_theme",
            "score": 0.769,
            "peak_datetime": "2026-04-22T12:00:00Z"
          }
        ],
        "supportive_vs_challenging": {
          "supportive": 12,
          "challenging": 12
        }
      },
      "insights_meta": {
        "source": "timeline_and_transit_insights",
        "timeline_enabled": true,
        "insights_enabled": true,
        "interpretation_blocks_enabled": true,
        "timeline_pass_count": 112,
        "generated_fact_count": 64,
        "range_start": "2026-04-01T00:00:00Z",
        "range_end": "2026-04-30T23:59:59Z"
      }
    }
  }
}

V3: Timeline-Powered Daily Context

V3 keeps the daily scores and top transits, but upgrades the endpoint with a real timing layer. It is designed for clients that want a more coherent and inspectable daily personal horoscope.

Exact-Hit Timing

day_context.exact_hits and next_shift expose the exact intraday turning points that drive the daily ranking.

Active Windows

active_windows summarizes transits already in force around the target date, including start, end, and exact-hit timestamps.

Dominant Topics

dominant_topics surfaces the larger monthly pattern behind the day, such as a stellium, support window, pressure window, or activation cluster.

Optional Atomic Blocks

Set include_interpretation_blocks=true to attach real interpretation blocks to personal.transits_top[*].explanation.