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

Oggi annunciamo AstroWay API - il backend computazionale per gli sviluppatori che creano applicazioni astrologiche, prodotti di oroscopo, funzioni di compatibilità per il dating e agenti AI che devono ragionare sulle carte natali.

In questo articolo - cosa c’è davvero dentro l’API, quali soluzioni non convenzionali abbiamo adottato, cosa abbiamo lasciato consapevolmente tra parentesi e come siamo arrivati qui. Senza fronzoli.

🕓 Registrazione del 2026-04-22, aggiornata il 2026-05-09. Alcuni numeri sono obsoleti. Stato attuale: 865 endpoint (e non 87 al momento del lancio), 888 test snapshot CI (e non 183), MCP-server @astroway/mcp + TypeScript SDK @astroway/sdk + Python SDK astroway + PHP SDK astroway/sdk ora vivono tutti sui public registries. Stato aggiornato - su /faq e changelog.

REST API basata su Swiss Ephemeris - ora anche con interpretazioni AI sopra i calcoli reali. Lo stesso motore che gli astrologi professionisti usano da oltre 30 anni in Solar Fire, Kepler, Astro Gold e Janus - precisione fino a una frazione di secondo d’arco, verificata con le effemeridi NASA JPL e il riferimento swetest ufficiale di Astrodienst (Astro.com).

Numeri:

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

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

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

1. Avevano una copertura superficiale (10–30 endpoint, per lo più solo natale)
2. Erano costosi su larga scala ($0.02–$0.10 per richiesta senza sconti all’ingrosso)
3. Usavano motori chiusi, la cui precisione è impossibile da verificare
4. Si concentravano sull’astrologia vedica, trattando quella occidentale come secondaria

Così abbiamo vendorizzato Swiss Ephemeris in autonomia 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 giornalieri a centinaia di migliaia di visitatori al mese.

In tre anni di produzione di questo codice siamo giunti a due conclusioni:

1. Lo stesso motore computazionale deve essere disponibile ad altri sviluppatori: non perché non possano scriverlo da soli, ma perché lo stack library + caching + CI per la precisione richiede sei mesi di lavoro, che nessuno dovrebbe ripetere.
2. La nostra copertura Human Design (12 endpoint: carta, tipo, autorità, profilo, porte, canali, contorni, attivazioni planetarie, incarnation cross, definition) è davvero unica. Nessun concorrente offre l’intero stack HD tramite API.

Questo è il lancio.

Abbiamo /nakshatras, /ashtakavarga e endpoint per le carte divisionali, ma non c’è Dasha, Panchang, Ashtakoota, KP. Motivo: nell’astrologia vedica ci sono divergenze irrisolte tra le scuole (guerre ayanamsha, dispute sui cuspidi KP, scelta della scuola dasha). Una parte vedica affrettata contro Prokerala e VedicAstroAPI riceverebbe semplicemente critiche.

La decisione è fissata: il pacchetto vedico è una fase separata 3, dopo che ci sarà una domanda stabile per l’occidentale e avremo tempo per validarlo contro Jagannatha Hora e Parashara’s Light. Meglio non lanciare affatto che lanciare male.

Una chiamata /chart costa circa 50 volte meno calcoli rispetto al /forecast-calendar di 365 giorni. Un prezzo fisso per richiesta o escluderebbe gli utenti leggeri, o sosterrebbe quelli pesanti. I crediti mappano il costo al lavoro reale - vedi la tabella per endpoint su pagina dei prezzi.

Le risposte nel piano gratuito contengono il campo _footer:

{
  "data": { ... },
  "_footer": "Powered by astroway.api - get your own key at https://api.astroway.info"
}

Non ci costa nulla, e dà agli utenti gratuiti un piccolo incentivo ad aggiornarsi. Nel piano Hobby+ viene rimosso nelle impostazioni della chiave. Il pattern è stato preso in prestito da Zapier e RevenueCat.

/rectification (selezione del tempo di nascita basata su eventi di vita tramite ricerca likelihood-grid) - computazionalmente costoso: una 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 alto in crediti, perché gli abusi graverebbero sull’infrastruttura condivisa per tutti gli altri.

Gli endpoint /interpret/* funzionano tramite il nostro AI-gateway privato con failover automatico tra più modelli. Non ti chiudiamo nei nostri prompt - ogni risposta con interpretazione include i calcoli originali, così puoi ri‑programmare con la tua LLM se la nostra voce non ti convince. Prompt completi e output li registriamo nella tabella di audit per la conformità B2B (conservazione 90 giorni).

• Pacchetto vedico: fase 3, dopo le prime conferme di domanda (vedi sopra)
• Webhook per soglie raggiunte: implementati, ma UI grezzo; in fase di perfezionamento
• Widget pubblici (<script src="api.astroway.info/widget/natal.js">) - fase 7
• Plugin per il sito Marketing principale: progetto separato, previsto nell’ambito dell’ecosistema astroway.info

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

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

Domande, richieste, edge case strani: hello@astroway.info.

Roadmap pubblica - PRODUCT-PLAN.md - cosa è stato fatto, cosa è prossimo, cosa è rimandato e perché.

Benvenuto.