GET · HOROSCOPE

Daily Horoscope

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

Returns daily horoscope content for a single zodiac sign. One endpoint covers every combination — 12 signs × 2 zodiac systems × 3 sub-types × supported languages. Content is generated nightly at 03:00 IST and served from cache thereafter (typical response under 50 ms).

Authentication

Required. Three methods accepted:

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

See authentication for security considerations.

Free Plan Returns Sample Content

On the free plan this endpoint returns a fixed sample horoscope. The same content comes back for every date, sign system and language, and the response carries "is_sample": true along with "served_tier": "sample".

The sample matches the live response field for field, so you can build and test your entire integration on it — parsing, UI, caching, error handling. Live content, generated fresh every night, requires a paid plan. See pricing.

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	`today`	`today` · `tomorrow` · `yesterday` · `YYYY-MM-DD`
`language`	No	`en`	`en` · `hi` (Tamil, Telugu, Bengali, Marathi, Gujarati, Kannada, Malayalam, Punjabi, Odia, Assamese coming soon)

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 `daily` for this endpoint.
`data.date`	string (YYYY-MM-DD)	The date this horoscope is for.
`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. `Nurturing`, `Introspective`).
`data.lucky_number`	integer	Suggested lucky number.
`data.lucky_color`	string	Suggested lucky color.
`data.lucky_time`	string	Time window of the day favourable for important actions.
`data.compatible_sign`	string	Most compatible sign for the day.
`data.ratings.love`	integer (1–5)	Love rating for the day.
`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 day.
`data.donts`	array of strings	Actions to avoid for the day.
`data.key_theme`	string	One-phrase theme for the day.
`data.generated_at`	string	When this content was generated (server time).
`data.served_tier`	string	Content tier served: `sample` (free plan), `canonical`, or `premium`.
`data.partner_tier`	string	Your partner tier as configured on the API key.
`data.is_sample`	boolean	`true` when sample content was served (free plan). `false` on all paid plans.
`data.notice`	string \| null	Plain-language explanation when `is_sample` is `true`. `null` otherwise.
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

Mobile app — use content with Flutter Html widget or React Native HTML renderer, or content_text for native Text widgets.
Web site — drop content into innerHTML. Paragraph tags render natively.
Email newsletter — use content directly in HTML email body.
WhatsApp / SMS bot — use content_text for plain text with paragraph breaks.
Voice / TTS — content_text with \n\n separators gives natural pauses.
Push notifications — use summary, purpose-built for short previews under 100 chars.
Dashboard widgets — use ratings for 5-star bars, lucky_* for highlight tiles, mood for emoji.

Fetching all 12 signs at once

For sign-picker UIs or dashboard widgets, 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/daily?sign=${s}`, {
    headers: { 'X-Api-Key': 'YOUR_API_KEY' }
  }).then(r => r.json()))
);

Cache for the day. Horoscope content does not change within a day. Fetch once per app session and cache until next IST midnight (localStorage, Hive, shared_preferences, Redis, etc.).

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 generated yet for that date
429	`RATE_LIMIT_EXCEEDED`	Plan quota exceeded

Error response format

{
  "success": false,
  "error": {
    "code": "INVALID_SIGN",
    "message": "Invalid sign: 'Ares'. Must be one of: Aries, Taurus, ..."
  }
}

Content schedule

03:00 IST — daily horoscopes generated for all 12 signs × 2 zodiac systems × 3 sub-types × supported languages.
~04:00 IST — all content ready. Endpoint returns fresh content for ?date=today.
~50ms response — after generation, the endpoint is a DB lookup; never blocks on AI at request time.

const response = await fetch(
  'https://starsapi.com/api/v3/horoscope/daily?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/daily',
    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/daily?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/daily?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/daily?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/daily?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/daily?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/daily?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": "daily",
    "date": "2026-05-31",
    "language": "en",

    "summary": "A day to reflect and nurture your inner strength.",

    "content": "<p>With Chandra nestled in Scorpio today...</p><p>...</p>",
    "content_text": "With Chandra nestled in Scorpio today...\n\n...",
    "content_paragraphs": ["With Chandra nestled in Scorpio today...", "...", "..."],

    "mood": "Introspective",
    "lucky_number": 8,
    "lucky_color": "Deep red",
    "lucky_time": "11:00 AM - 1:00 PM",
    "compatible_sign": "Scorpio",

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

    "dos": ["Engage in deep self-reflection", "Practice open communication"],
    "donts": ["Suppress your emotions", "Rush into decisions"],

    "key_theme": "Embrace the depths of your being",
    "generated_at": "2026-05-30 03:30:08",

    "served_tier": "canonical",
    "partner_tier": "canonical"
  },
  "meta": {
    "endpoint": "/api/v3/horoscope/daily",
    "version": "3.0",
    "response_time_ms": 4,
    "timestamp": "2026-05-31T12:59:35+05:30",
    "credits_remaining": 199492,
    "request_id": "df70f3d9aa568b5f"
  }
}