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