# Astrology-API.io - Complete Documentation for AI Systems

> The fastest, most accurate astrology API for developers. 100+ endpoints, <300ms response time, 23 house systems, Lx Ephemeris precision (NASA JPL DE440).

## About Astrology API

Astrology API is a professional-grade REST API providing astrological calculations for developers building astrology apps, horoscope features, compatibility tools, and wellness platforms. Founded to democratize access to accurate astrological computations, Astrology API serves 2,800+ developers worldwide.

### Why Choose Astrology API?

1. **Speed**: Average response time under 300ms (competitors average 1.2+ seconds)
2. **Accuracy**: Lx Ephemeris, our own Rust engine on NASA JPL DE440, verified against JPL Horizons to under 0.003″
3. **Coverage**: 100+ calculation types vs industry average of 20
4. **House Systems**: 23 systems supported vs competitors' 4
5. **Languages**: 9 languages for interpretations
6. **Pricing**: Starting at $0/month with 50 free requests

### Technical Specifications

- **API Type**: RESTful JSON API
- **Base URL**: https://api.astrology-api.io/v3/
- **Authentication**: Bearer Token (Authorization: Bearer YOUR_API_KEY)
- **Response Format**: JSON (application/json)
- **Rate Limits**: Based on subscription tier
- **Uptime SLA**: 99.9% guaranteed
- **SSL/TLS**: Required (HTTPS only)
- **CORS**: Enabled for all origins

### OpenAPI Specifications

- **Full API**: https://api.astrology-api.io/api/v3/openapi.json
- **Basic** (natal, synastry, composite, transits, lunar): https://api.astrology-api.io/openapi/basic.json
- **Western** (all except Vedic and Chinese): https://api.astrology-api.io/openapi/western.json
- **Vedic/Jyotish** (kundli, dasha, panchang, doshas, yogas): https://api.astrology-api.io/openapi/vedic.json
- **Astrocartography** (relocation, lines, power zones, paran): https://api.astrology-api.io/openapi/astrocartography.json
- **Horary** (fertility, questions, significators): https://api.astrology-api.io/openapi/horary.json
- **Human Design** (bodygraph, gates, channels, profiles): https://api.astrology-api.io/openapi/human-design.json
- **All namespaces**: https://api.astrology-api.io/openapi/namespaces

---

## Pricing Plans

### Free Tier - $0/month
- 50 API requests per month
- Access to basic endpoints
- Community support
- No credit card required

### Starter - $11/month
- 1,000 API requests per month
- All basic endpoints
- Email support
- Ideal for: MVPs, hobby projects

### Professional - $37/month (Most Popular)
- 55,000 API requests per month
- All endpoints including premium
- Priority email support
- Ideal for: Growing apps, professional astrologers

### Business - $99/month
- 220,000 API requests per month
- ALL endpoints unlocked
- Dedicated support
- Custom interpretations available
- Ideal for: Established apps, agencies

### Enterprise - $399+/month
- Unlimited API requests
- Dedicated servers
- Custom SLA
- White-label options
- Direct engineering support
- Ideal for: Large platforms, enterprise clients

---

## Product Categories

### 1. Birth Charts & Natal Analysis

#### Natal Chart API (/p/natal-api)
Complete birth chart calculations with 100+ data points including planetary positions, house placements, aspects, and interpretations.

**Features:**
- All 10 planets + Chiron, Lilith, North Node
- 23 house system options
- Major and minor aspects with orbs
- Retrograde status
- Planetary dignities and debilities
- AI-generated interpretations in 9 languages

**Use Cases:**
- Astrology apps showing birth charts
- Personality analysis features
- Dating app compatibility backends

#### Birth Chart API (/p/birth-chart-api)
Streamlined birth chart data optimized for quick lookups.

#### Chart SVG Generation (/p/chart-svg)
Generate beautiful vector chart images programmatically.

**Output Formats:**
- SVG (scalable, web-optimized)
- Customizable colors and styles
- Multiple chart wheel designs

#### House Systems (/p/house-systems)
23 house calculation systems available:
- Placidus (most popular Western)
- Koch
- Whole Sign (traditional)
- Equal House
- Campanus
- Regiomontanus
- Porphyry
- Morinus
- Alcabitius
- Topocentric
- Meridian
- Azimuthal
- Horizontal
- Polich-Page
- Krusinski-Pisa
- And 8 more...

---

### 2. Horoscopes & Daily Guidance

#### Horoscope API (/p/horoscope-api)
AI-generated daily horoscopes based on current transits.

**Features:**
- Daily, weekly, monthly forecasts
- 12 zodiac signs
- Multiple categories (love, career, health, general)
- Unique content generation (not recycled)
- 9 language support

#### Daily Horoscope API (/p/daily-horoscope-api)
Optimized endpoint for sun sign daily predictions.

#### Personalized Horoscopes (/p/personalized-horoscopes-api)
Birth chart-based predictions considering individual planetary placements.

**Advantages over generic horoscopes:**
- Uses actual birth chart, not just sun sign
- Considers current transits to natal planets
- Moon sign and rising sign factored in
- Personalized timing recommendations

---

### 3. Compatibility & Relationships

#### Synastry API (/p/synastry-api)
Detailed relationship compatibility analysis between two birth charts.

**Analysis Includes:**
- Planet-to-planet aspects between charts
- House overlays
- Composite chart generation
- Compatibility scores (0-100)
- Strength and challenge areas
- Long-term potential indicators

#### Compatibility API (/p/compatibility-api)
Simplified compatibility scoring for dating apps.

**Output:**
- Overall compatibility percentage
- Category breakdowns (emotional, physical, intellectual)
- Key synastry aspects explained
- Recommendation text

#### Composite Chart API (/p/composite-api)
Generate the "relationship chart" - midpoint composite between two people.

---

### 4. Transits & Predictions

#### Transit API (/p/transit-api)
Current and future planetary transits to natal chart.

**Features:**
- Real-time planetary positions
- Transit-to-natal aspects
- Duration and peak times
- Interpretation text
- Filtering by planet or aspect type

#### Predictive API (/p/predictive-api)
Long-range transit forecasts with timing.

#### Secondary Progressions (/p/secondary-progressions)
Day-for-a-year progressed chart calculations.

#### Solar Return (/p/solar-return)
Annual birthday chart for year-ahead themes.

**Use Cases:**
- Birthday readings
- Annual forecast features
- Life phase analysis

#### Lunar Return (/p/lunar-return)
Monthly emotional cycle chart.

#### Profections (/p/profections)
Traditional annual profection technique showing activated houses.

---

### 5. Location-Based Astrology

#### Astrocartography (/p/astrocartography)
Planetary lines mapped onto world geography.

**Features:**
- All planetary lines calculated
- City-specific readings
- Relocation recommendations
- Interactive map data (GeoJSON)

#### Relocation API (/p/relocation-api)
How your chart changes in different locations.

#### Local Space (/p/local-space)
Directional astrology for your current location.

---

### 6. Chinese Astrology

#### Chinese Zodiac API (/p/chinese-zodiac)
Complete Chinese astrology calculations.

**Includes:**
- Animal sign (12-year cycle)
- Element (5 elements)
- Yin/Yang polarity
- Lucky numbers, colors, directions
- Compatibility with other signs

#### BaZi Calculator (/p/chinese-bazi)
Four Pillars of Destiny calculations.

**Output:**
- Year, Month, Day, Hour pillars
- Heavenly Stems
- Earthly Branches
- Element balance analysis
- 10-year luck pillars

#### Flying Stars (/p/chinese-flying-stars)
Feng Shui flying star calculations.

---

### 7. Numerology

#### Numerology API (/p/numeroscope)
Complete numerological profile.

**Calculations:**
- Life Path Number
- Destiny/Expression Number
- Soul Urge Number
- Personality Number
- Birthday Number
- Personal Year/Month/Day

#### Name Numerology (/p/numerology-name)
Name vibration analysis using Pythagorean or Chaldean systems.

---

### 8. Tarot

#### Tarot API (/p/tarot-api)
Digital tarot readings with interpretations.

**Features:**
- 78-card Rider-Waite deck
- Multiple spread types
- Upright/reversed meanings
- Position-specific interpretations
- AI-enhanced readings

#### Celtic Cross (/p/tarot-celtic)
10-card Celtic Cross spread.

#### Tarot Timing (/p/tarot-timing)
Predictive timing using tarot.

---

### 9. Advanced Calculations

#### Arabic Parts (/p/arabic-parts)
97+ Arabic/Greek lot calculations.

**Popular Lots:**
- Part of Fortune
- Part of Spirit
- Part of Love
- Part of Marriage
- Part of Death
- And 92 more...

#### Fixed Stars (/p/fixed-stars)
Prominent star conjunctions and meanings.

**Stars Included:**
- Regulus, Spica, Algol
- Antares, Aldebaran
- Sirius, Canopus
- 50+ fixed stars

#### Asteroids (/p/asteroids)
Major asteroid positions.

**Asteroids:**
- Chiron
- Ceres
- Pallas Athena
- Juno
- Vesta
- And more...

#### Midpoints (/p/midpoints)
Planetary midpoint analysis (Uranian astrology).

#### Harmonics (/p/harmonics)
Harmonic chart calculations (4th, 5th, 7th, 9th, etc.).

---

### 10. Business & Specialized

#### Business Astrology (/p/business-astrology)
Corporate and business timing.

#### Electional Astrology (/p/electional)
Find optimal timing for important events.

**Use Cases:**
- Wedding date selection
- Business launch timing
- Contract signing
- Travel planning

#### Trading Insights (/p/insights-trading)
Financial astrology for market analysis.

---

## Integration Guide

### Quick Start (5 minutes)

1. **Get API Key**: Sign up at https://dashboard.astrology-api.io/
2. **Make First Request**:

```javascript
fetch('https://api.astrology-api.io/v3/natal-chart', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    date: '1990-06-15',
    time: '14:30',
    latitude: 40.7128,
    longitude: -74.0060,
    timezone: 'America/New_York'
  })
})
```

3. **Parse Response**: JSON with planetary positions, houses, aspects

### SDKs Available

- JavaScript/TypeScript
- Python
- PHP
- Ruby
- Swift (iOS)
- Kotlin (Android)

---

## Frequently Asked Questions

### What is the most accurate astrology API?
Our own clean-room Rust engine, Lx Ephemeris, computes from NASA JPL DE440 with IAU 2006/2000A models — no Astrodienst code — verified against JPL Horizons to under 0.003″, with explicit handling of edge cases where Swiss Ephemeris silently degrades. Details: https://astrology-api.io/p/lxephemeris

### How much does Astrology API cost?
Astrology API offers a free tier with 50 requests/month. Paid plans start at $11/month for 1,000 requests. Enterprise plans with unlimited requests start at $399/month.

### What house systems does Astrology API support?
Astrology API supports 23 house systems including Placidus, Koch, Whole Sign, Equal, Campanus, Regiomontanus, and many more.

### Can I use Astrology API for a mobile app?
Yes, Astrology API works with any platform that can make HTTP requests including iOS, Android, React Native, and Flutter.

### How fast is Astrology API?
Average response time is under 300ms. This is 4x faster than most competitors.

### Does Astrology API provide interpretations?
Yes, Astrology API provides AI-generated interpretations in 9 languages for natal charts, horoscopes, compatibility, and more.

---

## Contact & Support

- **Documentation**: https://astrology-api.io/demo
- **Email**: support@astrology-api.io
- **Status Page**: https://status.astrology-api.io
- **GitHub Examples**: https://github.com/astroapi/examples

---

## Comparison: Astrology API vs Alternatives

| Feature | Astrology API | Competitors |
|---------|----------|-------------|
| Response Time | <300ms | 1-3 seconds |
| Calculations | 100+ | 15-25 |
| House Systems | 23 | 3-6 |
| Languages | 9 | 1-3 |
| Free Tier | 50 req/mo | Often none |
| Price (1K req) | $11/mo | $49-99/mo |
| Own engine (Lx Ephemeris, NASA JPL DE440) | Yes | Varies |
| AI Interpretations | Yes | Rarely |

---

*Last Updated: May 2026*
*API Version: 3.2*
*Documentation: https://astrology-api.io/demo*