GET · HOROSCOPE

Weekly Horoscope

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

Returns the 7-day weekly horoscope (Monday through Sunday, IST) for a single zodiac sign. Shares the same response shape as Daily Horoscope — only the period fields differ. Cached per (sign, ISO week, sub_type, zodiac_system, language) tuple. Typical response under 50 ms.

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`
`sub_type`	No	`general`	`general` · `love` · `career`
`date`	No	`this_week`	See the date formats section below
`language`	No	`en`	`en` · `hi`

Date formats

The date parameter accepts several formats — pick whichever fits your client code:

Format	Example	Resolves to
Keyword (hyphen or underscore)	`this-week` or `this_week`	Mon–Sun of current week (IST)
Keyword	`next-week` or `next_week`	Mon–Sun of upcoming week
Keyword	`last-week` or `last_week`	Mon–Sun of previous week
ISO week	`2026-W22`	The specific ISO 8601 week (May 25–31, 2026)
Any date in week	`2026-05-27`	Mon–Sun of the week containing that date

ISO 8601 weeks always start Monday and end Sunday. The week containing January 4 is always W01. Use meta.endpoint + data.period_key as a stable cache key — rotates naturally each week.

Response shape

Successful responses contain a top-level status + success flag, a data object with the horoscope content, and a meta envelope with request metadata:

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	Sub-type returned.
`data.period_type`	string	Always `weekly` for this endpoint.
`data.period_key`	string	ISO 8601 week key, e.g. `2026-W22`. Stable cache key.
`data.period_start_date`	string (YYYY-MM-DD)	Monday of the target week.
`data.period_end_date`	string (YYYY-MM-DD)	Sunday of the target week.
`data.language`	string	Language of the returned content.
`data.summary`	string	Short single-line summary — ideal for push notifications, list previews.
`data.content`	string (HTML)	Full horoscope wrapped in `<p>` tags. Use for web, Flutter `Html` widget, email bodies.
`data.content_text`	string	Plain text with `\n\n` between paragraphs. Use for SMS, WhatsApp/Telegram bots, voice TTS.
`data.content_paragraphs`	array of strings	Each paragraph as a separate string — for custom UI per-paragraph styling.
`data.mood`	string	Mood keyword (e.g. `Transformative`, `Inspirational`).
`data.lucky_number`	integer	Suggested lucky number for the week.
`data.lucky_color`	string	Suggested lucky color.
`data.lucky_time`	null	Not applicable for weekly — always `null`. See Daily Horoscope for time-of-day windows.
`data.compatible_sign`	string	Most compatible sign for the week.
`data.ratings.love`	integer (1–5)	Love rating for the week.
`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 week.
`data.donts`	array of strings	Actions to avoid for the week.
`data.key_theme`	string	One-phrase theme for the week.
`data.generated_at`	string	When this content was generated (server time).
`data.served_tier`	string	Content tier served (e.g. `canonical`).
`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.

The three content formats

Each response returns the same horoscope in three pre-formatted variants so you don't need a parser:

Field	Format	Use for
`content`	HTML	Web pages (drop into `innerHTML`), Flutter `Html` widget, WordPress, email bodies.
`content_text`	Plain text	SMS, WhatsApp/Telegram bots, voice TTS, plain Text widgets.
`content_paragraphs`	Array of strings	Custom UI where each paragraph should be styled independently.

Use cases

Weekly tab in a mobile app — use content with Flutter Html widget, with period_start_date / period_end_date rendered as a "May 25 – May 31" header.
Monday morning newsletter — use content as email body, summary in the subject line. Send Monday 06:00 IST after Sunday generation.
Sunday evening push — notify users with summary for the week ahead.
WhatsApp / Telegram bot — use content_text for plain text with natural paragraph breaks.
Carousel UI — use content_paragraphs array to make each paragraph a swipeable card.
Weekly rating dashboard — use ratings for 5-star bars, mood for emoji headers.

Fetching all 12 signs at once

For weekly sign-picker screens or full-zodiac dashboards, fetch all 12 signs in parallel. Each call counts as one request against your quota.

// JavaScript
const signs = ['Aries','Taurus','Gemini','Cancer','Leo','Virgo',
               'Libra','Scorpio','Sagittarius','Capricorn','Aquarius','Pisces'];

const all = await Promise.all(
  signs.map(s => fetch(
    `https://starsapi.com/api/v3/horoscope/weekly?sign=${s}&date=this_week`,
    { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
  ).then(r => r.json()))
);

Cache for 7 days. Weekly horoscopes don't change Mon–Sun. Use data.period_key (e.g. 2026-W22) as your cache key — it rotates automatically when the week changes. Fetch once at app open or week start, cache until the next Sunday after generation.

Errors

HTTP	Code	Cause
400	`MISSING_SIGN`	`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_SUB_TYPE`	Must be `general`, `love`, or `career`
400	`INVALID_LANGUAGE`	Unsupported language code
400	`INVALID_DATE`	Bad date format
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 week (querying a future week before its cron runs)
429	`RATE_LIMIT_EXCEEDED`	Plan quota exceeded

Error response format

{
  "status": 404,
  "success": false,
  "error": {
    "code": "HOROSCOPE_NOT_AVAILABLE",
    "message": "Weekly horoscope not yet generated for Aries / vedic_moon / general / 2026-W25 / en"
  },
  "meta": {
    "endpoint": "/api/v3/horoscope/weekly",
    "version": "3.0",
    "response_time_ms": 2,
    "timestamp": "2026-05-31T13:56:38+05:30",
    "request_id": "321ce360c8fef1aa"
  }
}

const response = await fetch(
  'https://starsapi.com/api/v3/horoscope/weekly?sign=Aries',
  { 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/weekly',
    headers={'X-Api-Key': os.environ['STARSAPI_KEY']},
    params={'sign': 'Aries'}
)
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/weekly?sign=Aries');
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/weekly?sign=Aries'),
    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/weekly?sign=Aries"
    )!)
    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/weekly?sign=Aries")
        .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/weekly?sign=Aries", 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/weekly?sign=Aries')
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": "Aries",
    "zodiac_system": "vedic_moon",
    "sub_type": "general",
    "period_type": "weekly",
    "period_key": "2026-W22",
    "period_start_date": "2026-05-25",
    "period_end_date": "2026-05-31",
    "language": "en",

    "summary": "Embrace transformation and partnerships this week, dear one.",

    "content": "<p>This week, dear one, begins with a gentle embrace as Chandra enters Kanya on Monday...</p><p>...</p>",
    "content_text": "This week, dear one, begins with a gentle embrace as Chandra enters Kanya on Monday...\n\n...",
    "content_paragraphs": ["This week, dear one, begins with a gentle embrace...", "On Wednesday...", "..."],

    "mood": "Transformative",
    "lucky_number": 7,
    "lucky_color": "blue",
    "lucky_time": null,
    "compatible_sign": "Leo",

    "ratings": {
      "love": 4, "career": 3, "money": 3,
      "health": 4, "overall": 4
    },

    "dos": ["Practice self-care", "Engage in open communication", "Embrace transformation"],
    "donts": ["Avoid neglecting your health", "Rush financial decisions", "Express anger without reflection"],

    "key_theme": "Nurturing transformation in partnerships",
    "generated_at": "2026-05-21 10:42:25",

    "served_tier": "canonical",
    "partner_tier": "canonical"
  },
  "meta": {
    "endpoint": "/api/v3/horoscope/weekly",
    "version": "3.0",
    "response_time_ms": 5,
    "timestamp": "2026-05-31T13:28:46+05:30",
    "credits_remaining": 199491,
    "request_id": "11c59634be1a6842"
  }
}