#What the Horoscope API does
The Horoscope API provides 10 endpoints covering the full spectrum of astrological and metaphysical readings: zodiac sign profiles, daily/weekly/monthly horoscopes, romantic and friendship compatibility, tarot card spreads, Chinese zodiac profiles and yearly forecasts, moon phase reports, and biorhythm cycles. Every reading is generated with AI and can be personalized using birth date, birth time, and location data for natal-chart-level accuracy.
birth_date, birth_time,
and location to unlock personalized readings based on the user’s full natal chart
rather than sun sign alone.
#Endpoints at a glance
| Endpoint | What it does | Credits |
|---|---|---|
zodiac-profile |
Full zodiac sign profile: element, ruling planet, traits, strengths, weaknesses, and compatibility | 0.02 |
daily-horoscope |
Daily horoscope reading with love, career, health, lucky number, color, and mood | 0.02 |
weekly-horoscope |
Weekly outlook covering all life areas with day-by-day highlights | 0.02 |
monthly-horoscope |
In-depth monthly forecast with key dates, themes, and planetary influences | 0.02 |
compatibility |
Romantic and friendship compatibility score between two zodiac signs | 0.02 |
tarot-reading |
AI-generated tarot card spread with per-card meanings and overall interpretation | 0.03 |
chinese-zodiac |
Chinese zodiac animal profile based on birth year with element and yin/yang | 0.02 |
chinese-year-forecast |
Yearly Chinese zodiac forecast with lucky months and life-area predictions | 0.02 |
moon-phase-report |
Current or date-specific moon phase with energy, mood, and activity guidance | 0.02 |
biorhythm |
Physical, emotional, and intellectual biorhythm cycles with daily advice | 0.02 |
#How personalization works
Most endpoints accept either a sign name (e.g. aries) or a
birth_date in YYYY-MM-DD format. When you provide a birth date,
the API automatically determines the zodiac sign and sets personalized: true
in the response.
For deeper accuracy, add optional birth_time (HH:MM, 24-hour format) and
location (city name or coordinates). This enables natal chart calculations
including rising sign, moon sign, and planetary house positions, which are woven into
the reading.
curl -X POST https://api.yeb.to/v1/horoscope/daily-horoscope \
-H "Content-Type: application/json" \
-d '{
"api_key": "YOUR_KEY",
"birth_date": "1990-05-15",
"birth_time": "14:30",
"location": "New York"
}'
Without birth data, pass sign directly for a general reading:
curl -X POST https://api.yeb.to/v1/horoscope/daily-horoscope \
-H "Content-Type: application/json" \
-d '{
"api_key": "YOUR_KEY",
"sign": "aries"
}'
#Western zodiac endpoints
Four endpoints cover the Western astrological system: zodiac-profile for
static sign data, and daily-horoscope, weekly-horoscope, and
monthly-horoscope for time-based readings.
#POST /v1/horoscope/zodiac-profile
- Best for: Sign overview pages, onboarding flows, profile cards
- Returns: Element, ruling planet, traits, strengths, weaknesses, compatible signs, full description
- Personalized: Add birth data for rising sign and moon sign integration
#POST /v1/horoscope/daily-horoscope
- Best for: Daily horoscope widgets, morning notification content, lifestyle apps
- Returns: General, love, career, health readings plus lucky number, color, and mood
- Optional
date: Fetch a reading for a specific date (YYYY-MM-DD)
#POST /v1/horoscope/weekly-horoscope
- Best for: Weekly newsletter content, planning features
- Returns: Week-level overview with day-by-day highlights and focus areas
#POST /v1/horoscope/monthly-horoscope
- Best for: Monthly forecast features, editorial content
- Returns: In-depth monthly reading with planetary influences, key dates, and themes
- Optional
month: Specify month asYYYY-MM(defaults to current)
#Compatibility analysis
The compatibility endpoint compares two zodiac signs across multiple dimensions:
love, friendship, and communication. Pass either sign names (sign_a + sign_b)
or birth dates (birth_date_a + birth_date_b) for personalized results.
- Scores: Each dimension gets a 0-100 score plus a descriptive analysis
- Overall: Weighted overall compatibility percentage
- Use case: Dating apps, social features, relationship guidance tools
#Tarot card readings
The tarot-reading endpoint simulates a tarot card draw with AI-interpreted
meanings. Three spread types are available:
single— One card draw for a quick insight or daily guidancethree— Past / Present / Future spread (default)celtic_cross— Full 10-card Celtic Cross for deep analysis
Cards are drawn from the full 78-card deck (22 Major Arcana + 56 Minor Arcana) with
reversed positions possible. Pass an optional question to focus the reading
on a specific topic.
#Chinese zodiac
Two endpoints cover the Chinese astrological system:
#POST /v1/horoscope/chinese-zodiac
- Input:
birth_year(e.g. 1988) orbirth_date - Returns: Animal sign, element (wood/fire/earth/metal/water), yin/yang polarity, personality, career, love, and health traits
#POST /v1/horoscope/chinese-year-forecast
- Input: Same as above, plus optional
yearfor the forecast year - Returns: Yearly overview, career, love, health forecasts, and lucky months
- Use case: Lunar New Year features, yearly planning tools
#Moon phases & biorhythm
#POST /v1/horoscope/moon-phase-report
- Returns: Current moon phase name, illumination percentage, moon age in days, and the moon’s zodiac sign
- Reading: Energy description, emotional impact, recommended and discouraged activities
- Optional
date: Query a specific date (defaults to today) - Optional
birth_date: Adds personalized lunar guidance
#POST /v1/horoscope/biorhythm
- Requires:
birth_date(always required for cycle calculation) - Returns: Physical (23-day), emotional (28-day), and intellectual (33-day) cycle values (-100 to +100)
- Reading: Summary plus specific advice for each cycle
- Optional
target_date: Calculate for a future or past date
#Supported zodiac signs
All Western zodiac endpoints accept these 12 sign values (case-insensitive):
| Sign | Dates | Element | Ruling Planet |
|---|---|---|---|
aries | Mar 21 – Apr 19 | Fire | Mars |
taurus | Apr 20 – May 20 | Earth | Venus |
gemini | May 21 – Jun 20 | Air | Mercury |
cancer | Jun 21 – Jul 22 | Water | Moon |
leo | Jul 23 – Aug 22 | Fire | Sun |
virgo | Aug 23 – Sep 22 | Earth | Mercury |
libra | Sep 23 – Oct 22 | Air | Venus |
scorpio | Oct 23 – Nov 21 | Water | Pluto |
sagittarius | Nov 22 – Dec 21 | Fire | Jupiter |
capricorn | Dec 22 – Jan 19 | Earth | Saturn |
aquarius | Jan 20 – Feb 18 | Air | Uranus |
pisces | Feb 19 – Mar 20 | Water | Neptune |
#Language support
Every endpoint accepts an optional language parameter to receive the reading
in a specific language. Pass a two-letter ISO 639-1 code (e.g. en, es,
fr, de, bg, ja, zh).
Defaults to en (English) when omitted.
#Common use cases
- Horoscope apps — Daily push notifications with personalized zodiac readings
- Dating platforms — Compatibility scores as icebreakers or profile features
- Lifestyle & wellness apps — Moon phase rituals, biorhythm tracking, tarot guidance
- Content publishers — Auto-generate daily/weekly/monthly horoscope columns in any language
- Chatbots & virtual assistants — Conversational horoscope readings via API
- E-commerce — Personalized product recommendations based on zodiac traits
- Gaming — Tarot card mini-games, zodiac-themed character creation
#Best practices
- Cache daily readings:
daily-horoscopefor a given sign and date produces consistent results — cache for 24h to save credits - Use birth_date over sign: Birth date unlocks automatic sign detection and personalization; storing the sign on your side is unnecessary
- Progressive personalization: Start with just
sign, then prompt users to add birth date and time for richer readings - Tarot spread selection: Use
singlefor quick daily draws,threefor standard readings,celtic_crossfor premium features - Biorhythm charts: Query multiple
target_datevalues to build a 30-day cycle chart on the frontend - Handle rate limits: Implement exponential backoff for 429 responses
- Language fallback: If a language is not well-supported, the API falls back to English