FAQ answers

Generale

Cos’è l’API di AstroWay?

Un’API HTTP professionale per calcoli astrologici. 714 endpoint basati su Swiss Ephemeris (WASM): carte natali, sinastria, progressioni, direzioni, transiti, Human Design, astrocartografia, rettificazione, interpretazioni AI. Tutti i calcoli vengono eseguiti lato server: nessuna dipendenza lato client.

Per chi è questa API?

Per sviluppatori che costruiscono applicazioni astrologiche (web/mobile), aziende AI che aggiungono funzionalità astrologiche, astrologi professionisti con script e ricercatori che necessitano di accesso programmato ai calcoli.

Qual è la precisione dei calcoli?

Swiss Ephemeris garantisce una precisione delle posizioni planetarie fino a ±1 secondo d’arco, dei cuspidi delle case fino a ±1 minuto d’arco. I risultati sono stati verificati rispetto a Astrodienst (Astro.com), Solar Fire, Zet 9 e Kepler. Deriva sub-arcosecondo rispetto all’ephemeris NASA JPL e al NASA 5-Millennium Eclipse Catalog.

Come si confronta AstroWay con Astro.com o Solar Fire?

Stesso motore Swiss Ephemeris — identico a quello di Solar Fire ($495 di licenza), Kepler ($995), Astro Gold ($29.99/mese) e Astrodienst (Astro.com). Validato rispetto all’ephemeris NASA JPL e allo strumento di riferimento ufficiale swetest di Astrodienst. Deriva sub-arcosecondo (≤0.1″) nelle posizioni planetarie, ≤1 minuto negli eclissi. Differenza: AstroWay è un’API REST da $5/mese invece di una licenza one-time o di un’interfaccia desktop.

Quali sistemi di case sono supportati?

15 sistemi: Placidus (predefinito), Koch, Whole Sign, Equal, Regiomontanus, Campanus, Topocentrico, Alcabitius, Morinus, Porphyrius, Vehlow, Krusinski-Pisa, Hindu Bhava, APC e Equal da MC. Passa il codice corrispondente nel parametro houseSystem.

Crediti e pagamento

Come funziona il sistema di crediti?

Ogni endpoint ha un costo fisso in crediti (da 10 a 500), a seconda della complessità del calcolo. Una semplice ricerca costa 10 crediti, una carta natale 20, una sinastria 50, la rettificazione 500. La tabella completa è disponibile nella pagina Tariffe.

C’è un piano gratuito?

Sì. Il piano Free offre 10.000 crediti/mese, 10 req/min. Non è richiesto l’inserimento della carta di credito. È sufficiente per valutare il prodotto e prototipare.

Cosa succede quando finiscono i crediti?

Nel piano Free, le richieste vengono bloccate fino al mese successivo (429 CREDITS_EXHAUSTED). Nei piani Indie/Starter/Pro/Business viene applicato l’overage: $5/$3/$2 ogni 10.000 crediti aggiuntivi.

Le stesse richieste vengono messe in cache?

Sì. Un input identico entro 5 minuti viene restituito dalla cache senza addebitare crediti. Confermato dall’intestazione X-Cache: HIT.

Posso acquistare crediti senza abbonamento?

Al momento no. L’abbonamento offre un budget prevedibile e un limite di richieste migliore. È in programma un piano pay-as-you-go.

Tecnico

Quali SDK sono disponibili?

• Server MCP ✅ rilasciato: npx -y @astroway/mcp — espone tutti gli endpoint 714+ come strumenti per Claude $1, Cursor, GPT e altri agenti AI compatibili con MCP
• SDK TypeScript ✅ rilasciato: npm install @astroway/sdk — tipi + autocompletamento con OpenAPI 3.1, retry + idempotenza, errori in stile Stainless
• SDK Python ✅ rilasciato: pip install astroway — sync Astroway + async AsyncAstroway, basato su httpx, tipizzato PEP 561
• SDK PHP ✅ rilasciato: composer require astroway/sdk — PHP 8.1+, Guzzle 7 + PSR-18, middleware per retry
• Go / Ruby / Rust 📋 in programma — iscriviti per ricevere notifiche via email nella pagina di ogni SDK (/sdk/<language>/)

Il contratto dell’API è standard REST + JSON, quindi qualsiasi client HTTP funziona senza SDK. Sono disponibili pubblicamente la collection Postman e la specifica OpenAPI 3.1.

C’è una modalità sandbox?

Sì. Le chiavi aw_test_* non addebitano crediti e restituiscono gli stessi risultati. Ideale per sviluppo e testing.

Qual è il limite di richieste (rate limit)?

Dipende dal piano: Free — 10, Indie — 30, Starter — 120, Pro — 400, Business — 1.000 req/min. In caso di superamento, viene restituito 429 con l’intestazione Retry-After.

Viene supportato lo zodiaco siderale?

Sì. Passa "zodiacType": "sidereal" e opzionalmente "ayanamsaId" (predefinito: Lahiri). Funziona con tutti gli endpoint.

Cosa sono gli endpoint Human Design?

12 endpoint per il calcolo del Human Design: tipo, strategia, autorità, profilo, definizione, croce d’incarnazione, canali, centri, Dream Rave, Hologenetic Profile, Penta (dinamica di gruppo), sensibilità temporale. La copertura più approfondita di HD tra le API commerciali.

Sicurezza e privacy

Vengono memorizzati i dati delle richieste?

L’API è stateless: i dati su data/ora/coordinate di nascita non vengono memorizzati dopo l’elaborazione della richiesta. Vengono registrati solo metadati: key_id, endpoint, timestamp, latenza, crediti. Nessun dato personale.

L’API è conforme al GDPR?

Sì. I dati non vengono memorizzati. Per gli utenti UE: nessuna elaborazione di PII, nessun profilo, nessun cookie. La chiave API è legata all’account, non all’utente finale.

Le interpretazioni AI sono sicure?

Gli endpoint AI (/interpret/*, /horoscope/*) includono guardrail di sicurezza integrati: divieto di consigli medici, legali o finanziari. Ogni risposta include un disclaimer. Audit trail completo per la compliance aziendale.

Supporto

Come ottenere assistenza?

Dipende dal piano: Free — community, Indie — email (48 ore), Starter — email (24 ore), Pro — email (4 ore), Business — email + Slack (1 ora), Enterprise — manager dedicato su Slack. I contatti sono disponibili nella pagina Contatti.

C’è un SLA?

Indie: 99% di uptime. Starter e Pro: 99,9% di uptime. Business: 99,95% di uptime. Enterprise: SLA personalizzato con garanzie finanziarie.