Lancio AstroWay API: stack completo di calcoli astrologici con precisione Swiss Ephemeris

Oggi annunciamo AstroWay API — un backend computazionale per gli sviluppatori che creano applicazioni astrologiche, prodotti oroscopici, funzioni di compatibilità per app di incontri e agenti AI che devono ragionare su carte natali.

In questo articolo — cosa c’è realmente dentro l’API, quali soluzioni insolite abbiamo adottato, cosa abbiamo lasciato fuori e come siamo arrivati qui. Senza giri di parole.

🕓 Nota del 2026-04-22, aggiornata il 2026-05-09. Alcuni dati sono obsoleti. Stato attuale: 723 endpoint (e non 87 al momento del lancio), 818 snapshot test CI (e non 183), server MCP @astroway/mcp + SDK TypeScript @astroway/sdk + SDK Python astroway + SDK PHP astroway/sdk ora vivono tutti sui registri pubblici. Stato aggiornato — su /faq e changelog.

API REST basata su Swiss Ephemeris (LGPL), compilata in WASM e distribuita come servizio Node.js — ora anche con interpretazioni AI (catena di failover GPT-4 / Claude / Llama 3.3 / Gemini / DeepSeek / Mistral) sopra calcoli reali. Lo stesso motore utilizzato da astrologi professionisti da oltre 30 anni in Solar Fire, Kepler, Astro Gold e Janus — precisione fino a una frazione di secondo angolare, verificata con l’efemeride NASA JPL e il riferimento swetest ufficiale di Astrodienst (Astro.com).

Dati:

• 723 endpoint — astrologia natale occidentale, sinastria, transiti, progressioni, direzioni, ritorni, armoniche, stelle fisse, punti arabi, astrocartografia più un set completo di Human Design
• 183 snapshot test in CI contro l’output reale di swetest CGI e il catalogo di eclissi NASA — eseguiti su ogni PR
• p50 < 100 ms, p95 < 500 ms per endpoint di calcolo tipici
• Server MCP @astroway/mcp + tre SDK sui registri pubblici: @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist) — la stessa API in tre lingue
• Server MCP: @astroway/mcp — fornisce l’API come strumenti per Claude, GPT, Cursor e altri agenti LLM
• Tariffe basate su crediti: piano gratuito (10 000 crediti / mese, senza carta), piani a pagamento — da $5 / mese

Documentazione completa: api.astroway.info/docs/api/. Stato attivo: api.astroway.info/status.

Tre anni fa abbiamo iniziato a costruire applicazioni astrologiche per consumatori. Lo strato computazionale si è rivelato la parte più difficile — molto più complessa dell’interfaccia utente o del contenuto. I servizi esistenti o:

1. Avevano una copertura superficiale (10–30 endpoint, principalmente solo natale)
2. Erano costosi su larga scala ($0.02–$0.10 per richiesta senza sconti in bulk)
3. Utilizzavano motori chiusi, la cui precisione non poteva essere verificata
4. Si concentravano sull’astrologia vedica, mentre quella occidentale era secondaria

Quindi abbiamo personalizzato Swiss Ephemeris e scritto il nostro strato computazionale — inizialmente per il prodotto consumer app.astroway.info, poi per il sito di marketing astroway.info, che fornisce oroscopi quotidiani a centinaia di migliaia di visitatori al mese.

In tre anni di lavoro con questo codice in produzione, siamo giunti a due conclusioni:

1. Lo stesso motore computazionale dovrebbe essere disponibile per altri sviluppatori — non perché non possano scriverlo da soli, ma perché lo stack libreria + WASM + caching + CI sulla precisione — è un lavoro di mezzo anno che nessuno dovrebbe ripetere.
2. La nostra copertura di Human Design (12 endpoint — carta, tipo, autorità, profilo, porte, canali, contorni, attivazioni planetarie, croce di incarnazione, definizione) — è veramente unica. Nessun concorrente offre un set completo di HD tramite API.

Ecco il lancio.

Abbiamo /nakshatras, /ashtakavarga e endpoint per le carte divisionali, ma non ci sono Dasha, Panchang, Ashtakoota, KP. La ragione: nell’astrologia vedica ci sono dispute irrisolte tra le scuole (guerre di ayanamsha, controversie sui cuspidi KP, scelta della scuola di dasha). Una parte vedica fatta in fretta contro Prokerala e VedicAstroAPI sarebbe stata semplicemente criticata.

La soluzione è stata fissata: il pacchetto vedico — fase 3, dopo le prime conferme della domanda (vedi sopra)

Una singola chiamata a /chart costa circa 50 volte meno calcoli di un /forecast-calendar di 365 giorni. Un prezzo piatto per richiesta o avrebbe tagliato fuori gli utenti leggeri o avrebbe sovvenzionato quelli pesanti. I crediti mappano il costo sul lavoro reale — vedi la tabella degli endpoint sulla pagina dei prezzi.

Le risposte sul piano gratuito contengono un campo _footer:

{
  "data": { ... },
  "_footer": "Powered by astroway.api — ottieni la tua chiave su api.astroway.info"
}

Non ci costa nulla, ma dà agli utenti gratuiti un piccolo incentivo per aggiornarsi. Sul piano Hobby+ può essere rimosso nelle impostazioni della chiave. Il pattern è stato preso in prestito da Zapier e RevenueCat.

/rectification (selezione dell’orario di nascita in base agli eventi della vita attraverso la ricerca della griglia di likelihood) — è computazionalmente costoso: una singola chiamata dura 10–60 secondi e esegue decine di migliaia di calcoli intermedi di Swiss Ephemeris. L’abbiamo limitato al piano Pro ($59 / mese) e abbiamo impostato un prezzo di credito elevato, perché l’abuso avrebbe messo a rischio l’infrastruttura condivisa per tutti gli altri.

Gli endpoint /interpret/* vengono instradati attraverso il nostro gateway AI privato, che utilizza i migliori modelli del mercato (Google Gemini → Groq → OpenRouter → Cerebras → SambaNova → Mistral) con failover automatico. Non ti blocciamo con i nostri prompt — ogni risposta con interpretazione contiene i calcoli originali, quindi puoi chiedere di nuovo con la tua LLM, se la nostra voce non ti piace. I prompt e gli output completi li registriamo nella tabella di audit per la conformità B2B (conservazione di 90 giorni).

• Pacchetto vedico — fase 3, dopo le prime conferme della domanda (vedi sopra)
• Webhook per la soglia — implementati, ma l’interfaccia utente è grezza; lo stiamo perfezionando
• Widget pubblici (<script src="api.astroway.info/widget/natal.js">) — fase 7
• Plugin per il sito di marketing principale — progetto separato, pianificato nell’ambito dell’ecosistema astroway.info

1. Leggi la documentazione se vuoi capire “perché”: api.astroway.info/overview
2. Avvio rapido in 5 minuti con codice: Astrology API Quick Start
3. Prezzi, inclusa la tabella dei crediti per endpoint: api.astroway.info/pricing
4. Registra un account — gratuito, senza carta: api.astroway.info/dashboard/sign-up

Se costruisci qualcosa sull’API — o trovi un bug, o desideri un endpoint che non abbiamo ancora — scrivici. Preferiamo sentire cento sviluppatori che chiedono qualcosa piuttosto che lanciare funzionalità che nessuno usa.

Domande, richieste, casi limite strani: hello@astroway.info.

Roadmap pubblico — PRODUCT-PLAN.md — cosa è stato fatto, cosa segue, cosa è stato rinviato e perché.

Benvenuto.