Horoscope API Documentation

Complete reference for the Cosmic Guide Horoscope API with LLM Integration

Overview

This API allows you to scrape horoscope data from multiple astrological websites, consolidate the information using LLM processing, and retrieve it in a structured format. It's designed to be easy to use while providing powerful data processing capabilities.

Base URL

http://localhost:5000

Authentication

Currently, no authentication is required to use the API. However, the API uses rate limiting to prevent abuse.

Rate Limiting

To prevent overwhelming target websites and the API itself, rate limiting is implemented:

  • API-wide limit: 10 requests per minute
  • Per-domain limit: 5 requests per minute

When a rate limit is exceeded, the API will return a 429 status code with information about how long to wait before retrying.

Endpoints

Get Horoscope

GET /api/horoscope/get/{sign}

Get horoscope for a specific zodiac sign.

Parameters

  • sign (path parameter): Zodiac sign (e.g., aries, taurus, gemini, etc.)
  • date (query parameter, optional): Date in YYYY-MM-DD format. Defaults to today's date.
  • source (query parameter, optional): Specific source to get the horoscope from.

Response

{
  "id": 1,
  "sign": "aries",
  "date": "2025-05-13",
  "prediction": "Today is a good day for new beginnings...",
  "source": "astrology.com",
  "created_at": "2025-05-13T00:00:00.000Z"
}

Get All Horoscopes

GET /api/horoscope/get-all

Get horoscopes for all zodiac signs for a specific date.

Parameters

  • date (query parameter, optional): Date in YYYY-MM-DD format. Defaults to today's date.

Response

{
  "date": "2025-05-13",
  "horoscopes": {
    "aries": [
      {
        "id": 1,
        "sign": "aries",
        "date": "2025-05-13",
        "prediction": "Today is a good day for new beginnings...",
        "source": "astrology.com",
        "created_at": "2025-05-13T00:00:00.000Z"
      },
      {
        "id": 2,
        "sign": "aries",
        "date": "2025-05-13",
        "prediction": "You'll find new opportunities today...",
        "source": "horoscope.com",
        "created_at": "2025-05-13T00:00:00.000Z"
      }
    ],
    "taurus": [
      // Taurus horoscopes...
    ],
    // Other signs...
  }
}

Scrape Horoscope

POST /api/horoscope/scrape

Scrape horoscope for a specific sign from a source.

Request Body

{
  "sign": "aries",
  "source": "astrology.com",  // Optional
  "date": "2025-05-13"  // Optional, defaults to today
}

Response

{
  "success": true,
  "sign": "aries",
  "scraped_date": "2025-05-13",
  "prediction": "Today is a good day for new beginnings...",
  "date": "2025-05-13",
  "source": "astrology.com",
  "source_name": "Astrology.com",
  "type": "horoscope"
}

Scrape All Horoscopes

POST /api/horoscope/scrape-all

Scrape horoscopes for all signs from all sources.

Request Body

{
  "date": "2025-05-13"  // Optional, defaults to today
}

Response

{
  "results": [
    // Array of scraped horoscopes
  ]
}

Consolidate Horoscope

POST /api/horoscope/consolidate/{sign}

Consolidate horoscopes for a specific sign using LLM.

Parameters

  • sign (path parameter): Zodiac sign (e.g., aries, taurus, gemini, etc.)

Request Body

{
  "date": "2025-05-13"  // Optional, defaults to today
}

Response

{
  "message": "Consolidated horoscope created for aries on 2025-05-13",
  "horoscope": {
    "id": 1,
    "sign": "aries",
    "date": "2025-05-13",
    "consolidated_prediction": "The stars align perfectly for you today...",
    "sources": "[\"astrology.com\", \"horoscope.com\"]",
    "created_at": "2025-05-13T00:00:00.000Z"
  }
}

Scheduler API

Various endpoints

Endpoints for managing scheduled jobs.

Get Scheduled Jobs

GET /api/horoscope/schedule
{
  "jobs": [
    {
      "id": 1,
      "name": "scrape_daily_horoscopes",
      "frequency": "daily",
      "last_run": "2025-05-12T00:00:00.000Z",
      "next_run": "2025-05-13T00:00:00.000Z",
      "enabled": true,
      "created_at": "2025-05-01T00:00:00.000Z",
      "active": true
    }
  ]
}

Add Scheduled Job

POST /api/horoscope/schedule

Request Body:

{
  "name": "scrape_daily_horoscopes",
  "frequency": "daily"
}

Remove Scheduled Job

DELETE /api/horoscope/schedule/{name}

Examples

Python Example


import requests
import json

# Get horoscope for Aries
response = requests.get('http://localhost:5000/api/horoscope/get/aries')
data = response.json()
print(f"Aries horoscope: {data['prediction']}")

# Scrape and consolidate horoscope
response = requests.post(
    'http://localhost:5000/api/horoscope/consolidate/taurus',
    json={}  # Use default date (today)
)
consolidated = response.json()
print(f"Consolidated Taurus horoscope: {consolidated['horoscope']['consolidated_prediction']}")
                    

JavaScript Example


// Get all horoscopes for today
async function getAllHoroscopes() {
  const response = await fetch('http://localhost:5000/api/horoscope/get-all');
  const data = await response.json();
  
  // Display each sign's horoscope
  for (const sign in data.horoscopes) {
    const horoscopes = data.horoscopes[sign];
    if (horoscopes.length > 0) {
      console.log(`${sign.toUpperCase()}: ${horoscopes[0].prediction}`);
    }
  }
}

getAllHoroscopes();