Skip to content

Horoscope Reports API Overview

Build astrology products on a deterministic Swiss Ephemeris-powered engine designed for production apps.

Engine Quality Editorial Model Modes Reports Language

This API supports two high-value report modes:

  • Public mode for stable sign-based output at scale.
  • Personalized mode for birth-data-aware editorial reports with deeper vectors (houses, aspects, timing dynamics).

Language note: engine-backed /api/v1/horoscope/reports/* endpoints currently support English only (lang=en). Non-report endpoints may support translator-helper language options where documented.

Zodiac System Response Clarity

When you select zodiac_system: "tropical", the report computation remains tropical. When you select zodiac_system: "sidereal", the report computation remains sidereal.

If no zodiac_system is provided in the request body, the engine defaults to tropical.

You may still see tropical, sidereal, and ayanamsa-related fields in the response metadata regardless of the selected mode.

These fields are returned for comparison, transparency, and observability only. They do not override or alter the actual report calculations for the selected zodiac system.

Daily App UI Stats Spotlight

Main daily personalized endpoints expose rich UI-friendly stats at data.daily_personalized_stats.

App UI Stats Activation Payload Chart Packs

Personalized daily stats include:

  • overall_pulse
  • archetype_scores
  • harmony_discord
  • elemental_balance
  • momentum_channels
  • confidence tiers per block

Use daily_stats_detail: "full" | "compact" to control payload density for mobile/web clients.

Architecture

Full Engine Architecture

Full Horoscope Engine Architecture

Request to Response Architecture

Horoscope Request-to-Response Architecture

Runtime Breakdown

The production horoscope stack follows a deterministic pipeline:

  1. API Gateway validates auth, quota, and request policy.
  2. FastAPI app validates contract and checks cache.
  3. HoroscopeService resolves sign, period window, ephemeris config, and mode.
  4. EphemerisEngine computes positions, aspects, houses, rising sign.
  5. AggregationEngine extracts period events, metrics, and ranked drivers.
  6. InterpretationEngine maps factor stacks to editorial output with traceability.
  7. Response is assembled, wrapped with metadata, and cached.

This architecture gives repeatable outputs for identical payloads while still enabling deep personalization for paid app experiences.

Trust Model: Closed Core + Open Source Lite

Our main engine is closed-source and optimized for enterprise-grade deterministic reports, premium editorial layers, and production reliability.

To promote transparency and developer trust, we also maintain a robust lightweight open-source engine:

Use OpAstro to evaluate engine quality quickly, then scale to NumerologyAPI enterprise routes for richer report layers, broader endpoint coverage, and managed production operations.

Start Here

Quickstart: Personalized Daily + App Stats

curl --request POST \
  --url "https://api.numerologyapi.com/api/v1/horoscope/reports/today?lang=en" \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "dob": "1992-07-16",
  "timezone": "America/New_York",
  "birth_time": "13:45",
  "birth_latitude": 40.7128,
  "birth_longitude": -74.0060,
  "birth_timezone": "America/New_York",
  "daily_stats_detail": "compact"
}'

This returns a live daily report plus data.daily_personalized_stats for app cards and trend modules.

Route Selection Guide

Goal Recommended Endpoint Family
General sign-based daily report /horoscope/reports/today, /horoscope/reports/tomorrow, /horoscope/reports/yesterday
Personalized daily report + app stats cards Daily main routes with birth_time, coordinates, and daily_stats_detail
Periodic general reports /horoscope/reports/weekly, /horoscope/reports/monthly, /horoscope/reports/yearly
Section-specific reports (career, health, money, communication, friendship, lifestyle, love) Section routes across periods
Planet-focused editorial reports Planetary routes
Aspect-focused editorial reports Aspects routes
Transit-focused editorial reports Transits routes
House-focused personalized reports House routes
Planet-house personalized reports Planet-house routes
High-detail natal chart + wheel artifacts Birth chart routes

Endpoint Map

Use this map to jump directly to the exact route family your product needs.

Natal Chart and Foundations

Daily Horoscope

Weekly Horoscope

Monthly Horoscope

Yearly Horoscope

Love Horoscope

Planetary, Aspect, Transit, and House Reports

Zodiac Sign Descriptions (Not Live Reports)

These /api/v1/horoscope/sign/* endpoints return descriptive sign archetype meanings, not live astrological reports. Use /api/v1/horoscope/reports/* for live report generation.

Compatibility and Encyclopedia

Best For

  • Astrology mobile and web apps
  • Personalized daily report feeds and newsletters
  • Compatibility and relationship products
  • Wellness, coaching, and spiritual dashboards
  • Enterprise integrations that need deterministic repeatability

Powered by NumerologyAPI.com