GET STARTED

Quickstart

1. Get your API key

Visit pricing and choose a plan. API keys are delivered instantly to your dashboard. Keys begin with am_live_ (production) or am_test_ (sandbox).

Throughout these docs, code samples use YOUR_API_KEY as a placeholder. Replace it with the key from your dashboard before running any sample.

2. Make your first call

Fetch today's general horoscope for Aries (default Vedic Moon-sign system, English). Use the language switcher on the right to view the request in your stack — cURL, JavaScript, Python, PHP, Flutter, Swift, Kotlin, Go, or Ruby.

3. Read the response

All StarsAPI responses follow the envelope format: { "status": 200, "success": true, "data": {...}, "meta": {...} } on success, or { "success": false, "error": {"code": "...", "message": "..."} } on failure. See the errors reference for the full list of error codes.

The data object always includes three pre-formatted content fields — content (HTML), content_text (plain), and content_paragraphs (array). Pick whichever fits your platform; no parser needed.

4. Add authentication

Pass your API key in the X-Api-Key request header on every call. Bearer and query-string methods also work but the header method is the recommendation for production. See authentication for details.

Next steps

Browse the Daily Horoscope reference for all parameters, response fields, and error codes.
Press ⌘K or Ctrl+K to search for any endpoint.

REQUEST

# Replace YOUR_API_KEY with the key from your dashboard
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://starsapi.com/api/v3/horoscope/daily?sign=Aries"

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",
    "summary": "A day to reflect and nurture your inner strength.",
    "content": "<p>With Chandra nestled in Scorpio today...</p>",
    "mood": "Introspective",
    "lucky_number": 8,
    "lucky_color": "Deep red"
  },
  "meta": {
    "endpoint": "/api/v3/horoscope/daily",
    "version": "3.0",
    "response_time_ms": 4,
    "request_id": "df70f3d9aa568b5f"
  }
}