Jak postavit aстрологічní aplikaci: kompletní průvodce pro vývojáře

🕓 Zápis z 2026-04-14, aktualizováno 2026-05-09. TS / Python / PHP SDK nyní žijí na veřejných registrech — @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Podrobnosti v changelogu.

Chceš vytvořit astrologickou aplikaci. Odkud začít? V tomto průvodci najdeš řešení a kód: od výběru API až po nasazení hotového produktu.

Architektura: klient vs. server

Než začneš psát kód, rozhodni: výpočty na klientovi nebo na serveru?

Klient (např. Swiss Ephemeris WASM v prohlížeči):

Výhody: žádné náklady za dotaz, funguje offline, plná kontrola
Nevýhody: ~2 MB WASM na každého uživatele, složité licencování (komerční použití Swiss Ephemeris má omezení), sám se staráš o výpočetní kód

Serverové API (AstroWay, Prokerala atd.):

Výhody: žádné klientské závislosti, malý bundle aplikace, rychlé na mobilech, žádné licenční problémy
Nevýhody: náklady ve formě kreditů za dotaz, zpoždění u „studených“ dotazů

Pro většinu aplikací vítězí serverové API. Mobilní uživatelé nebudou čekat na 2 MB WASM; s licenčními nuancemi si nemusíš lámat hlavu; a moderní API zdarma cachují identické dotazy (AstroWay používá 5minutovou cache s hlavičkou X-Cache: HIT).

Výběr API

Co je důležité:

Přesnost — hledej Swiss Ephemeris „pod kapotou“ (±1 úhlová vteřina). Pokud to API přímo neuvádí, zeptej se.
Pokrytí — natal + synastrie + transity jsou minimum. Progresie a návraty jsou další úroveň. Vzácné techniky (rektifikace, Human Design) jsou diferenciátorem.
Kvalita SDK — typované TypeScript a Python SDK ušetří hodiny.
Model ceníku — credit-based škáluje lépe než per-request u smíšeného zatížení.

Pro tento tutoriál použijeme AstroWay API, protože splňuje všechna čtyři kritéria (723 endpoint, Swiss Ephemeris, typovaná SDK, credit-based).

Krok 1: Nastavení backendu

Nikdy nevolej astrologické API přímo z prohlížeče — tvůj API klíč by mohl uniknout. Vždy používej svůj 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

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

Spusť:

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

Otestuj pomocí 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}'

Získáš úplnou JSON natalní mapu.

Krok 2: Frontend

Vhodný je jakýkoliv framework. Pro příklad použijeme React s jednoduchým formulářem:

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="Časový posun (např. 3)" required />
        <input name="lat" type="number" step="0.0001" placeholder="Zeměpisná šířka" required />
        <input name="lng" type="number" step="0.0001" placeholder="Zeměpisná délka" required />
        <button>Vygenerovat mapu</button>
      </form>

      {chart && (
        <div>
          <h2>Planety</h2>
          <ul>
            {chart.planets.map(p => (
              <li key={p.name}>{p.name}: {p.sign} (dům {p.house})</li>
            ))}
          </ul>
          <h2>Aspekty</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>
  );
}

Krok 3: Synastrie

Kompatibilita je další logickou funkcí. Přidej do 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,
  });
});

Hotovo. Jeden endpoint, 50 kreditů za volání, vrací skóre 0–100 a cross-aspekty.

Krok 4: Denní horoskopy

Pro zapojení uživatelů jsou denní horoskopy nutností. AstroWay je generuje z reálných transitních dat:

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, // nezapomeň zobrazit uživatelům!
  });
});

Důležité: AI generovaný obsah obsahuje disclaimer, který musíš uživatelům zobrazit (dle Terms of Service). Neodstraňuj ho.

Krok 5: Cachování

Denní horoskopy jsou pro všechny uživatele narozené ve stejný den a s podobnými natalními mapami stejné. Cachuj agresivně:

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 má také vestavěnou 5minutovou serverovou cache (X-Cache: HIT), ale pro dlouhotrvající obsah potřebuješ vlastní cache.

Krok 6: Nasazení

Vhodná je jakákoliv platforma. Pro rychlý start použij Vercel nebo Railway:

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

V panelu platformy nastav env proměnnou ASTROWAY_API_KEY.

Plánování rozpočtu

Pokud jsi se dostal až sem, odhadni měsíční spotřebu kreditů před spuštěním:

kredity/měsíc = DAU × (průměrné_počty_map_na_uživatele × 20
                     + průměrné_počty_synastrií × 50
                     + průměrné_počty_horoskopů × 20) × 30

Pro 100 DAU s 1 mapou + 1 horoskopem + 0,3 synastrií na uživatele denně:

100 × (20 + 20 + 0,3 × 50) × 30 = 165 000 kreditů / měsíc

To odpovídá plánu Starter za $19/měs (200K kreditů).

Co dál

Pokročilé funkce, které stojí za to přidat s růstem:

Overlay transitů — /v1/transits ukazuje aktuální pozice planet na natalní mapě
Progresie — /v1/progressions pro oblouky psychologického vývoje
Solar return — /v1/solar-return pro „předpověď na rok od narozenin“
Human Design — Human Design API otevírá úplně novou funkční doménu
Astrokartografie — /v1/acg mapuje, kde by uživatel měl žít

Každá funkce je těžká na implementaci od nuly, ale s AstroWay stačí jeden API volání.

Začněte

Získej bezplatný API klíč — 10 000 kreditů / měsíc
Úplná API reference — všechny 723 endpointy
Birth Chart API — detailní dokumentace endpointu pro mapy

AstroWay team

Inženýrský tým AstroWay API. Zabalujeme Swiss Ephemeris do čistého RESTu a píšeme o nudných detailech, které jsou ve skutečnosti důležité.

// postav na tom

Stejný Swiss Ephemeris jako v Solar Fire — ve 4 řádcích kódu.

Zdarma klíč bez karty. 5 000 volání za měsíc do první platby.

Získat API klíč → Dokumentace