Horoscope Endpoints

Daily horoscopes for all zodiac signs at 1 credit each.

Perfect for horoscope apps, daily forecasts, and zodiac content.

---

Get Horoscope for Specific Sign

Get today's horoscope for a specific zodiac sign.

Endpoint

GET /api/v1/horoscope/:sign

Pricing

1 credit - Fixed cost

URL Parameters

:sign - Zodiac sign (lowercase)

Valid signs:

• aries, taurus, gemini, cancer, leo, virgo
• libra, scorpio, sagittarius, capricorn, aquarius, pisces

Example Request

GET /api/v1/horoscope/aries

Response Example

{
  "success": true,
  "data": {
    "sign": "aries",
    "date": "2025-01-15",
    "content": "Today brings dynamic energy and new opportunities for Aries. The planetary alignments favor bold action and innovation. Your passionate nature is heightened, making this an excellent time for pursuing your goals with confidence...",
    "transits": [
      {
        "planet": "Mars",
        "aspect": "trine",
        "description": "Mars trine your Sun brings vitality and drive"
      }
    ],
    "updatedAt": "2025-01-15T00:00:00Z"
  },
  "meta": {
    "creditsUsed": 1,
    "creditsRemaining": 1999
  }
}

---

Get Horoscopes for All Signs

Get today's horoscopes for all 12 zodiac signs in a single request.

Endpoint

GET /api/v1/horoscope/all

Pricing

1 credit - Fixed cost (92% cheaper than 12 individual requests!)

Response Example

{
  "success": true,
  "data": {
    "date": "2025-01-15",
    "horoscopes": {
      "aries": {
        "sign": "aries",
        "content": "Today brings dynamic energy and new opportunities for Aries...",
        "preview": "Today brings dynamic energy and new opportunities...",
        "updatedAt": "2025-01-15T00:00:00Z"
      },
      "taurus": {
        "sign": "taurus",
        "content": "Stability and comfort are your themes today...",
        "preview": "Stability and comfort are your themes...",
        "updatedAt": "2025-01-15T00:00:00Z"
      },
      "gemini": { /* ... */ },
      "cancer": { /* ... */ },
      "leo": { /* ... */ },
      "virgo": { /* ... */ },
      "libra": { /* ... */ },
      "scorpio": { /* ... */ },
      "sagittarius": { /* ... */ },
      "capricorn": { /* ... */ },
      "aquarius": { /* ... */ },
      "pisces": { /* ... */ }
    },
    "count": 12
  },
  "meta": {
    "creditsUsed": 1,
    "creditsRemaining": 1998
  }
}

---

Horoscope Content

Each horoscope includes:

• content - Complete AI-generated daily horoscope text covering general energy, relationships, career, and wellness
• transits (single sign only) - Current planetary aspects affecting the sign
• preview (all signs endpoint only) - First ~100 characters of the full content
• sign - Zodiac sign (lowercase: aries, taurus, etc.)
• date - Date of the horoscope (YYYY-MM-DD)
• updatedAt - Last update timestamp (ISO 8601)

---

Use Cases

Horoscope Apps

Single Sign Endpoint:

• User-specific daily horoscopes
• Personal zodiac notifications
• Customized daily forecasts

All Signs Endpoint:

• Browse all horoscopes feature
• Zodiac comparison tools
• Complete daily horoscope section

Content Platforms

Blog/Website:

• Daily horoscope widgets
• Zodiac content sections
• Email newsletter content

Social Media:

• Automated horoscope posts
• Daily zodiac stories
• Engagement content

Astrology Services

Personal Services:

• Client daily insights
• Supplementary guidance
• Quick reference tool

---

Cost Comparison

💡 Pro Tip: Use /horoscope/all and cache the results if you need multiple signs. It's 12× more cost-effective!

---

Horoscope Generation

Horoscopes are:

• ✓ Generated fresh daily
• ✓ Cached for 24 hours
• ✓ Based on current planetary positions
• ✓ Updated at midnight UTC
• ✓ Consistent across all requests for the same day

---

Error Responses

{
  "error": "Invalid zodiac sign",
  "message": "Sign must be one of: aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, pisces"
}

{
  "error": "Insufficient credits",
  "message": "This horoscope costs 1 credit",
  "required": 1,
  "available": 0
}

---

Free in UI Mode

Important: Daily horoscopes are FREE when accessed through the web UI at /horoscope. API access costs 1 credit per request.

Perfect for integrating horoscope features into your own applications!