Frequently Asked Questions

We offer transparent, all-inclusive pricing that includes features other providers charge extra for:

• Free: $0/month - 1,000 requests (perfect for testing and small projects)
• Starter: $11/month - 5,000 requests (ideal for personal astrology websites)
• Professional: $37/month - 55,000 requests (great for growing apps and businesses)
• Business: $99/month - 220,000 requests (ALL 56+ endpoints included)
• Enterprise: $399+/month - Custom solutions with dedicated servers

Unlike other solutions that charge $800-1000/month for basic horoscopes, we give you complete access to 56+ calculation types, 23 house systems, and AI-powered interpretations in every plan. Compare this to Alternative A ($31-49/month for just 15 features) or Alternative B (€279/month for limited functionality). You get 10x more value per dollar with our API.

I was paying $850/month for three different APIs. AstroAPI gives me everything in one place for $37. Game changer for my astrology app business.

Yes! We have a Forever Free Tier that never expires:

• Forever Free Tier: 1,000 requests per month, permanently free (no credit card ever required)
• Full API Access: Test all 56+ calculations, AI interpretations, and premium features
• Extended Beta Access: Qualifying astrologers and developers get additional free credits

Here's what makes us different: While other services like ProKerala require payment upfront, we let you build and test your entire application before spending a penny. Join 500+ developers who started with our free tier and scaled up as their businesses grew. You can use the free tier forever - no time limits, no expiration, no risk.

Started with the free tier for my thesis project, now running a profitable astrology SaaS with 2000+ users. The migration was seamless. - Isabella Romano 🇮🇹, Full-Stack Developer at StarMatch Dating

We've got you covered with flexible, fair overage options (no surprise bills!):

• Extra request blocks: Only $10 per 1,000 additional requests (other providers charge 2-3x more)
• Volume discounts: 40-60% discounts for 1M+ requests per month
• Smart overage protection: Optional auto-billing prevents service interruption during traffic spikes
• Real-time monitoring: Live dashboard shows usage with predictive alerts

The free tier resets monthly - you never lose access to basic functionality. Unlike other services that cut you off entirely, we give you advance warnings at 75% and 90% usage so you're never surprised.

I went viral on TikTok and hit 10x my usual traffic overnight - 500K views! AstroAPI handled the surge perfectly while my friend's app on another platform crashed for 6 hours.

Industry-leading performance that keeps your users happy:

• Natal charts & simple requests: 300-400ms (5x faster than other solutions)
• 1-month transit calculations: Under 1 second (other APIs take 2-3 seconds)
• 6-month transit calculations: 4.5 seconds maximum (other services: 8-15 seconds)
• Concurrent handling: Up to 73 requests/second with no degradation
• Uptime: 99.92% guaranteed (Enterprise: 99.99%)

Why we're faster: We use Swiss Ephemeris precision with intelligent multi-level caching and parallel processing. While other providers recalculate everything from scratch, our smart caching system delivers instant responses for repeated requests.

Speed isn't just a nice-to-have, it's essential for user retention.

Switched from my homebrew Python solution to AstroAPI. Load times went from 3 seconds to 300ms, and my app's bounce rate dropped 40%. Users actually wait for results now.

Professional-grade accuracy trusted by certified astrologers worldwide:

• Swiss Ephemeris: The same astronomical engine used in $500+ professional software
• Configurable precision: 0-8 decimal places (default: 4 decimals = 1.3 arcseconds accuracy)
• 23 house systems: Including Whole Sign, Placidus, Koch, Campanus (other providers typically offer only 4 systems)
• 56+ calculation types: Complete natal analysis, transits, progressions, returns, profections
• Traditional Hellenistic methods: Essential dignities, receptions, Arabic parts (unique in the API market)

Quality guarantee: Our calculations match leading professional astrology programs to the exact degree and minute. We're the only API that offers Swiss Ephemeris precision with traditional astrological techniques - giving you both astronomical accuracy and authentic astrological interpretation.

I tested AstroAPI against my $500 Solar Fire software - identical results to the arc-second. Now I offer instant charts on my website with the same professional accuracy. My booking rate increased 65%.

The most comprehensive feature set in the astrology API market (56+ calculations vs other providers' 20-30):

• Complete Planetary Data: Sun through Pluto, Chiron, Lunar Nodes, Vertex, Lilith, Part of Fortune, 1000+ fixed stars
• 23 House Systems: Whole Sign, Placidus, Koch, Equal, Campanus, Regiomontanus + 17 more (other providers offer only 4)
• Advanced Aspects: Major/minor aspects, applying/separating, custom orbs, aspect patterns
• Traditional Astrology: Essential dignities, sect analysis, combustion, receptions, dispositor chains, 97+ Arabic parts
• Fixed Stars: 23 major stars including royal stars and Behenian stars (other providers: none)
• Forecasting: Transits, progressions, solar/lunar returns, annual profections, firdaria
• AI-Powered Interpretations: Personalized readings in 9+ languages (other providers: static database only)

Here's the reality check: Leading other providers offer 15-25 calculations at most. We offer 56+ calculations that would require you to integrate 3-4 different APIs.

Finally! An API that doesn't make me choose between Western and Hellenistic techniques. I can offer both traditional sect analysis AND modern psychological readings to my diverse client base.

Developer-friendly JSON responses with the best documentation in the industry:

Response Format: Clean, consistent JSON structure across all endpoints

113+ Pre-built Examples for instant integration:

• JavaScript/Node.js (React, Next.js, Vue)
• Python (Django, Flask, FastAPI)
• PHP (Laravel, WordPress plugins)
• Go, Ruby, Java, C#
• No-code tools: Bubble, Zapier, Make

What makes us different:

• Automatic geocoding: Just pass "New York, NY" - we handle coordinates
• IANA timezone support: Perfect daylight saving time handling
• Batch processing: Calculate multiple charts in one request
• 3 documentation formats: Swagger, ReDoc, and RapiDoc
• Error messages that actually help: Specific guidance, not generic codes

I had my astrology app MVP running in 2 hours using their React examples. With AstrologyAPI.com, it took me 3 days just to understand their documentation. - Jessica Kim 🇰🇷, Full-Stack Developer at Samsung

For non-developers: We provide WordPress plugins, Bubble templates, and Zapier integrations so anyone can use our API without coding knowledge.

Generous limits designed for real applications, not artificial restrictions:

Standard Limits (much higher than other providers):

• Per minute: 50 requests (adjustable on request - other providers limit to 10-20)
• Burst handling: Up to 100 requests for traffic spikes
• Concurrent processing: 5 requests/second optimal, 10 requests/second maximum
• No throttling: Consistent performance even at limit

Enterprise Features:

• Custom rate limits tailored to your needs
• Dedicated servers for 5M+ requests/month
• Priority processing queues - your requests jump ahead
• Multi-region failover for 99.99% uptime

Here's why this matters: While other providers impose restrictive limits that break during viral moments, our limits are set for real-world usage patterns. We've seen TikTok astrologers go viral overnight - our infrastructure scales with your success, not against it.

During the Mercury retrograde meme surge, my app got 50x normal traffic - 2M requests in one day! AstroAPI scaled automatically while my alternative solution friend's app was down for 8 hours.

Yes! We encourage intelligent caching to optimize your costs and performance:

Liberal Caching Policy:

• Cache responses indefinitely - no expiration requirements like other providers
• Store natal and transit data as long as you need
• Build your own database if desired for instant access
• No "phone home" requirements - your cached data works offline

Privacy-First Approach:

• We never store personal birth data - everything processed on-the-fly
• Zero data retention on our servers means maximum privacy
• GDPR/CCPA compliant by design
• You control your users' data, not us

Smart Caching Strategies:

• Cache global transit data (works for all users) to reduce 80% of API calls
• Store individual natal charts with proper encryption
• Use conditional requests for dynamic content

Why this matters: Other providers often restrict caching or charge extra for data storage rights. We believe once you pay for the calculation, the data is yours to keep and use however benefits your application.

Absolutely! This is a game-changer for app performance and costs:

Global Transit Mode (/api/v3/data/positions):

• No location required - one calculation serves all users worldwide
• Cache once daily at midnight UTC - serves thousands of users from one request
• Returns planetary positions, aspects, lunar phases, void-of-course periods
• Reduces API usage by 80-90% for most astrology apps

Personal Mode for individual analysis:

• Full natal chart with houses and angles
• Location-specific calculations
• Complete traditional dignities and receptions

Why this is unique: Most other providers force you to make individual calculations for every user, even for global data that's identical worldwide. Our global mode lets you cache transit data once and share it across your entire user base.

Cost optimization example: Instead of 10,000 daily horoscope requests (costing $100+/month), you make 1 global request per day and cache it (costing $0.01/month). That's a 99.99% cost reduction without sacrificing functionality.

The global caching feature alone saved us $800/month. We cache daily transits once and serve 50,000 users. Absolute genius engineering.

World-class support that actually helps you succeed (not just answer tickets):

Support Levels with real humans who understand astrology:

• Free Tier: Community forums + email within 48 hours
• Paid Plans: Priority technical support within 24 hours
• Business: Integration consulting within 12 hours + phone support
• Enterprise: Dedicated success manager within 1 hour + emergency line

Service Level Agreement backed by real infrastructure:

• Uptime: 99.92% guaranteed (Enterprise: 99.99%) with automatic refunds for downtime
• Response times: Measured and reported monthly
• Real-time status: Always-current system status at status.astroapi.dev
• Maintenance windows: 48-hour advance notice, scheduled during low-usage periods

What makes our support different:

• We know astrology - not just API troubleshooting, but domain expertise
• Integration help - we don't just tell you "read the docs," we help you implement
• Proactive monitoring - we often catch and fix issues before you notice them
• Success-focused - measured on your business outcomes, not ticket closure time

Other APIs just sent me to their docs. AstroAPI's support actually helped me architect my app properly. They even reviewed my code!

Enterprise-grade security that protects your users' most personal data:

Security Infrastructure:

• 256-bit SSL/TLS encryption for all data in transit
• Amazon AWS hosting with SOC 2 Type II compliance
• ISO 27001 certified development practices
• Regular security audits by third-party professionals
• DDoS protection and intelligent threat detection

Privacy-First Architecture:

• Zero data storage - birth data never touches our databases
• Stateless processing - calculations happen in memory and disappear
• No tracking pixels or analytics on your API calls
• GDPR/CCPA compliant by design, not retrofit
• Optional dedicated servers for healthcare/enterprise applications requiring air-gapped processing

Trust & Transparency:

• White-label licensing available (remove all AstroAPI branding)
• Source code escrow available for Enterprise customers
• Security incident history: Zero breaches in 3+ years of operation
• Compliance documentation available for legal reviews

Why this matters for astrology: Birth data is incredibly personal and sensitive. Unlike other providers who store data for "performance optimization," we've architected our system to be secure by design - there's simply nothing for hackers to steal because we don't keep it.

As a therapy platform, data security was non-negotiable. AstroAPI was the only provider that met our HIPAA-equivalent requirements.

23 house systems - 5x more than any alternative solution in the market:

• Popular Western Systems: Placidus (default), Whole Sign, Koch, Campanus, Equal Houses, Regiomontanus
• Traditional Systems: Alcabitus, Porphyrius, Morinus, Meridian Houses
• Specialized Systems: Topocentric, Sripati (Vedic), Azimuthal, Krusinski, plus 9 more advanced systems

Why this matters: Professional astrologers need flexibility. Other providers typically offer only 4 basic systems (Placidus, Koch, Equal, Whole Sign). We support every house system a professional might use - from ancient Porphyry to modern Topocentric.

Developer-Friendly Design:

• Identical JSON structure across all systems - no code changes needed
• Guaranteed backward compatibility - switch systems without breaking your app
• Only calculated degrees change - all other data remains consistent

I serve clients who use different house systems. With AstroAPI, I can switch between Whole Sign for beginners and Porphyry for traditional clients in the same app. Game changer for my business.

Competitive advantage: This single feature eliminates the need to integrate multiple APIs or ask clients to compromise on their preferred system.

YES! We're the ONLY API built specifically for traditional astrologers - this is where we absolutely dominate the market:

Essential Dignities (what made medieval astrology work):

• Domicile, exaltation, triplicity, term (bounds), decan/face
• Automatic dignity scoring and strength calculations
• Mixed reception analysis for complex aspect interpretation

Planetary Conditions (the details other providers miss):

• Sect analysis (day/night chart, sect light, benefics/malefics)
• Combustion, under beams, cazimi - precise solar proximity calculations
• Planetary phases (oriental/occidental to the Sun)

Advanced Traditional Techniques (simply not available elsewhere):

• Dispositor chains and final dispositors
• Mutual receptions by rulership, exaltation, triplicity
• Annual profections with time-lord calculations
• Firdaria (Arabic/Persian time periods)
• House joys and accidental dignities

97+ Arabic Parts/Lots (other providers offer 0-3):

• Part of Fortune, Spirit, Love, Marriage, Death, Surgery, Travel, etc.
• Calculated by day/night sect for historical accuracy
• Integrated with dignity analysis for strength assessment

Why this is revolutionary: While other providers focus on modern sun-sign astrology, we've digitized the complete toolkit of ancient astrologers. Professional traditional astrologers can finally build digital practices without sacrificing their techniques.

For 20 years I've waited for someone to properly digitize Hellenistic astrology. AstroAPI finally gets it right - even the sect calculations match my hand calculations perfectly.

Absolutely! We've specifically designed solutions for astrologers and entrepreneurs who want to build digital businesses without technical knowledge:

No-Code Integration Options:

• Bubble.io templates: Complete astrology app templates you can customize
• WordPress plugins: Ready-to-install calculators for your website
• Zapier workflows: Connect to 5,000+ apps without code
• Make/n8n integrations: Visual workflow builders
• AI builders: Works with Lovable, Bolt.new, v0, Cursor for AI-powered development

For Astrologers Building Businesses:

• Copy-paste HTML widgets for your existing website
• Patreon integration for automated premium content
• Etsy/Gumroad automation for instant report delivery
• WhatsApp/Telegram bots using simple tools like ChatBase

Hand-Holding Support:

• Video tutorials for every no-code platform
• 1-on-1 setup calls for Business+ customers
• Template customization help
• Success stories library showing what others built

I'm a professional astrologer with zero coding experience. Using AstroAPI's Bubble template, I built an automated birth chart service that generates $2,000/month in passive income. It took me one weekend to set up.

Bottom line: If you can use WordPress or build a Facebook page, you can build a profitable astrology business with our API.

Here's the brutal truth about our competition (with specific evidence):

vs Alternative A ($31-49/month):

• They offer: 15 basic calculations, sun-sign horoscopes only, no natal charts
• We offer: 56+ calculations, full natal analysis, traditional techniques
• Price comparison: Similar cost for 10x more features

vs Alternative B (€29-279/month):

• They offer: 4 house systems, European focus, limited API examples
• We offer: 23 house systems, global coverage, 113+ code examples
• Performance: We're 3-5x faster with better caching

vs ProKerala (India-focused):

• They offer: Basic Vedic calculations, regional focus, poor documentation
• We offer: Both Western AND Vedic, global audience, world-class docs

Our Unique Advantages NO alternative solution offers:

• ✅ Swiss Ephemeris + Traditional techniques (professional-grade accuracy with ancient methods)
• ✅ AI-powered interpretations (unique content, not database repetition)
• ✅ 97+ Arabic parts (other providers: 0-3)
• ✅ Global transit caching (90% cost savings)
• ✅ 3 documentation formats (integration in hours, not weeks)
• ✅ No-code templates (Bubble, WordPress, Zapier ready)

I was spending $500/month on three different APIs. AstroAPI gives me everything for $37. Plus their Hellenistic features let me charge premium prices. My ROI is 15:1.

The math is simple: Choose us and get more features, better performance, lower costs, and superior support. Or choose other providers and pay more for less while your users complain about slow response times.

Let's run the numbers on real astrology business models using our API:

Scenario 1: Professional Astrologer Going Digital

• Investment: $37/month Professional plan
• Service: Automated birth chart reports at $25 each
• Monthly capacity: 55,000 requests = 1,833 reports possible
• Conservative sales: 200 reports/month = $5,000 revenue
• ROI: 13,400% return on investment

Scenario 2: Astrology App Startup

• Investment: $99/month Business plan
• Monetization: $4.99/month subscriptions with daily horoscopes
• API efficiency: Global caching serves 10,000 users with minimal requests
• Revenue: 2,000 subscribers × $4.99 = $9,980/month
• ROI: 9,900% return on investment

Scenario 3: Content Platform Integration

• Investment: $37/month Professional plan
• Value: Unique daily horoscopes for SEO and engagement
• Alternative cost: Hiring writers at $200/article × 30 days = $6,000/month
• Savings: $5,963/month using AI-generated content
• ROI: 16,000% cost savings

Success Multipliers with AstroAPI:

• Premium positioning: Professional accuracy justifies higher prices
• Time savings: Automation lets you serve 10x more clients
• Global reach: Multi-language support = international markets
• Competitive moat: Features other providers don't have

Real Customer Success Stories:

• Emma Walsh 🇮🇪 (Dublin Astrologer): $500/month → $5,000/month in 6 months
• LunaMatch Dating 🇨🇦 (Toronto startup): Added compatibility, increased user retention by 40%
• ZenFlow Wellness 🇯🇵 (Tokyo platform): Astrology features drove 25% of new sign-ups

Risk mitigation: Start with our forever-free tier, scale as you grow. Zero downside, unlimited upside.

2025-2026 Roadmap built based on actual customer requests:

Advanced Forecasting (Q4 2025):

• Electional astrology: Perfect timing for events and launches
• Horary analysis: Answer specific questions with astrology
• Predictive algorithms: Major life event timing
• Transit impact scoring: Quantified significance of planetary movements

Business & Enterprise Features (Q1 2026):

• Multi-tenant dashboard: Manage multiple client projects
• White-label report builder: Create branded PDF/HTML reports
• Webhook notifications: Real-time alerts for significant transits
• GraphQL API: More efficient queries for complex applications

AI & Personalization (Q2 2026):

• GPT-5, Claude Sonnet, and custom LLM interpretations with personality profiling
• Natural language queries: "When is my next good time for love?"
• Conversation-based readings for chatbot integration
• Multi-dimensional compatibility beyond just sun signs

Global Expansion (Q3 2026):

• Vedic astrology completeness: Dashas, Yogas, remedies
• Chinese astrology integration: Four Pillars/Ba Zi calculations
• Cultural adaptation: Region-specific interpretation styles
• Local calendar systems: Lunar, solar, and traditional calendars

Everything maintains backward compatibility - your existing integrations keep working while new features enhance your offering.

Customer-driven development: We build what our paying customers actually need, not what sounds impressive in marketing materials.

YES! Complete astronomical precision without manual calculations:

Absolute Longitude (0-360° from 0° Aries):

• Every planetary position includes both sign+degree AND absolute longitude
• Example: Mercury at 20.8° Taurus = 50.8° absolute longitude
• No manual conversion needed - calculated directly from Swiss Ephemeris

Planetary Speed (degrees/day):

• Speed field included for all planets showing exact daily motion
• Positive values: Direct motion
• Negative values: Retrograde motion
• Precision: 6 decimal places for research-grade accuracy

Retrograde Detection:

• is_retrograde boolean for instant identification
• Speed-based verification for double accuracy
• Works for all planets including asteroids and special points

Sample Response Structure:

{
  "name": "Mercury",
  "sign": "Tau", "degree": 20.8231,
  "absolute_longitude": 50.8231,
  "speed": 1.019021,
  "is_retrograde": false
}

Why this matters: Other APIs make you calculate this manually or provide incomplete data. We deliver complete astronomical precision ready for professional applications.

Complete Lunar Node Coverage - Both True AND Mean calculations:

North Node Options:

• Mean_Node - Traditional mean node (default, most commonly used)
• True_Node - Oscillating true node for precision applications

South Node Coverage:

• Mean_South_Node - Automatically calculated, no +180° math needed
• True_South_Node - True south node with proper house placement
• Separate entries in response - not derived values

Professional Integration:

"active_points": [
  "Mean_Node", "Mean_South_Node",
  "True_Node", "True_South_Node"
]

House Placement Accuracy:

• South Nodes get proper house assignment (not just opposite of North Node)
• Independent calculations ensure precision for both nodes
• Works with all 23 house systems we support

Finally! An API that treats the lunar axis properly. No more manual South Node calculations that introduce errors into my client work.

Competitive Advantage: Most APIs force you to calculate South Node positions manually, introducing potential errors. We provide both nodes as native calculations.

Configurable precision from basic to research-grade accuracy:

Precision Levels (0-8 decimal places):

• 0 decimals: Basic astrology (1° precision)
• 2 decimals: Standard practice (0.01° ≈ 36 arcseconds) - DEFAULT
• 4 decimals: Professional grade (0.0001° ≈ 0.36 arcseconds)
• 8 decimals: Research-grade astronomical precision

What Gets Controlled:

• All degree values: Planetary positions, house cusps, aspects
• Orb calculations: Precise aspect detection
• Angle measurements: Ascendant, MC, IC, Descendant

API Parameter:

{
  "options": {
    "precision": 4  // 4 decimal places
  }
}

Performance Impact:

• Higher precision = slightly longer calculation time
• 4 decimals recommended for professional applications
• 2 decimals sufficient for most consumer applications

Real-world Applications:

• Legal astrology: 8-decimal precision for court cases
• Research: 6-8 decimals for statistical analysis
• Client readings: 2-4 decimals for interpretation work
• Mobile apps: 2 decimals for optimal performance

Swiss Ephemeris Foundation: Our precision comes from NASA JPL data, the same source used by professional astronomy software.

Complete time handling with professional timezone management:

• Time Input Precision:

• Timezone Handling:

• City Name Input:

• Location Database:

Sample Request:

{
  "year": 1985, "month": 5, "day": 11,
  "hour": 18, "minute": 15, "second": 30,
  "city": "São Paulo", "country_code": "BR"
}

Professional Recommendation: When possible, provide latitude/longitude directly for 100% location accuracy in critical applications.

Industry-leading 23 house systems - more than any alternative solution:

Popular Systems (ready now):

• P - Placidus (default, most common)
• W - Whole Sign (traditional, growing popularity)
• K - Koch (European preference)
• C - Campanus (medieval traditional)
• A - Equal Houses (simple, effective)
• R - Regiomontanus (classical)

Traditional & Specialized Systems:

• M - Morinus (French tradition)
• B - Alcabitus (medieval Arabic)
• O - Porphyrius (Hellenistic)
• S - Sripati (Vedic tradition)
• T - Topocentric (modern precision)
• H - Azimuthal (astronomical)
• ...and 11 more advanced systems

Seamless System Switching:

• Same JSON structure across all systems
• Only degrees change - field names identical
• Runtime switching - no code changes needed
• Perfect backward compatibility

Example Comparison:

// Placidus
{"house": 1, "sign": "Leo", "degree": 7.53}

// Whole Sign (same structure!)  
{"house": 1, "sign": "Leo", "degree": 0.0}

I serve clients globally who prefer different systems. Indians want Sripati, Europeans prefer Placidus, traditional astrologers need Whole Sign. One API supports them all.

Missing: Only Gauquelin Sectors (not supported by underlying astronomical libraries).

YES! Global transit mode for maximum efficiency and cost optimization:

Endpoint: POST /api/v3/data/positions with global mode

What You Get (location-independent):

• Planetary positions: All planets with sign + degree + absolute longitude
• Planetary speed: Degrees per day for all bodies
• Retrograde status: For motion analysis
• Lunar metrics: Phase, elongation, void-of-course periods
• Aspects: Between planets (no house-based aspects)

What's Excluded (requires location):

• House cusps and placements
• Ascendant, MC, IC, Descendant angles
• Local space directions

Caching Strategy:

{
  "year": 2024, "month": 1, "day": 15,
  "hour": 0, "minute": 0, "second": 0,
  "mode": "global",
  "active_points": ["all_planets", "lunar_metrics"]
}

Business Impact:

• Cache once at midnight UTC - serve thousands of users
• 99.9% cost reduction vs individual calculations
• Sub-100ms response from cached data
• Perfect for: Daily horoscopes, transit newsletters, app dashboards

We serve 50,000 daily horoscope users. Global caching reduced our API costs from $2,000/month to $37/month while improving response times by 10x.

Who's Already Using This:

• BuzzFeed Astrology 🇺🇸 - Daily horoscope content
• CosmicDaily App 🇨🇦 - Transit notifications for 100K+ users
• AstroBlog Network 🇬🇧 - 50+ astrology blogs
• @DailyHoroscope 🇦🇺 - 5M Instagram followers

23 major fixed stars with zero-risk integration (completely opt-in):

Supported Fixed Stars:

• Royal Stars (Watchers of Heaven):

• Behenian Stars (Medieval magical stars):

• Other Major Stars:

100% Safe Integration:

• Opt-in only: Never included unless explicitly requested
• Same data structure: Uses identical PlanetaryPosition format as planets
• No breaking changes: Existing code handles them automatically
• Backward compatible: All current integrations continue working

Usage Example:

{
  "active_points": [
    "Sun", "Moon", "Mercury",        // Regular planets
    "Aldebaran", "Regulus", "Spica"  // Fixed stars (opt-in)
  ]
}

Response Structure (identical to planets):

{
  "name": "Regulus",
  "sign": "Leo", "degree": 29.8234,
  "absolute_longitude": 149.8234,
  "house": 10,
  "is_retrograde": false,  // Always false for stars
  "speed": 0.0            // Negligible proper motion
}

Fixed stars add incredible depth to my readings. Clients are amazed when I mention their Sun conjunct Spica. No other API offers this depth without breaking my existing code.

Complete freedom to cache and store data with enterprise-grade privacy:

Your Data Rights:

• Store indefinitely: No restrictions on caching API responses
• Commercial use: Full rights to use data in paid applications
• Derivative works: Create reports, charts, interpretations freely
• Backup and archival: Store for business continuity

Our Privacy Guarantee:

• No personal data storage: Birth information processed on-the-fly only
• Zero PII logs: No birth dates, times, or locations retained
• GDPR/CCPA compliant: Designed for maximum privacy protection
• No data mining: Your user data never used for our analytics

Processing Model:

User Request → Swiss Ephemeris → Response → Data Deleted
                  (Calculation only)

Recommended Caching Strategy:

• Natal charts: Cache permanently (user-specific data)
• Global transits: Cache for 24 hours (shared across users)
• Interpretations: Cache for business efficiency
• Sensitive data: Use your own encryption for PII

Business Benefits:

• Faster user experience: Instant loads from your cache
• Cost optimization: Reduce API calls through smart caching
• Offline capability: Serve cached content when needed
• Business continuity: Own your essential data

Legal Framework:

• White-label licensing: No attribution requirements
• Commercial freedom: Use in any business model
• Professional applications: Suitable for client-facing services
• Enterprise compliance: Meets corporate security standards

Security Best Practice: While we don't store PII, ensure your own systems protect user privacy with proper encryption and access controls.

Comprehensive global geocoding with 98%+ success rate:

Primary Database - GeoNames:

• 98% resolution rate including small cities worldwide
• 11+ million locations in database
• Brazilian coverage: Excellent for South American users
• Rural areas: Small towns and villages included
• Historical accuracy: Coordinates for older locations

Fallback System - OpenStreetMap:

• Universal coverage: Every mapped location globally
• Real-time updates: Community-maintained accuracy
• Alternative spellings: Handles local language variations
• Coordinate precision: Exact latitude/longitude

Input Flexibility:

{
  "city": "São Paulo",           // Local language OK
  "country_code": "BR"           // Optional disambiguation
}

Professional Recommendation:

• First choice: Provide exact latitude/longitude when available
• Second choice: City + country code for disambiguation
• Last resort: City name only (still 98% successful)

International Examples That Work:

• Москва, RU (Moscow, Russia)
• नई दिल्ली, IN (New Delhi, India)
• São Paulo, BR (São Paulo, Brazil)
• 东京, JP (Tokyo, Japan)
• القاهرة, EG (Cairo, Egypt)

Error Handling:

• Coordinate validation: Ensures reasonable lat/lng values
• Timezone detection: Automatic from coordinates
• Fallback options: Multiple resolution attempts
• Clear error messages: When resolution fails

We serve astrology clients in 47 countries. AstroAPI's geocoding handles everything from Tokyo to tiny villages in Peru. Never had a location it couldn't find.

Integration Note: While geocoding is comprehensive, providing exact coordinates eliminates any ambiguity and ensures 100% location accuracy for critical applications.

Optimized for speed with transparent performance characteristics:

Benchmark Response Times:

• Natal charts: 300-400ms average
• Simple requests: 250-300ms
• 1-month transits: Under 1 second
• 6-month transits: Up to 4.5 seconds (≈0.75s per month)

Performance Optimization Techniques:

• Swiss Ephemeris caching: Pre-calculated astronomical data
• Intelligent request routing: Load-balanced infrastructure
• Geographic distribution: AWS multi-region deployment
• Connection pooling: Persistent database connections
• Response compression: Minimal data transfer

Factors Affecting Speed:

Faster Requests:

• Natal charts with standard points
• Current date calculations
• Single-day transit requests
• Cached planetary positions

Slower Requests (still professional-grade):

• Extended transit periods (6+ months)
• Complex aspect calculations
• Multiple house systems simultaneously
• Historical date calculations (ancient dates)

Performance Tips:

• Use global mode: For shared transit data
• Limit date ranges: Break long periods into chunks
• Cache wisely: Store frequently requested data
• Batch related requests: Multiple charts for same date

Stress Test Results:

• Concurrent capacity: 73 requests/second
• Reliability: 0% errors under load
• 95th percentile: ≤345ms response time
• 99th percentile: ≤380ms response time

Our astrology app serves real-time birth chart calculations. Users expect instant results, and AstroAPI delivers every time. 300ms feels instantaneous to our users.

Optional Speed Optimization: For long-range forecasting, we can enable "major planets only" mode, which reduces calculation complexity while maintaining astrological relevance.