Back to Docs

Personal Weekly Horoscope

POST/api/v3/horoscope/weekly/personal

Personal Weekly Horoscope

Generates a seven-day personalized horoscope from a natal chart using the V3 transit timeline and transit insights engines.

V3 weekly is designed for calendar, dashboard, email, and app views that need weekly exact hits, active transit windows, dominant topics, and daily slices in one response.

Full URL

https://api.freeastroapi.com/api/v3/horoscope/weekly/personal

Endpoint Overview

The endpoint calculates the natal chart once, samples seven daily score layers, then runs one weekly transit timeline range for inspectable week-level timing. Send week_start for an exact range, or send date to resolve the containing week.

Location rule: send either birth.city or both birth.lat and birth.lng. City is optional when coordinates are already known.

Body Parameters

Field
birth
Type
object
Required
Yes
Description
Birth details object. Send either birth.city or both birth.lat and birth.lng.
Field
week_start
Type
string
Required
No
Description
Explicit first day of the requested week in YYYY-MM-DD format. When present, this exact date is used.
Field
date
Type
string
Required
No
Description
Anchor date in YYYY-MM-DD format. Used only when week_start is omitted.
Field
start_week_on
Type
string
Required
No
Description
When date is used as an anchor, resolves the week from monday or sunday. Default: monday.
Field
tz_str
Type
string
Required
No
Description
Client timezone label for request settings. Birth timezone should still be sent inside birth.tz_str when known.
Field
include_interpretation_
blocks
Type
boolean
Required
No
Description
Adds optional atomic interpretation blocks to the week-level top transits. Default: false.
Field
birth.year
Type
integer
Required
Yes
Description
Birth year.
Field
birth.month
Type
integer
Required
Yes
Description
Birth month, 1-12.
Field
birth.day
Type
integer
Required
Yes
Description
Birth day.
Field
birth.hour
Type
integer
Required
Yes
Description
Birth hour, 0-23.
Field
birth.minute
Type
integer
Required
Yes
Description
Birth minute.
Field
birth.city
Type
string
Required
No
Description
Optional city name for auto-geolocation. Required only when coordinates are omitted.
Field
birth.lat
Type
float
Required
No
Description
Birth latitude. Required together with birth.lng when birth.city is omitted.
Field
birth.lng
Type
float
Required
No
Description
Birth longitude. Required together with birth.lat when birth.city is omitted.
Field
birth.tz_str
Type
string
Required
No
Description
IANA timezone for the birth location, for example Europe/London.
Field
birth.time_known
Type
boolean
Required
No
Description
Set false when birth time is unknown.

Example Request

Use the same birth payload as the daily personal endpoint, plus a weekly period selector.

curl -X POST "https://api.freeastroapi.com/api/v3/horoscope/weekly/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
    },
    "week_start": "2026-04-20",
    "include_interpretation_blocks": true
  }'
{
  "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
  },
  "week_start": "2026-04-20",
  "include_interpretation_blocks": true
}

Response Data

Field
data.period
Type
object
Required
n/a
Description
Resolved weekly period with start, end, and day count.
Field
data.scores
Type
object
Required
n/a
Description
Average weekly overall, love, career, money, and health scores from seven daily samples.
Field
data.content.text
Type
string
Required
n/a
Description
Human-readable weekly summary generated from dominant topics, top exact hits, support/pressure balance, focus areas, and weekly scores.
Field
data.content.weekly_summary
Type
string
Required
n/a
Description
Same weekly narrative as data.content.text for clients that prefer an explicit weekly field.
Field
data.personal.transits_top
Type
array<object>
Required
n/a
Description
Top-ranked transits active during the week, spread across available event days and deduplicated for mirrored axis-pair hits.
Field
data.personal.week_context
Type
object
Required
n/a
Description
Weekly timing layer with active windows, exact hits, next shift, dominant topics, and support versus pressure counts.
Field
data.personal.days
Type
array<object>
Required
n/a
Description
Seven daily slices with date, weekday, scores, focus areas, top transits, and day_context.
Field
data.personal.insights_meta
Type
object
Required
n/a
Description
Timeline and transit-insights engine metadata for the weekly range.

Response Example

Trimmed sample showing the weekly range, aggregate scores, week context, and first daily slice.

{
  "meta": {
    "request_id": "req_42c1b7a9",
    "generated_at": "2026-04-20T13:28:51.233830",
    "settings": {
      "week_start": "2026-04-20",
      "week_end": "2026-04-26",
      "version": "v3",
      "include_interpretation_blocks": true
    },
    "engine": {
      "name": "DailyHoroscopeEngine",
      "version": "3.1.0-weekly"
    }
  },
  "data": {
    "sign": "taurus",
    "period": {
      "start": "2026-04-20",
      "end": "2026-04-26",
      "days": 7
    },
    "scores": {
      "overall": 71,
      "love": 82,
      "career": 63,
      "money": 76,
      "health": 61
    },
    "content": {
      "text": "From April 20 to April 26, the week centers on Relationship Window, with timing led by Venus Trine Natal Moon. The timeline shows 5 supportive windows and 3 pressure windows, so plan around both openings and friction points. The practical focus is relationships & bonds and structure & career. Love is the strongest average score (82), while Health benefits from extra pacing (61).",
      "weekly_summary": "From April 20 to April 26, the week centers on Relationship Window, with timing led by Venus Trine Natal Moon. The timeline shows 5 supportive windows and 3 pressure windows, so plan around both openings and friction points. The practical focus is relationships & bonds and structure & career. Love is the strongest average score (82), while Health benefits from extra pacing (61).",
      "theme": "Stability",
      "keywords": ["Stability", "Practicality", "Focus"],
      "supporting_insights": [
        "Dominant topics: Relationship Window.",
        "Top exact hits: Venus Trine Natal Moon.",
        "Focus areas: Relationships & Bonds and Structure & Career."
      ]
    },
    "personal": {
      "focus_areas": ["Relationships & Bonds", "Structure & Career", "Background Themes"],
      "confidence_score": 92,
      "transits_top": [
        {
          "label": "Venus Trine Natal Moon",
          "score": 99.3,
          "event_date": "2026-04-21",
          "exact_at": "2026-04-21T13:42:39Z",
          "active_start": "2026-04-20T09:00:00Z",
          "active_end": "2026-04-22T18:00:00Z",
          "exact_hits": ["2026-04-21T13:42:39Z"],
          "transit_planet": { "key": "venus", "label": "Venus" },
          "natal_planet": { "key": "moon", "label": "Moon" },
          "aspect": { "key": "trine", "label": "Trine" }
        }
      ],
      "week_context": {
        "range_start": "2026-04-20",
        "range_end": "2026-04-26",
        "exact_hits": [
          {
            "timestamp": "2026-04-21T13:42:39Z",
            "label": "Venus Trine Natal Moon"
          }
        ],
        "next_shift": {
          "timestamp": "2026-04-21T13:42:39Z",
          "label": "Venus Trine Natal Moon exact",
          "type": "exact_hit"
        },
        "dominant_topics": [
          {
            "title": "Relationship Window",
            "category": "relationships",
            "focus_type": "sharp_event_peak",
            "score": 0.91,
            "peak_datetime": "2026-04-23T13:42:39Z"
          }
        ],
        "supportive_vs_challenging": {
          "supportive": 5,
          "challenging": 3
        }
      },
      "days": [
        {
          "date": "2026-04-20",
          "weekday": "monday",
          "scores": { "overall": 72, "love": 86, "career": 58, "money": 92, "health": 53 },
          "focus_areas": ["Relationships & Bonds", "Action & Energy"],
          "transits_top": [],
          "day_context": {
            "range_start": "2026-04-20",
            "range_end": "2026-04-20",
            "exact_hits": [],
            "dominant_topics": []
          }
        }
      ],
      "insights_meta": {
        "source": "timeline_and_transit_insights",
        "timeline_enabled": true,
        "insights_enabled": true,
        "period": "week",
        "range_start": "2026-04-20T00:00:00Z",
        "range_end": "2026-04-26T23:59:59Z"
      }
    }
  }
}

Implementation Notes

  • Weekly scores are averaged from seven daily personal score samples.
  • Week-level active windows and exact hits come from one timeline range, not seven public API calls.
  • content.text and content.weekly_summary are generated from dominant topics, top exact hits, focus areas, support/pressure balance, and weekly scores.
  • personal.transits_top favors day distribution and removes mirrored axis-pair duplicates such as Midheaven/IC and Ascendant/Descendant repeats.
  • personal.days[*].day_context is range-filtered to each calendar day.
  • include_interpretation_blocks only adds explanation blocks to week-level top transits.
Daily Personal

Use this when you need the single-day V3 timing payload.

Transit Timeline

Use the lower-level timeline endpoint for custom ranges and filters.