Astrology API

#What the Astrology API does

The Astrology API provides 12 specialized endpoints covering the full spectrum of astrological computation and interpretation. From natal chart calculations with AI-powered readings to raw planetary position data, transit forecasts, synastry compatibility analysis, and detailed lunar metrics — everything an astrology app, horoscope service, or wellness platform needs.

#Endpoints at a glance

#Natal charts & birth data

A natal chart (birth chart) maps the positions of the Sun, Moon, planets, and zodiac signs at the exact moment and location of birth. The natal-chart endpoint calculates all of this and returns both the raw computed data and an AI-generated interpretation.

• Sun sign: Core personality and life direction
• Moon sign: Emotional world and inner self
• Rising sign (Ascendant): How others perceive you (requires birth time)
• Planetary positions: Mercury, Venus, Mars, Jupiter, Saturn, and outer planets
• Aspects: Angular relationships between planets (conjunction, trine, square, opposition, sextile)

#POST /v1/astrology/natal-chart

• Best for: Full birth chart generation with personalized AI interpretation
• Required: birth_date (YYYY-MM-DD)
• Optional: birth_time (HH:MM), location (city name or coordinates), language
• Returns: Computed planetary data + AI reading (sun sign, moon sign, rising sign, key aspects, overall analysis)

#POST /v1/astrology/planetary-positions

• Best for: Raw astronomical data for any date — no AI processing
• Required: birth_date or date (YYYY-MM-DD)
• Returns: Sign, degree, and retrograde status for Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn
• Use case: Build your own chart renderer, populate dashboards, power custom interpretations

#Transit forecasts

Transits describe the current movement of planets through the zodiac and how they interact with natal chart positions. The API provides two categories: generic transits (by zodiac sign) and personalized natal transits (compared to your birth chart).

#Generic transits (by sign)

These endpoints produce horoscope-style readings for a zodiac sign. No birth data needed — just pass the sign parameter.

• daily-transit — Today’s forecast covering love, career, and energy level
• weekly-transit — Week overview with highlights, best day, and challenge day
• monthly-transit — Month outlook with career, love, health themes and key dates

#Personalized natal transits

These endpoints compare current planetary positions against your actual natal chart for highly personalized readings. They require birth_date at minimum.

• natal-daily-transit — Exact transit-to-natal aspects for today, with the most significant aspect highlighted
• natal-weekly-transit — Day-by-day personalized outlook for the coming week
• life-forecast — Long-range forecast covering 3 to 12 months with monthly themes and key periods

#Synastry & compatibility

The synastry endpoint compares two natal charts to analyze relationship compatibility. It calculates cross-aspects between both charts and produces numerical scores alongside AI-powered interpretation.

• Cross-aspects: How Person A’s planets interact with Person B’s (conjunctions, trines, squares, etc.)
• Scores: Overall compatibility, romance, communication, and longevity scores (0–100)
• Interpretation: AI reading of strengths, challenges, and practical advice
• Required: birth_date_a and birth_date_b

curl -X POST "https://api.yeb.to/v1/astrology/synastry" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_KEY",
    "birth_date_a": "1990-04-15",
    "birth_date_b": "1992-08-03",
    "birth_time_a": "14:30",
    "birth_time_b": "09:15",
    "location_a": "New York",
    "location_b": "London"
  }'

#Moon phase & lunar data

Three data-only endpoints provide comprehensive lunar information without AI processing, making them fast and cost-effective for real-time displays:

#POST /v1/astrology/moon-phase

• Returns: Phase name, illumination percentage, moon age in days, moon sign
• Optional: date (defaults to today)
• Use case: Widgets, gardening apps, spiritual/wellness platforms

#POST /v1/astrology/lunar-metrics

• Returns: Everything in moon-phase plus distance in km, next full/new moon dates, waxing/waning flag
• Use case: Astronomy apps, tide calculations, detailed lunar dashboards

#POST /v1/astrology/moon-calendar

• Returns: Daily moon data (phase, illumination, sign) and significant events (full moon, new moon) for a date range
• Required: start_date
• Limits: Maximum 31 days per request; end_date defaults to start + 30 days
• Use case: Calendar views, planting guides, event planning tools

#Quick start

# Generate a natal chart
curl -X POST "https://api.yeb.to/v1/astrology/natal-chart" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_KEY",
    "birth_date": "1990-04-15",
    "birth_time": "14:30",
    "location": "New York"
  }'

# Get today's Aries horoscope
curl -X POST "https://api.yeb.to/v1/astrology/daily-transit" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_KEY", "sign": "aries"}'

# Check today's moon phase (data only)
curl -X POST "https://api.yeb.to/v1/astrology/moon-phase" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_KEY"}'

# Compatibility check between two people
curl -X POST "https://api.yeb.to/v1/astrology/synastry" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_KEY",
    "birth_date_a": "1990-04-15",
    "birth_date_b": "1992-08-03"
  }'

#Key parameters explained

#Valid zodiac signs

Pass these lowercase values for the sign parameter:

aries, taurus, gemini, cancer, leo, virgo,
libra, scorpio, sagittarius, capricorn, aquarius, pisces

#Data-only vs AI-powered endpoints

#Real-world use cases

#Daily horoscope app

Challenge: Serve personalized daily horoscopes to millions of users
Solution: Use daily-transit for generic forecasts (cache per sign per day), and natal-daily-transit for premium personalized readings

#Dating app compatibility

Challenge: Show astrological compatibility between matched users
Solution: synastry endpoint returns scores for romance, communication, and longevity — perfect for compatibility badges and detailed reports

#Wellness & planning platform

Challenge: Integrate moon phase data into a wellness/gardening/planning app
Solution: moon-calendar for monthly views, moon-phase for today’s widget, lunar-metrics for detailed astronomical data

#Content generation

Challenge: Generate weekly astrology content for a blog or newsletter
Solution: Loop through 12 signs with weekly-transit or monthly-transit, use the language parameter for multilingual publishing

#Best practices

1. Cache generic transits: Daily/weekly/monthly forecasts are the same for all users of a sign — cache them aggressively
2. Always send birth_time when available: Rising sign and house placements make readings significantly more accurate
3. Use data-only endpoints for dashboards: planetary-positions, moon-phase, and lunar-metrics are fast and cheap
4. Batch moon calendar requests: One moon-calendar call covers up to 31 days, avoiding repeated single-day lookups
5. Use the language parameter: AI endpoints support multilingual output — generate readings in the user’s locale
6. Handle rate limits: Implement exponential backoff for 429 responses
7. Store birth data securely: Birth date + time + location is sensitive personal data — encrypt at rest

#Error handling

• 401: Invalid or missing API key
• 402: Insufficient credits
• 422: Missing required parameters or invalid format (e.g. invalid date, unknown sign)
• 429: Rate limit exceeded
• 500: Server error (retry with exponential backoff)

// Common error responses
{"error": "birth_date is required", "code": 422}
{"error": "sign is required for generic transit forecasts", "code": 422}
{"error": "months must be between 3 and 12", "code": 422}
{"error": "Invalid API key", "code": 401}

#API Changelog