Hogyan építsünk asztrológiai alkalmazást: fejlesztőknek szóló teljes útmutató

🕓 Bejegyzés 2026-04-14-ból, frissítve 2026-05-09. A TS / Python / PHP SDK-k most a nyilvános regisztereken vannak — @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). További részletek a changelog-ban.

Szeretnél csillagászati alkalmazást készíteni? Ebben az útmutatóban megoldásokat és kódot találsz: az API kiválasztásától a működő termék telepítéséig.

Mielőtt belekezdenél a kódolásba, döntsd el: a kliensen vagy a szerveren történjenek a számítások?

Kliensoldal (például Swiss Ephemeris WASM a böngészőben):

• Előnyök: nincs lekérdezésenkénti költség, offline működés, teljes kontroll
• Hátrányok: ~2 MB WASM minden felhasználónál, bonyolult licencelés (a Swiss Ephemeris kereskedelmi használata korlátozott), magadnak kell karbantartanod a számítási kódot

Szerveroldali API (AstroWay, Prokerala stb.):

• Előnyök: nincs kliensoldali függőség, kis alkalmazásméret, gyors mobilon, nincs licencprobléma
• Hátrányok: lekérdezésenkénti kreditköltség, késleltetés „hideg” lekérdezéseknél

A legtöbb alkalmazás esetében a szerveroldali API a nyerő. A mobilhasználók nem várnak meg 2 MB WASM-t; nem kell foglalkoznod a licencnyűgökkel; és a modern API-k ingyenesen cache-elnek azonos lekérdezéseket (az AstroWay 5 perces cache-t használ a X-Cache: HIT fejléccel).

Mire figyelj:

• Pontosság — keress Swiss Ephemeris „a motor alatt” (±1 szögmásodperc). Ha az API nem említi kifejezetten, kérdezd meg.
• Tartalom — a natív + szinasztria + tranzitok minimum. A progressziók és visszatérések a következő szint. Ritka technikák (rektifikáció, Human Design) pedig differenciáló tényezők.
• SDK minősége — a típusos TypeScript és Python SDK-k órákat spórolnak meg.
• Tarifamodell — a credit-alapú skálázhatóbb, mint a per-request, vegyes terhelés mellett.

Ebben az útmutatóban az AstroWay API mellett döntünk, mert mind a négy kritériumnak megfelel (723 endpoint, Swiss Ephemeris, típusos SDK-k, credit-alapú).

Soha ne hívd meg közvetlenül a böngészőből az asztrológiai API-t — a(z) API-kulcsod kiszivároghat. Mindig a saját backendeden keresztül kommunikálj.

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

Hozd létre a src/server.ts fájlt:

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

Indítsd el:

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

Ellenőrzés curl-lel:

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}'

Egy teljes JSON natív kartát kapsz.

Bármelyik keretrendszer megfelel. Például React egy egyszerű űrlappal:

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="Időzóna eltolás (például 3)" required />
        <input name="lat" type="number" step="0.0001" placeholder="Szélesség" required />
        <input name="lng" type="number" step="0.0001" placeholder="Hosszúság" required />
        <button>Kartya készítése</button>
      </form>

      {chart && (
        <div>
          <h2>Bolygók</h2>
          <ul>
            {chart.planets.map(p => (
              <li key={p.name}>{p.name}: {p.sign} (ház {p.house})</li>
            ))}
          </ul>
          <h2>Aspektusok</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>
  );
}

Az összeférhetőség a következő nyilvánvaló funkció. Add hozzá a src/server.ts-hez:

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

Ennyi. Egy endpoint, 50 kredit lekérdezésenként, 0–100 közötti score és cross-aspektusok.

A tartalom-engagement szempontjából a napi horoszkópok must-have-ok. Az AstroWay valós tranzitadatokból generálja őket:

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, // kötelező megjeleníteni a UI-ban!
  });
});

Fontos: Az AI által generált tartalom tartalmaz egy disclaimert, amit kötelező megjelenítened a felhasználóknak (a Terms of Service szerint). Ne hagyd el!

A napi horoszkópok azonosak minden olyan felhasználó számára, akiknek ugyanazon a napon született a napja és hasonló a natív kartájuk. Cache-eld agresszívan:

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

Az AstroWay is rendelkezik beépített 5 perces szerveroldali cache-eléssel (X-Cache: HIT), de a hosszú életű tartalomhoz saját cache-re van szükség.

Bármelyik platform megfelel. Gyors kezdéshez: Vercel vagy Railway:

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

A platform vezérlőpultján állítsd be a ASTROWAY_API_KEY környezeti változót.

Ha idáig eljutottál, értékeld ki a havi kreditfogyasztásod a bevezetés előtt:

kredit/hó = NAU × (átlag_kartya_felhasználónként × 20
                     + átlag_szinasztria × 50
                     + átlag_horoszkóp × 20) × 30

100 NAU esetén, 1 kártya + 1 horoszkóp + 0,3 szinasztria felhasználónként naponta:

100 × (20 + 20 + 0,3 × 50) × 30 = 165 000 kredit/hó

Ez a Starter terv $19/hó (200K kredit).

Haladó funkciók, amiket érdemes hozzáadni a növekedéssel:

• Tranzit overlay — a /v1/transits mutatja a jelenlegi bolygópályákat a natív kártyán
• Progressziók — a /v1/progressions a pszichológiai fejlődés ívét mutatja
• Solar return — a /v1/solar-return „éves előrejelzés a születésnapodtól”
• Human Design — a Human Design API egy teljesen új funkcionális területet nyit meg
• Asztrogeográfia — a /v1/acg feltérképezi, hol érdemes élni a felhasználónak

Minden funkció nehezen kivitelezhető nulláról, de — egy API-hívás az AstroWay-tól.

• Kapj ingyenes API-kulcsot — 10 000 kredit/hó
• Teljes API referencia — az összes 723 endpoint
• Natív Kártya API — részletes dokumentáció a kártya endpointjáról