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

{
  "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.