Cum să construiți o aplicație de astrologie: ghid complet pentru dezvoltatori

🕓 Postare din 2026-04-14, actualizat 2026-05-09. SDK-urile TS / Python / PHP acum sunt disponibile pe registrele publice — @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Detalii în changelog.

Vrei să creezi o aplicație astrologică. De unde să începi? În acest ghid vei găsi soluții și cod: de la alegerea API-ului până la deploy-ul unui produs funcțional.

Înainte de a scrie cod, decide: calculele se fac pe client sau pe server?

Client (de exemplu, Swiss Ephemeris WASM în browser):

• Puncte forte: fără costuri per cerere, funcționează offline, control total
• Puncte slabe: ~2 MB WASM per utilizator, licențiere complexă (utilizarea comercială a Swiss Ephemeris are restricții), trebuie să întreții singur codul de calcul

API-ul serverului (AstroWay, Prokerala etc.):

• Puncte forte: fără dependențe pe client, aplicația are un bundle mic, rapid pe mobil, fără dureri de cap legate de licențe
• Puncte slabe: costuri în credite per cerere, latență la cererile „reci”

Pentru majoritatea aplicațiilor, API-ul serverului este câștigător. Utilizatorii de mobil nu vor aștepta 2 MB de WASM; nu trebuie să te ocupi de nuanțele de licențiere; iar API-urile moderne fac caching gratuit pentru cereri identice (AstroWay oferă un cache de 5 minute cu antetul X-Cache: HIT).

Ce contează:

• Precizia — caută Swiss Ephemeris „sub capotă” (±1 secundă de arc). Dacă API-ul nu specifică acest lucru, întreabă.
• Acoperirea — natal + sinastrie + tranzite — minimul. Progresii și revoluții — nivelul următor. Tehnici rare (rectificare, Human Design) — acesta este un factor de diferențiere.
• Calitatea SDK-ului — SDK-urile tipizate pentru TypeScript și Python economisesc ore de lucru.
• Modelul tarifar — bazat pe credite se scalează mai bine decât per-request, pe încărcătură mixtă.

Pentru acest tutorial, vom folosi API-ul AstroWay, deoarece are toate cele patru (723 endpoint-uri, Swiss Ephemeris, SDK-uri tipizate, model bazat pe credite).

Nu apela niciodată un API astrologic direct din browser — cheia ta API va fi expusă. Trebuie să treci întotdeauna prin backend-ul tău.

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

Creează 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'));

Rulează:

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

Verifică cu 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}'

Primești o hartă natală completă în format JSON.

Poți folosi orice framework. Ca exemplu, vom folosi React cu un formular simplu:

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 (de exemplu 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>Construiește hartă</button>
      </form>

      {chart && (
        <div>
          <h2>Planete</h2>
          <ul>
            {chart.planets.map(p => (
              <li key={p.name}>{p.name}: {p.sign} (casa {p.house})</li>
            ))}
          </ul>
          <h2>Aspecte</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>
  );
}

Compatibilitatea este următoarea funcționalitate evidentă. Adaugă în 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,
  });
});

Gata. Un singur endpoint, 50 de credite per apel, returnează un scor de la 0 la 100 și aspecte încrucișate.

Pentru engagement-ul conținutului, horoscopurile zilnice sunt un must-have. AstroWay le generează din date reale de tranzite:

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, // trebuie să îl afișezi în UI!
  });
});

Important: Conținutul generat de AI include un disclaimer pe care ești obligat să îl arăți utilizatorilor (conform Termenilor de Serviciu). Nu îl elimina.

Horoscopurile zilnice sunt identice pentru toți utilizatorii cu aceeași dată de naștere și hărți natale similare. Caching-ul agresiv este recomandat:

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);
});

AstroWay are și un caching încorporat de 5 minute (X-Cache: HIT), dar pentru conținut de lungă durată este necesar un caching propriu.

Poți folosi orice platformă. Pentru un start rapid, folosește Vercel sau Railway:

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

În panoul platformei, setează variabila de mediu ASTROWAY_API_KEY.

Dacă ai ajuns până aici, estimează consumul lunar de credite înainte de lansare:

credite/lună = ZAU × (medie_hărți_per_utilizator × 20
                     + medie_sinastrii × 50
                     + medie_horoscopuri × 20) × 30

Pentru 100 ZAU cu 1 hartă + 1 horoscop + 0,3 sinastrii pe utilizator pe zi:

100 × (20 + 20 + 0,3 × 50) × 30 = 165 000 credite / lună

Acesta este planul Starter la $19/lună (200K credite).

Funcționalități avansate pe care merită să le adaugi pe măsură ce crești:

• Suprapuneri de tranzite — /v1/transits arată pozițiile curente ale planetelor pe harta natală
• Progresii — /v1/progressions pentru arce de dezvoltare psihologică
• Solar return — /v1/solar-return pentru „prognoză pe un an de la ziua de naștere”
• Human Design — Human Design API deschide un întreg nou domeniu funcțional
• Astrocartografie — /v1/acg cartografiază unde ar trebui să locuiască utilizatorul

Fiecare funcționalitate este greu de implementat de la zero, dar — un singur apel API cu AstroWay.

• Obține cheia API gratuită — 10 000 de credite / lună
• Referința completă a API-ului — toate cele 723 endpoint-uri
• API-ul Hărții Natale — documentație detaliată a endpoint-ului de hartă