+
+
+
+
+
+
+
+
+
+
+
+ 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();
+