Why You Need an Astrology API
If you are building an app, website, or bot that involves astrology, you have two options: write the astronomical calculation engine yourself, or use an API.
Writing it yourself means implementing the Swiss Ephemeris from scratch (or wrapping the C library), handling timezone conversions for any location on Earth across any date in history, computing house cusps under multiple house systems, calculating geometric aspects with proper orb tables, and maintaining all of this as your application evolves. This is months of specialized work, and any bugs produce wrong charts -- wrong charts that your users will notice and leave over.
Using an API means sending a request with a birth date, time, and coordinates, and receiving a complete, accurate chart in JSON format. You focus on your application logic and user experience. The API handles the astronomy.
The question is not whether to use an API. The question is which one.
What an Astrology API Does
At its core, an astrology API performs astronomical calculations and returns structured data. A request includes birth data (date, time, geographic coordinates) and the API returns planetary positions, house cusps, aspects, and derived astrological data.
The calculation pipeline looks like this:
- Input normalization: Convert the provided date, time, and location into a Julian Day Number in Universal Time, accounting for timezone and daylight saving time rules at the specified location on the specified date
- Ephemeris lookup: Calculate planetary positions using the Swiss Ephemeris (or equivalent), returning ecliptic longitude, latitude, speed, and distance for each body
- House calculation: Compute house cusps based on the selected house system (Placidus, Whole Sign, Koch, Equal, etc.) using the observer's geographic latitude and the local sidereal time
- Aspect calculation: Determine all geometric aspects between planets based on angular separation and configurable orb tables
- Derived data: Compute additional astrological data -- essential dignities, lots/Arabic parts, sect, planetary hours, fixed star conjunctions, and specialized techniques
A comprehensive API handles all five layers and exposes endpoints for each.
Astro Engine API: 121+ Endpoints
Astro Engine provides the most comprehensive public astrology API currently available, with over 121 endpoints covering natal, synastry, predictive, traditional, electional, and Hamburg School techniques.
Base URL: https://astro-engine.com/api/v1
Calculation Engine: Swiss Ephemeris (DE441 ephemeris dataset)
Authentication: API key via Bearer token
Endpoint Categories
Natal Chart Endpoints
The foundation of any astrology application. These endpoints calculate complete birth chart data.
POST /chart/natal Full natal chart (planets, houses, aspects, dignities)
POST /chart/natal/svg Natal chart as SVG image
POST /chart/natal/png Natal chart as PNG image
POST /chart/natal/pdf Natal chart as PDF report
POST /chart/natal/reading AI-generated natal chart reading (Premium)
POST /chart/natal/report/pdf Complete report with interpretations (Pro)
POST /chart/natal/dispositor-svg Dispositor tree diagram
Transit Endpoints
Track current and future planetary movements relative to a natal chart.
POST /chart/transit Transit chart for a specific date
POST /chart/transit/svg Transit chart as SVG overlay
GET /horoscope/daily Daily transit summary for all signs
GET /horoscope/daily/{sign} Daily transit summary for one sign
GET /horoscope/weekly/{sign} Weekly forecast
GET /horoscope/monthly/{sign} Monthly forecast
POST /predictive/transit-search Find future transits to natal points
Synastry and Relationship Endpoints
Compare two charts for compatibility analysis.
POST /synastry Full synastry aspect table
POST /synastry/report Detailed synastry report
POST /synastry/composite Composite (midpoint) chart
POST /synastry/davison Davison relationship chart
POST /synastry/svg Synastry biwheel SVG
POST /synastry/compatibility-report Comprehensive compatibility analysis
Predictive Techniques
Forecasting tools for timing analysis.
POST /predictive/progressions Secondary progressions
POST /predictive/progressions/svg Progressed chart SVG
POST /predictive/solar-return Solar return chart for any year
POST /predictive/solar-return/svg Solar return chart SVG
POST /predictive/lunar-return Lunar return chart for any month
POST /predictive/planetary-return Return chart for any planet
POST /predictive/planetary-return/svg Planetary return SVG
POST /predictive/profections Annual profections
POST /predictive/profections/svg Profections wheel SVG
POST /predictive/profection-wheel-svg Visual profection wheel
POST /predictive/solar-arc Solar arc directions
POST /predictive/harmonic Harmonic charts
POST /predictive/tertiary-progressions Tertiary progressions
Traditional and Hellenistic Techniques
Advanced techniques from the classical astrological tradition. These are among the hardest endpoints to find in any public API.
POST /traditional/zodiacal-releasing Full zodiacal releasing periods
POST /traditional/firdaria Firdaria planetary periods
POST /traditional/primary-directions Primary directions
POST /traditional/planetary-hours Planetary hours for any date/location
POST /traditional/decennials Decennial periods
POST /traditional/distribution Distributor/bounds analysis
POST /traditional/circumambulations Circumambulation through bounds
POST /traditional/planetary-periods Planetary period calculations
POST /traditional/embolismic-lunation Embolismic lunation analysis
Hamburg School / Uranian Endpoints
Specialized endpoints for Uranian astrology practitioners.
POST /hamburg/transneptunians Transneptunian planet positions
POST /hamburg/planetary-pictures Planetary picture calculations
POST /hamburg/90-dial 90-degree dial analysis
Electional and Mundane Endpoints
Tools for timing elections and tracking ingresses.
POST /elections/find Find astrologically favorable dates
POST /elections/ingress Ingress chart for a planet entering a sign
POST /elections/planetary-ingresses All upcoming ingresses in a date range
Tools and Utilities
POST /tools/eclipses Eclipse search with natal chart impact
POST /tools/void-of-course Void-of-course Moon status
POST /tools/rectification Birth time rectification suggestions
POST /tools/relocation Relocated chart for astrocartography
POST /tools/ephemeris Ephemeris table for a date range
POST /tools/transit-calendar Transit calendar with natal aspects
POST /tools/chart-report Generated chart report
GET /tools/lunar-calendar Monthly lunar calendar with phases
GET /tools/lunar-today Today's lunar data
GET /tools/lunar-day-detail Detailed lunar day information
POST /tools/planetary-nodes Planetary node positions
POST /tools/heliacal-events Heliacal rising/setting dates
POST /tools/parans Paran conjunctions with fixed stars
POST /tools/horary Horary chart calculation
GET /tools/timezone Timezone lookup for coordinates
GET /ephemeris/positions Current planetary positions
Code Examples
Python: Generate a Natal Chart
import requests
API_KEY = "your-api-key"
BASE = "https://astro-engine.com/api/v1"
response = requests.post(
f"{BASE}/chart/natal",
json={
"date": "1990-06-15",
"time": "14:30",
"latitude": 34.0522,
"longitude": -118.2437,
"location_name": "Los Angeles, CA",
"house_system": "whole_sign"
},
headers={"Authorization": f"Bearer {API_KEY}"}
)
chart = response.json()
# Print planet positions
for planet in chart["planets"]:
print(f"{planet['name']:10} {planet['sign']:12} {planet['degree']:6.2f} "
f"House {planet['house']} {planet.get('dignity', '')}")
# Print aspects
for aspect in chart["aspects"]:
print(f"{aspect['planet_a']:10} {aspect['aspect']:12} {aspect['planet_b']:10} "
f"(orb: {aspect['orb']:.2f})")
JavaScript: Fetch Synastry Data
const API_KEY = 'your-api-key';
const BASE = 'https://astro-engine.com/api/v1';
async function getSynastry(personA, personB) {
const response = await fetch(`${BASE}/synastry`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${API_KEY}`
},
body: JSON.stringify({
person_a: {
date: personA.date,
time: personA.time,
latitude: personA.lat,
longitude: personA.lon,
location_name: personA.city
},
person_b: {
date: personB.date,
time: personB.time,
latitude: personB.lat,
longitude: personB.lon,
location_name: personB.city
}
})
});
const data = await response.json();
// Find the strongest aspects (smallest orbs)
const strongAspects = data.aspects
.sort((a, b) => Math.abs(a.orb) - Math.abs(b.orb))
.slice(0, 10);
console.log('Top 10 strongest synastry aspects:');
strongAspects.forEach(a => {
console.log(`${a.planet_a} ${a.aspect} ${a.planet_b} (orb: ${a.orb.toFixed(2)})`);
});
return data;
}
// Example usage
getSynastry(
{ date: '1990-06-15', time: '14:30', lat: 34.05, lon: -118.24, city: 'Los Angeles' },
{ date: '1992-03-22', time: '09:15', lat: 40.71, lon: -74.01, city: 'New York' }
);
Python: Get Current Transits to a Natal Chart
import requests
API_KEY = "your-api-key"
BASE = "https://astro-engine.com/api/v1"
# Search for upcoming transits to a natal chart
response = requests.post(
f"{BASE}/predictive/transit-search",
json={
"birth_data": {
"date": "1990-06-15",
"time": "14:30",
"latitude": 34.0522,
"longitude": -118.2437
},
"start_date": "2026-03-20",
"end_date": "2026-06-20",
"transiting_planets": ["saturn", "jupiter", "pluto"],
"aspects": ["conjunction", "square", "opposition", "trine"]
},
headers={"Authorization": f"Bearer {API_KEY}"}
)
transits = response.json()
for t in transits["transits"]:
print(f"{t['date']}: {t['transiting_planet']} {t['aspect']} natal {t['natal_planet']}")
JavaScript: Generate a Chart Image
async function getChartSVG(birthData) {
const response = await fetch(`${BASE}/chart/natal/svg`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${API_KEY}`
},
body: JSON.stringify(birthData)
});
const svgText = await response.text();
// Insert directly into the DOM
document.getElementById('chart-container').innerHTML = svgText;
}
Use Cases
Astrology Apps (iOS/Android)
The most common use case. A mobile app uses the API for all calculations and renders charts natively. The app handles user interface, birth data storage, and push notifications. The API handles the astronomy. This separation means you can build a beautiful, platform-native experience without embedding a C library in your app.
Dating and Social Apps
Compatibility features powered by synastry. When two users match, the app calls the synastry endpoint with both birth profiles and surfaces the compatibility data in the match interface. This adds genuine astrological depth beyond "you are both fire signs."
Content Personalization
Horoscope and astrology content platforms use the API to generate personalized content. Instead of generic Sun sign horoscopes, the API produces transit-based readings specific to a user's full chart. The /horoscope/daily/{sign} endpoint provides transit-generated daily content, while the transit search endpoints enable highly personalized forecasting.
Astrology Bots (Discord, Telegram, Slack)
Chatbots that respond to commands like /birthchart 1990-06-15 14:30 Los Angeles or /compatibility @user1 @user2. The bot sends the request to the API and formats the response for the chat platform. The API's JSON responses are easy to parse and template into chat messages.
Research and Data Analysis
Astrological researchers use the API to generate large datasets for pattern analysis. Calculate thousands of charts programmatically, search for astrological correlations, or build training datasets for machine learning models. The ephemeris endpoint provides raw positional data for custom analysis.
Wellness and Lifestyle Platforms
Health, wellness, and lifestyle apps integrate the lunar calendar and planetary hours endpoints to add astrological timing features. The /tools/lunar-calendar endpoint provides moon phases and signs for any month, which wellness platforms use for content scheduling, ritual timing, and cycle tracking.
Print and Media
Publishers use the API to generate horoscope content for websites, newsletters, and print publications. The daily, weekly, and monthly horoscope endpoints produce unique, transit-based content that can be formatted for any medium.
Pricing and Rate Limits
Astro Engine offers a tiered pricing model designed to scale with your usage.
| Tier | Rate Limit | Price | Best For |
|---|---|---|---|
| Free | 100 requests/day | $0 | Development, testing, hobby projects |
| Pro | 1,000 requests/day | Paid | Small apps, bots, content sites |
| Premium | 10,000 requests/day | Paid | Production apps, high-traffic platforms |
The free tier provides full access to all endpoints with no feature restrictions -- only the daily request count is limited. This means you can build and test your entire application against the real API before committing to a paid plan.
For applications that exceed 10,000 requests per day, enterprise pricing is available with custom rate limits and SLA guarantees.
Getting Started
1. Create an Account
Register at astro-engine.com to get access to the developer dashboard.
2. Generate an API Key
In the developer dashboard, create an API key. You will receive a key with a prefix (for identification) and a secret (for authentication). Store the secret securely -- it is shown only once.
3. Make Your First Request
curl -X POST https://astro-engine.com/api/v1/chart/natal \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"date": "1990-06-15",
"time": "14:30",
"latitude": 34.0522,
"longitude": -118.2437,
"house_system": "placidus"
}'
4. Explore the Documentation
The full API documentation is available at https://astro-engine.com/api/v1/docs with interactive Swagger/OpenAPI documentation. You can test endpoints directly in the browser.
Technical Details
Response Format
All endpoints return JSON with consistent structure. Planet positions include ecliptic longitude (absolute and sign-relative), sign, degree, minute, retrograde status, speed, and dignity information. Aspect data includes the aspect type, exact orb, and whether the aspect is applying or separating.
Timezone Handling
The API handles timezone conversion automatically when you provide geographic coordinates and a local time. You do not need to convert to UTC yourself. The engine uses the IANA timezone database with historical timezone data, correctly handling daylight saving time transitions, historical timezone changes, and locations with unusual timezone rules.
For edge cases, the /tools/timezone endpoint lets you verify which timezone the engine assigns to a given set of coordinates.
Error Handling
The API returns standard HTTP status codes with descriptive error messages:
400-- Invalid request (bad date format, impossible coordinates, etc.)401-- Missing or invalid API key403-- Feature requires a higher tier429-- Rate limit exceeded (includesRetry-Afterheader)500-- Server error (rare, but includes error ID for support)
Performance
Standard natal chart calculations return in under 200ms. Complex calculations (zodiacal releasing, transit searches over long date ranges) may take up to 500ms. The API is built on FastAPI with asynchronous request handling, so concurrent requests do not degrade performance.
Why Astro Engine Over Alternatives
The astrology API market in 2026 includes several providers. Here is what differentiates Astro Engine:
Endpoint coverage: 121+ endpoints vs. 40-60 for most competitors. The traditional and Hellenistic technique endpoints (zodiacal releasing, firdaria, primary directions, decennials) are available from virtually no other public API.
Hamburg School support: Transneptunian calculations, planetary pictures, and 90-degree dial analysis are niche but essential for Uranian astrology applications. No other public API offers these.
Chart rendering: Native SVG and PNG chart generation endpoints mean you do not need a separate charting library. The API returns publication-quality chart images.
Accuracy: Swiss Ephemeris with DE441 data. Sub-arcsecond precision for all standard calculations.
Free tier with full access: The free tier does not restrict which endpoints you can use -- only the request volume. You can prototype against any endpoint without upgrading.