✨ Powered by Swiss Ephemeris

Professional astrology
calculations as an API

Birth charts, daily horoscopes, moon phases, retrograde alerts, and compatibility scores — JSON responses in milliseconds.

Get API Key — It's free View Endpoints
# Get a birth chart GET /v1/birth-chart?date=1990-04-15&time=14:30&latitude=40.7128&longitude=-74.0060 X-API-Key: sw_your_key_here → { "sunSign": { "name": "Aries", "element": "Fire", "symbol": "♈" }, "moonSign": { "name": "Cancer", "element": "Water", "symbol": "♋" }, "risingSign": { "name": "Leo", "element": "Fire", "symbol": "♌" }, "planets": [ ... ], "aspects": [ ... ] }
Endpoints

Everything your astrology app needs

Six endpoints covering the full astrological toolkit. All return clean JSON.

GET /v1/birth-chart

Complete natal chart: Sun/Moon/Rising, all 10 planetary positions with houses, 12 house cusps (Placidus), and all major aspects. The core money-maker endpoint.

date time latitude longitude timezone
GET /v1/compatibility

Synastry compatibility score (0–100), element harmony, Venus/Mars interplay, Moon resonance, and personalized highlights for two people.

person1_date person1_time person1_lat person1_lon person2_date person2_time person2_lat person2_lon
GET /v1/daily-horoscope

Daily horoscope text, mood of the day, lucky number, lucky color, and tagline — deterministically seeded per sign and date.

sign date
GET /v1/transits

Current sky snapshot: all planetary positions, active aspects between transiting planets, retrograde status for all 8 planets, and moon phase.

date latitude longitude
GET /v1/moon-phase

Phase name, illumination %, cycle day, moon sign, next full & new moon dates, ritual suggestion, and energy description.

date
GET /v1/retrograde

Retrograde periods for any planet in any year: start/end dates, shadow period, affected zodiac sign, what it means, and current status.

planet year
Quickstart

Running locally in 60 seconds

# Clone and run git clone https://github.com/you/star-witness-api cd star-witness-api # Run in demo mode (no API key required) STAR_WITNESS_DEMO_MODE=1 swift run # Test an endpoint curl "http://localhost:8080/v1/moon-phase" # With an API key curl -H "X-API-Key: sw_free_demo_key_123" \ "http://localhost:8080/v1/daily-horoscope?sign=scorpio" # Birth chart curl -H "X-API-Key: sw_free_demo_key_123" \ "http://localhost:8080/v1/birth-chart?date=1990-04-15&time=14:30&latitude=40.7128&longitude=-74.0060"
Pricing

Simple, transparent pricing

Start free. Scale as you grow. No credit card required to get started.

Free
$0 /mo
100 requests / day
  • All 6 endpoints
  • JSON responses
  • No credit card
Starter
$9 /mo
1,000 requests / day
  • Everything in Free
  • Email support
  • Usage dashboard
Pro
$29 /mo
10,000 requests / day
  • Everything in Starter
  • Priority support
  • Webhook alerts
Enterprise
$99 /mo
Unlimited requests
  • Everything in Pro
  • SLA guarantee
  • Dedicated support
AI Agents

Built for AI agent discovery

Claude, GPT-4, Gemini, and any agent that supports OpenAPI or function calling can read this API natively. The spec is served at /v1/openapi for programmatic consumption.

📄

OpenAPI Specification

Full OpenAPI 3.0 spec covering all 25 endpoints with parameter types, response schemas, and examples. Import directly into any compatible tool.

GET /v1/openapi openapi.yaml
🤖

Function Calling Schemas

Pre-built tool schemas for Anthropic and OpenAI function calling formats. Drop them into your agent's tool list — no manual schema writing needed.

AGENTS.md
🔌

MCP Integration

Wrap any endpoint as an MCP tool for Claude Desktop, Cursor, or any MCP-compatible host. Step-by-step server code included.

MCP guide
💬

Example agent prompts

Phrases that naturally trigger an agent to call these endpoints:

  • What's my horoscope today? I'm a Scorpio.
  • Do a Celtic Cross tarot reading for me.
  • Is Mercury in retrograde right now?
  • What crystals are good for my heart chakra?
  • Calculate my life path number — born June 21, 1990.
  • What's tonight's moon phase?
# Auto-discover the spec (no auth required) curl https://star-witness-api-production.up.railway.app/v1/openapi # Anthropic Python SDK — pass function schemas from AGENTS.md import anthropic client = anthropic.Anthropic(api_key="...") response = client.messages.create( model="claude-opus-4-6", tools=star_witness_tools, # schemas from AGENTS.md messages=[{"role": "user", "content": "What's the moon phase tonight?"}] )

Ready to ship? ✨

Get your free API key and start returning birth charts in minutes. No credit card required.

Get API Key View on GitHub

Demo keys for local testing are hardcoded in APIKeyMiddleware.swift