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": "2026-05-30T00:00:00.000Z",
    "content": "Today brings dynamic energy and new opportunities for Aries...",
    "transits": [
      {
        "id": "dt_abc123",
        "date": "2026-05-30T00:00:00.000Z",
        "dailyInsight": "The Scorpio Moon dives beneath the surface..."
      }
    ],
    "updatedAt": "2026-05-30T02:02:20.331Z"
  },
  "meta": {
    "creditsUsed": 1,
    "creditsRemaining": 1999
  }
}

Note: the sign parameter is case-insensitive (/aries and /ARIES both work).

---

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!