GET · HOROSCOPE

Yearly Horoscope

Endpoint GET https://starsapi.com/api/v3/horoscope/yearly

Returns the full calendar-year horoscope (January 1 through December 31, IST) for a single zodiac sign. Returns ~1500 words of content organized into 10 H2 sections — Year Overview, Career & Business, Money & Finance, Love & Relationships, Family & Home, Health & Wellbeing, Education & Learning, Travel & Foreign, Spirituality & Growth, and Important Dates — plus a structured content_sections field for tabbed UIs, calendar imports, and SEO landing pages.

Note: yearly uses year=, not date= or month=. Each period type uses its own time parameter — daily/weekly use date=, monthly uses month=, yearly uses year=. The accepted formats are also different — see the year formats section below.

Authentication

Required. Three methods accepted:

Method	Example
Header (recommended)	`X-Api-Key: am_live_xxxxxxxxxxxx`
Bearer	`Authorization: Bearer am_live_xxxxxxxxxxxx`
Query	`?api_key=am_live_xxxxxxxxxxxx`

See authentication for security considerations.

Query parameters

Param	Required	Default	Accepted values
`sign`	Yes	—	`Aries`, `Taurus`, `Gemini`, `Cancer`, `Leo`, `Virgo`, `Libra`, `Scorpio`, `Sagittarius`, `Capricorn`, `Aquarius`, `Pisces`
`zodiac_system`	No	`vedic_moon`	`vedic_moon` · `western_sun`
`year`	No	`this-year`	See the year formats section below
`language`	No	`en`	`en` · `hi`

No sub_type parameter. Daily and weekly accept sub_type=love / career to focus a short forecast on one area. Yearly doesn't need this — Love, Career, Money, Family, and Education each have their own dedicated H2 section. One yearly call covers all life areas at full depth. Always returns content equivalent to sub_type=general.

Year formats

The year parameter accepts several formats:

Format	Example	Resolves to
Keyword	`this-year`	Current calendar year (IST)
Keyword	`next-year`	Current year + 1
Keyword	`last-year`	Current year − 1
Year	`2027`	January 1 – December 31, 2027
Any date in year	`2027-06-15`	Extracts the year, returns January 1 – December 31, 2027

Response shape

Successful responses contain a top-level status + success flag, a data object, and a meta envelope:

Field	Type	Description
`status`	integer	HTTP status code echo (200 on success).
`success`	boolean	Always `true` on success.
data
`data.sign`	string	Echo of the requested sign.
`data.zodiac_system`	string	Zodiac system used.
`data.sub_type`	string	Always `general` for yearly.
`data.period_type`	string	Always `yearly` for this endpoint.
`data.period_key`	string	Calendar year key, e.g. `2027`. Stable cache key.
`data.period_start`	string (YYYY-MM-DD)	First day of the target year (always January 1).
`data.period_end`	string (YYYY-MM-DD)	Last day of the target year (always December 31).
`data.language`	string	Language of the returned content.
`data.summary`	string	One-line summary — ideal for push notifications, subject lines, list previews.
`data.content`	string (HTML)	Full content with 10 `<h2>` section headings, `<p>` paragraphs, `<ul>`/`<li>` for dates.
`data.content_text`	string	Plain text with section labels as headings, paragraphs separated by `\n\n`.
`data.content_paragraphs`	array of strings	Each paragraph (and section title) as a separate string.
`data.content_sections`	object	Yearly has 10 keyed sections. See below.
`data.mood`	string	Mood keyword for the year (e.g. `Reflective`, `Transformative`).
`data.key_theme`	string	One-phrase theme for the year.
`data.lucky_number`	integer	Suggested lucky number for the year.
`data.lucky_color`	string	Suggested lucky color.
`data.compatible_sign`	string	Most compatible sign for the year.
`data.ratings.love`	integer (1–5)	Love rating for the year.
`data.ratings.career`	integer (1–5)	Career rating.
`data.ratings.money`	integer (1–5)	Money rating.
`data.ratings.health`	integer (1–5)	Health rating.
`data.ratings.overall`	integer (1–5)	Overall rating.
`data.dos`	array of strings	Recommended actions for the year.
`data.donts`	array of strings	Actions to avoid for the year.
`data.generated_at`	string	When this content was generated (server time).
`data.served_tier`	string	Content tier served (e.g. `canonical`, `premium`).
`data.partner_tier`	string	Your partner tier as configured on the API key.
meta
`meta.endpoint`	string	Echo of the called endpoint path.
`meta.version`	string	API version (currently `3.0`).
`meta.response_time_ms`	integer	Server-side response time in milliseconds.
`meta.timestamp`	string (ISO 8601)	UTC time the response was served.
`meta.credits_remaining`	integer	API credits remaining on your plan.
`meta.request_id`	string	Unique request identifier — include in support tickets.

Note that yearly does not include a lucky_time field (unlike daily, which returns a time window).

The `content_sections` object (yearly has 10 sections)

In addition to the three content formats shared with daily and weekly (content, content_text, content_paragraphs), yearly returns a fourth format: a structured content_sections object with each section as its own keyed entry. Where monthly has 6 sections, yearly has 10 — ideal for tabbed year-ahead UIs, SEO landing pages, calendar imports, and premium PDF reports.

Section key	Returns
`overview`	`{title, body, body_html}` — synthesis of the year's defining theme, opens with the biggest event
`career`	`{title, body, body_html}` — work and profession, Mercury retrograde windows, slow-planet career impact
`money`	`{title, body, body_html}` — income, investments, expenses (Vedic: 2nd/11th/8th bhava framework)
`love`	`{title, body, body_html}` — Venus / Mars transits, marriage muhurat windows for Vedic
`family`	`{title, body, body_html}` — 4th bhava (home, mother, property), parental concerns, family events
`health`	`{title, body, body_html}` — physical and mental health, eclipse/Saturn caution windows
`education`	`{title, body, body_html}` — students, professional upskilling, exam-takers, knowledge acquisition
`travel`	`{title, body, body_html}` — short trips (3rd), long/foreign (9th), foreign residence (12th)
`spirituality`	`{title, body, body_html}` — dharma, sadhana, mantra for the year, retreat windows
`important_dates`	Array of `{date_label, event}` — major astrological dates with significance

Section sub-object shape

Field	Type	Description
`title`	string	English section title (e.g. `"Career & Business"`). Stable across languages.
`body`	string	Plain text body of the section.
`body_html`	string	HTML-wrapped body (e.g. `<p>...</p>`).

Important dates entry shape

Field	Type	Description
`date_label`	string	Human-friendly date label (e.g. `"January 3"`, `"June 9"`).
`event`	string	Description of the astrological event (e.g. `"Saphala Ekadashi, a day for spiritual reflection"`).

Important-dates entries are typically ordered by astrological importance, not chronologically. Headline events (slow planet ingresses, eclipses, retrograde stations) come first; smaller events follow. Sort the array client-side by parsing date_label if you need calendar order. Typically 8–12 entries per year — includes major planet ingresses, eclipses, retrograde stations, Adhik Maas (when applicable), and named panchang days (Ekadashi, Purnima, Amavasya) on premium tier.

The four content formats

Same horoscope, four pre-formatted variants — the same three as daily/weekly, plus the structured sections (monthly has 6 keys, yearly has 10).

Field	Format	Use for
`content`	HTML (with 10 `<h2>` sections)	Web pages, Flutter `Html` widget, WordPress, email bodies, SEO landing pages. H2s give natural heading hierarchy.
`content_text`	Plain text	Voice TTS, plain Text widgets, downloadable PDF reports. Section labels appear as plain headings.
`content_paragraphs`	Array of strings	Custom carousel UIs — each paragraph as a swipeable card. Section titles are array items too.
`content_sections`	Object (10 keys)	Tabbed yearly screens, section-specific notifications, calendar imports, year-ahead landing pages. Each section has its own keyed entry.

Use cases

Tabbed yearly screen — use content_sections with 10 tabs (Overview / Career / Money / Love / Family / Health / Education / Travel / Spirituality / Important Dates). Each pre-formatted as body_html.
Year-ahead calendar widget — iterate content_sections.important_dates as calendar event source. Each entry is ready to import into Google/Apple Calendar.
SEO landing page — drop content into "Cancer 2027 Yearly Horoscope" landing pages. H2 sections give native SEO heading hierarchy. Best for annual search traffic spikes.
New-year email campaign — use full content (HTML with 10 H2s) as email body. Drop summary in subject line. Send January 1.
Annual content piece — aggregate all 12 signs into a single "2027 Astrology Year Ahead" blog/magazine post. Each sign gets a section.
Premium PDF report — render the full 10-section HTML to PDF for a "Year Ahead Report" digital product. Strong December/January sales.
Section-specific notifications — push content_sections.career.body for "Your career outlook for 2027" mid-year reminders.
Onboarding flows — show new subscribers their year-ahead overview as part of first-week welcome sequence.

Premium tier

Premium-tier API keys automatically receive richer yearly content — no extra parameter needed. The endpoint detects your tier from the API key and serves appropriate content, with fallback to canonical content if premium isn't available for your sign/language combination.

Feature	Canonical	Premium
Word count	~1000 words	~1500+ words
Section depth	10 sections	10 sections + deeper analysis per section
Named Ekadashi references (Saphala, Putrada, etc.)	—	✓
Adhik Maas awareness (Purushottam Maas)	—	✓
Sanskrit terminology naturalized	Light	Naturalized (Karka, Guru, Shukra, bhava, drishti)
Practical remedies (mantra/charity/practice)	—	✓ One per major section
Marriage muhurat windows	—	✓ Specific favorable months flagged
Persona voice	Editorial neutral	Custom (e.g. Guruji — 40-year senior Vedic astrologer)

Check data.served_tier in the response to see whether you received canonical or premium content. Apps don't need different code paths — same JSON shape, deeper content.

Content schedule

Yearly content is generated once per year on October 15 for the upcoming calendar year. This gives 2.5 months of lead time before January 1 for SEO indexing, landing page builds, email campaign prep, and year-ahead marketing.

When	What happens
October 15 · 03:00 IST	Yearly canonical cron generates next year's content for all 12 signs across both zodiac systems and supported languages.
October 15 · 03:30 IST	Yearly premium cron runs for premium partners — adds Vedic panchang depth, named vrats, Adhik Maas, persona voice.
October 16 onward	Content live and queryable. `?year=next-year` returns the upcoming year from October 16 onward.
Response time	~30ms typical — pure DB lookup, no AI generation at request time.

Cache for 365 days. Yearly horoscopes don't change once generated. Use data.period_key (e.g. 2027) as your cache key — rotates automatically when the year changes. Safe to cache aggressively client-side, in CDN edge cache, and in your own database.

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	`sign` param not provided
400	`INVALID_SIGN`	Sign name not in 12-sign list
400	`INVALID_ZODIAC_SYSTEM`	Must be `vedic_moon` or `western_sun`
400	`INVALID_LANGUAGE`	Unsupported language code
400	`INVALID_YEAR`	Bad year format. Use `this-year`, `next-year`, `last-year`, `YYYY`, or `YYYY-MM-DD`
401	`AUTH_MISSING_KEY`	No API key in request
401	`AUTH_INVALID_KEY`	Key format invalid or not found
401	`AUTH_REVOKED_KEY`	Key has been revoked
403	`AUTH_ORIGIN_DENIED`	Request from non-whitelisted origin
404	`HOROSCOPE_NOT_AVAILABLE`	Content not yet generated for that year (querying a future year before October 15 cron runs)
429	`RATE_LIMIT_EXCEEDED`	Plan quota exceeded

Error response format

{
  "status": 404,
  "success": false,
  "error": {
    "code": "HOROSCOPE_NOT_AVAILABLE",
    "message": "Horoscope not yet generated for Cancer vedic_moon/en in 2028"
  },
  "meta": {
    "endpoint": "/api/v3/horoscope/yearly",
    "version": "3.0",
    "response_time_ms": 1,
    "timestamp": "2026-05-31T18:33:45+05:30",
    "request_id": "f2d5b26183a6c4b5"
  }
}

const response = await fetch(
  'https://starsapi.com/api/v3/horoscope/yearly?sign=Cancer&year=2027',
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
);
const result = await response.json();

if (result.success) {
  console.log(result.data.summary);
  console.log(result.data.content);          // HTML
  console.log(result.data.lucky_number);
}

import requests
import os

response = requests.get(
    'https://starsapi.com/api/v3/horoscope/yearly',
    headers={'X-Api-Key': os.environ['STARSAPI_KEY']},
    params={'sign': 'Cancer', 'year': '2027'}
)
result = response.json()

if result['success']:
    print(result['data']['summary'])
    print(result['data']['content_text'])
    print(f"Lucky: {result['data']['lucky_number']}")

<?php
$ch = curl_init('https://starsapi.com/api/v3/horoscope/yearly?sign=Cancer&year=2027');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . getenv('STARSAPI_KEY')
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['success']) {
    echo $data['data']['summary'];
    echo $data['data']['content'];          // HTML
    echo "Lucky number: " . $data['data']['lucky_number'];
}

import 'package:http/http.dart' as http;
import 'dart:convert';

Future<Map<String, dynamic>> getHoroscope() async {
  final response = await http.get(
    Uri.parse('https://starsapi.com/api/v3/horoscope/yearly?sign=Cancer&year=2027'),
    headers: {'X-Api-Key': 'YOUR_API_KEY'},
  );
  return jsonDecode(response.body);
}

// Use in a widget:
//   final result = await getHoroscope();
//   final summary = result['data']['summary'];
//   final content = result['data']['content'];   // HTML for flutter_html
//   final mood    = result['data']['mood'];

import Foundation

func getHoroscope() async throws -> [String: Any] {
    var request = URLRequest(url: URL(string:
        "https://starsapi.com/api/v3/horoscope/yearly?sign=Cancer&year=2027"
    )!)
    request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-Api-Key")

    let (data, _) = try await URLSession.shared.data(for: request)
    let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
    return json
}

import okhttp3.*
import org.json.JSONObject

val client = OkHttpClient()

fun getHoroscope(callback: (JSONObject) -> Unit) {
    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/horoscope/yearly?sign=Cancer&year=2027")
        .addHeader("X-Api-Key", "YOUR_API_KEY")
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onResponse(call: Call, response: Response) {
            callback(JSONObject(response.body!!.string()))
        }
        override fun onFailure(call: Call, e: java.io.IOException) {
            e.printStackTrace()
        }
    })
}

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET",
        "https://starsapi.com/api/v3/horoscope/yearly?sign=Cancer&year=2027", nil)
    req.Header.Set("X-Api-Key", os.Getenv("STARSAPI_KEY"))

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    data := result["data"].(map[string]interface{})
    fmt.Println(data["summary"])
}

require 'net/http'
require 'json'

uri = URI('https://starsapi.com/api/v3/horoscope/yearly?sign=Cancer&year=2027')
req = Net::HTTP::Get.new(uri)
req['X-Api-Key'] = ENV['STARSAPI_KEY']

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
res = http.request(req)

data = JSON.parse(res.body)

if data['success']
  puts data['data']['summary']
  puts data['data']['content_text']
  puts "Lucky: #{data['data']['lucky_number']}"
end

200 RESPONSE

{
  "status": 200,
  "success": true,
  "data": {
    "sign": "Cancer",
    "zodiac_system": "vedic_moon",
    "sub_type": "general",
    "period_type": "yearly",
    "period_key": "2027",
    "period_start": "2027-01-01",
    "period_end": "2027-12-31",
    "language": "en",
    "summary": "2027 brings emotional growth and stability for Karka, nurturing relationships and professional opportunities.",
    "content": "<h2>Year Overview</h2><p>This year, the nurturing energies of Chandra guide you towards emotional growth...</p><h2>Career & Business</h2><p>Your professional life will see steady progress...</p><h2>Money & Finance</h2><p>Your financial situation looks stable...</p><h2>Love & Relationships</h2><p>This year, your relationships will flourish...</p><h2>Family & Home</h2><p>Your family life will be filled with warmth...</p><h2>Health & Wellbeing</h2><p>Your health will benefit from a balanced routine...</p><h2>Education & Learning</h2><p>This year is auspicious for acquiring new knowledge...</p><h2>Travel & Foreign</h2><p>Travel opportunities may arise...</p><h2>Spirituality & Growth</h2><p>This year presents a wonderful opportunity for spiritual growth...</p><h2>Important Dates</h2><ul><li><strong>January 3</strong> &mdash; Saphala Ekadashi, a day for spiritual reflection.</li><li><strong>February 14</strong> &mdash; Mercury retrograde begins.</li><li><strong>June 9</strong> &mdash; Guru enters Mithuna, transformative energies arise.</li><li><strong>November 10</strong> &mdash; Favorable muhurat for marriage.</li></ul>",
    "content_text": "Year Overview\n\nThis year, the nurturing energies of Chandra guide you towards emotional growth...\n\nCareer & Business\n\nYour professional life will see steady progress...",
    "content_paragraphs": ["Year Overview", "This year, the nurturing energies of Chandra guide you...", "Career & Business", "Your professional life will see steady progress..."],
    "content_sections": {
      "overview": {
        "title": "Year Overview",
        "body": "This year, the nurturing energies of Chandra guide you towards emotional growth and stability...",
        "body_html": "<p>This year, the nurturing energies of Chandra guide you...</p>"
      },
      "career": {
        "title": "Career & Business",
        "body": "Your professional life will see steady progress, especially with Jupiter influencing your 10th bhava...",
        "body_html": "<p>Your professional life will see steady progress...</p>"
      },
      "money":        { "title": "Money & Finance",      "body": "...", "body_html": "<p>...</p>" },
      "love":         { "title": "Love & Relationships", "body": "...", "body_html": "<p>...</p>" },
      "family":       { "title": "Family & Home",        "body": "...", "body_html": "<p>...</p>" },
      "health":       { "title": "Health & Wellbeing",   "body": "...", "body_html": "<p>...</p>" },
      "education":    { "title": "Education & Learning", "body": "...", "body_html": "<p>...</p>" },
      "travel":       { "title": "Travel & Foreign",     "body": "...", "body_html": "<p>...</p>" },
      "spirituality": { "title": "Spirituality & Growth","body": "...", "body_html": "<p>...</p>" },
      "important_dates": [
        { "date_label": "January 3",   "event": "Saphala Ekadashi, a day for spiritual reflection" },
        { "date_label": "February 14", "event": "Mercury retrograde begins" },
        { "date_label": "April 1",     "event": "Jupiter influences career opportunities" },
        { "date_label": "May 15",      "event": "Mercury retrograde ends" },
        { "date_label": "June 9",      "event": "Guru enters Mithuna, transformative energies arise" },
        { "date_label": "July 15",     "event": "Creative projects and collaborations favored" },
        { "date_label": "October 31",  "event": "Positive energies for family gatherings" },
        { "date_label": "November 10", "event": "Favorable muhurat for marriage" },
        { "date_label": "December 20", "event": "Year-end reflections and planning" }
      ]
    },
    "mood": "Reflective",
    "key_theme": "Inner growth and practical advancements",
    "lucky_number": 8,
    "lucky_color": "Deep Red",
    "compatible_sign": "Pisces",
    "ratings": {
      "love": 4, "career": 4, "money": 3,
      "health": 4, "overall": 4
    },
    "dos": [
      "Engage in regular meditation or yoga practice",
      "Review financial plans during Mercury retrograde",
      "Communicate openly with family members",
      "Seek deeper connections in romantic relationships",
      "Focus on disciplined health practices"
    ],
    "donts": [
      "Sign new contracts during Mercury retrograde",
      "Neglect family relationships",
      "Rush into financial decisions",
      "Skip preventive health check-ups"
    ],
    "generated_at": "2026-05-31 18:14:33",
    "served_tier": "premium",
    "partner_tier": "premium"
  },
  "meta": {
    "endpoint": "/api/v3/horoscope/yearly",
    "version": "3.0",
    "response_time_ms": 12,
    "timestamp": "2026-05-31T18:33:45+05:30",
    "credits_remaining": 199462,
    "request_id": "f2d5b26183a6c4b5"
  }
}