Come costruire un'applicazione astrologica: guida completa per gli sviluppatori

🕓 Aggiornamento del 2026-04-14, aggiornato il 2026-05-09. TS / Python / PHP SDK ora sono disponibili su public registries — @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Dettagli in changelog.

Vuoi creare un’applicazione astrologica. Da dove iniziare? In questa guida — soluzioni e codice: dalla scelta dell’API alla distribuzione di un prodotto funzionante.

Prima di scrivere codice, pensa: calcoli sul client o sul server?

Client (ad esempio, Swiss Ephemeris WASM nel browser):

• Vantaggi: senza costi per richiesta, funziona offline, controllo totale
• Svantaggi: ~2 MB WASM per ogni utente, licenza complessa (utilizzo commerciale di Swiss Ephemeris ha limitazioni), tu stesso gestisci il codice di calcolo

API server (AstroWay, Prokerala ecc.):

• Vantaggi: senza dipendenze client, bundle applicativo ridotto, veloce su mobile, senza problemi di licenza
• Svantaggi: costo in crediti per richiesta, ritardo su richieste “fredde”

Per la maggior parte delle applicazioni, vince l’API server. Gli utenti mobili non aspetteranno 2 MB WASM; con le sfumature delle licenze non vale la pena avere a che fare; e le API moderne memorizzano nella cache le richieste identiche (AstroWay esegue una cache di 5 minuti con l’intestazione X-Cache: HIT).

Cosa conta:

• Precisione — cerca Swiss Ephemeris “sotto il cofano” (±1 seconda angolare). Se l’API non lo dice esplicitamente — chiedi.
• Copertura — natività + sinastria + transiti — minimo. Progressioni e ritorni — prossimo livello. Tecniche rare (rettificazione, Human Design) — questo è un differenziatore.
• Qualità dell’SDK — TypeScript e Python SDK tipizzati risparmiano ore.
• Modello di tariffazione — credit-based scala meglio di per-richiesta, su carico misto.

Per questo tutorial, useremo AstroWay API, perché ha tutti e quattro (723 endpoint, Swiss Ephemeris, SDK tipizzati, credit-based).

Non chiamare mai un’API astrologica direttamente dal browser — la tua chiave API verrà esposta. Vai sempre attraverso il tuo backend.

mkdir my-astrology-app
cd my-astrology-app
npm init -y
npm install express @astroway/sdk zod
npm install -D typescript @types/express @types/node tsx

Crea src/server.ts:

import express from 'express';
import { Astroway } from '@astroway/sdk';
import { z } from 'zod';

const app = express();
app.use(express.json());

const client = new Astroway({
  apiKey: process.env.ASTROWAY_API_KEY!,
});

const BirthInput = z.object({
  date: z.string(),
  time: z.string(),
  timezoneOffset: z.number(),
  latitude: z.number(),
  longitude: z.number(),
});

app.post('/api/chart', async (req, res) => {
  const parsed = BirthInput.safeParse(req.body);
  if (!parsed.success) return res.status(400).json({ error: parsed.error });

  try {
    const chart = await client.chart({
      ...parsed.data,
      houseSystem: 'P',
    });
    res.json(chart);
  } catch (err) {
    res.status(500).json({ error: String(err) });
  }
});

app.listen(3000, () => console.log('http://localhost:3000'));

Avvia:

ASTROWAY_API_KEY=aw_test_... npx tsx src/server.ts

Verifica tramite curl:

curl -X POST http://localhost:3000/api/chart \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-07-14","time":"14:30:00","timezoneOffset":3,"latitude":50.4501,"longitude":30.5234}'

Ottieni la carta nativa JSON completa.

Va bene qualsiasi framework. Per esempio — React con un modulo semplice:

import { useState } from 'react';

type Chart = {
  planets: { name: string; longitude: number; sign: string; house: number }[];
  aspects: { planet1: string; planet2: string; type: string; orb: number }[];
};

export function NatalForm() {
  const [chart, setChart] = useState<Chart | null>(null);

  async function handleSubmit(formData: FormData) {
    const body = Object.fromEntries(formData.entries());
    const res = await fetch('/api/chart', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        date: body.date,
        time: body.time + ':00',
        timezoneOffset: Number(body.tz),
        latitude: Number(body.lat),
        longitude: Number(body.lng),
      }),
    });
    setChart(await res.json());
  }

  return (
    <div>
      <form action={handleSubmit}>
        <input name="date" type="date" required />
        <input name="time" type="time" required />
        <input name="tz" type="number" placeholder="Timezone offset (ad esempio 3)" required />
        <input name="lat" type="number" step="0.0001" placeholder="Latitude" required />
        <input name="lng" type="number" step="0.0001" placeholder="Longitude" required />
        <button>Build chart</button>
      </form>

      {chart && (
        <div>
          <h2>Planets</h2>
          <ul>
            {chart.planets.map(p => (
              <li key={p.name}>{p.name}: {p.sign} (house {p.house})</li>
            ))}
          </ul>
          <h2>Aspects</h2>
          <ul>
            {chart.aspects.map((a, i) => (
              <li key={i}>{a.planet1} {a.type} {a.planet2} (orb {a.orb.toFixed(2)}°)</li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
}

La compatibilità è la prossima caratteristica ovvia. Aggiungi in src/server.ts:

const SynastryInput = z.object({
  chart1: BirthInput,
  chart2: BirthInput,
});

app.post('/api/synastry', async (req, res) => {
  const parsed = SynastryInput.safeParse(req.body);
  if (!parsed.success) return res.status(400).json({ error: parsed.error });

  const result = await client.synastry(parsed.data);
  res.json({
    score: result.compatibility.score,
    label: result.compatibility.label,
    aspects: result.crossAspects,
  });
});

Tutto. Un endpoint, 50 crediti per chiamata, restituisce punteggio 0-100 e cross-aspetti.

Per l’engagement dei contenuti, gli oroscopi giornalieri sono un must. AstroWay li genera con dati reali di transiti:

app.post('/api/horoscope/daily', async (req, res) => {
  const parsed = BirthInput.safeParse(req.body);
  if (!parsed.success) return res.status(400).json({ error: parsed.error });

  const horoscope = await client.horoscopeDaily(parsed.data);
  res.json({
    text: horoscope.text,
    disclaimer: horoscope.disclaimer, // obbligatorio salvare nell'UI!
  });
});

Importante: il contenuto generato da AI contiene un disclaimer che devi mostrare agli utenti (ai sensi dei Termini di servizio). Non rimuoverlo.

Gli oroscopi giornalieri sono gli stessi per tutti gli utenti con lo stesso giorno di nascita e carte natali simili. Memorizza nella cache in modo aggressivo:

import { LRUCache } from 'lru-cache';

const cache = new LRUCache<string, any>({ max: 1000, ttl: 86400 * 1000 });

app.post('/api/horoscope/daily', async (req, res) => {
  const key = JSON.stringify(req.body);
  const cached = cache.get(key);
  if (cached) return res.json(cached);

  const horoscope = await client.horoscopeDaily(req.body);
  cache.set(key, horoscope);
  res.json(horoscope);
});

In AstroWay c’è anche una memorizzazione nella cache server integrata di 5 minuti (X-Cache: HIT), ma per contenuti a lunga durata è necessaria una cache personalizzata.

Va bene qualsiasi piattaforma. Per un rapido avvio — Vercel o Railway:

# vercel.json
{ "functions": { "src/server.ts": { "runtime": "@vercel/node" } } }

Nel pannello della piattaforma, imposta l’env ASTROWAY_API_KEY.

Se sei arrivato fin qui — stima il consumo mensile di crediti prima del lancio:

credits/month = DAU × (avg_charts_per_user × 20
                     + avg_synastries × 50
                     + avg_horoscopes × 20) × 30

Per 100 DAU con 1 carta + 1 oroscopo + 0,3 sinastrie per utente al giorno:

100 × (20 + 20 + 0.3 × 50) × 30 = 165 000 crediti / mese

Questo è il piano Starter a $19/mese (200K crediti).

Caratteristiche avanzate che vale la pena aggiungere con la crescita:

• Sovrapposizione dei transiti — /v1/transits mostra le posizioni attuali dei pianeti sulla carta nativa
• Progressioni — /v1/progressions per archi di sviluppo psicologico
• Ritorno solare — /v1/solar-return per la “previsione per l’anno dal giorno di nascita”
• Human Design — Human Design API apre un intero nuovo dominio funzionale
• Astrocartografia — /v1/acg mappa dove l’utente dovrebbe vivere

Ogni caratteristica è difficile da implementare da zero, ma — una sola chiamata API con AstroWay.

• Ottieni una chiave API gratuita — 10 000 crediti / mese
• Riferimento API completo — tutti gli 723 endpoint
• Birth Chart API — documentazione dettagliata dell’endpoint della carta