Jak zbudować aplikację astrologiczną: kompletny przewodnik dla deweloperów

🕓 Wpis z dnia 2026-04-14, zaktualizowany 2026-05-09. TS / Python / PHP SDK są teraz dostępne w publicznych rejestrach — @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Szczegóły w changelog.

Chcesz stworzyć aplikację astrologiczną. Z czego zacząć? W tym przewodniku — rozwiązania i kod: od wyboru API do wdrożenia działającego produktu.

Pytania architektoniczne

Zanim zaczniesz pisać kod, rozważ: obliczenia na kliencie czy na serwerze?

Klient (np. Swiss Ephemeris WASM w przeglądarce):

Plusy: brak kosztów za żądanie, działa offline, pełna kontrola
Minusy: ~2 MB WASM na każdego użytkownika, skomplikowana licencja (użycie komercyjne Swiss Ephemeris ma ograniczenia), samodzielnie prowadzisz kod obliczeniowy

Serwerowy API (AstroWay, Prokerala itp.):

Plusy: brak zależności po stronie klienta, mały pakiet aplikacji, szybko działa na urządzeniach mobilnych, bez problemów z licencją
Minusy: koszt w kredytach za żądanie, opóźnienia w przypadku “zimnych” żądań

Dla większości aplikacji lepszym rozwiązaniem jest serwerowy API. Użytkownicy mobilni nie będą czekali na 2 MB WASM; nie warto mieć do czynienia z nuansami licencyjnymi; a nowoczesne API bezpłatnie buforują identyczne żądania (AstroWay robi 5-minutowy bufor z nagłówkiem X-Cache: HIT).

Wybór API

Co jest ważne:

Dokładność — szukaj Swiss Ephemeris “pod kapotem” (±1 kątowa sekunda). Jeśli API nie mówi o tym wprost — zapytaj.
Zakres — natals + synastry + transity — minimum. Progresje i powroty — następny poziom. Rzadkie techniki (rektyfikacja, Human Design) — to różnicujący czynnik.
Jakość SDK — typowane TypeScript i Python SDK oszczędzają godziny.
Model taryfy — oparty na kredytach lepiej skaluje się niż oparty na żądaniach, na mieszanym obciążeniu.

Do tego tutorialu wybierzemy AstroWay API, bo ma wszystkie cztery (723 endpoint, Swiss Ephemeris, typowane SDK, oparty na kredytach).

Krok 1: Uruchomienie backendu

Nigdy nie wywołuj API astrologicznego bezpośrednio z przeglądarki — twój klucz API wycieknie. Zawsze przechodź przez swó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

Stwórz 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'));

Uruchom:

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

Sprawdź przez 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}'

Otrzymujesz pełną JSON-natalską kartę.

Krok 2: Frontend

Podaje się dowolny framework. Dla przykładu — React z prostą formą:

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="Strefa czasowa (np. 3)" required />
        <input name="lat" type="number" step="0.0001" placeholder="Szerokość geograficzna" required />
        <input name="lng" type="number" step="0.0001" placeholder="Długość geograficzna" required />
        <button>Wygeneruj kartę</button>
      </form>

      {chart && (
        <div>
          <h2>Planety</h2>
          <ul>
            {chart.planets.map(p => (
              <li key={p.name}>{p.name}: {p.sign} (dom {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: Sinastry

Zgodność — następna oczywista funkcja. Dodaj w 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,
  });
});

Gotowe. Jeden endpoint, 50 kredytów za wywołanie, zwraca score 0–100 i cross-aspekty.

Krok 4: Codzienne horoskopy

Dla angażowania użytkowników codzienne horoskopy — must have. AstroWay generuje je z rzeczywistych danych tranzytów:

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, // obowiązkowo zachowaj w UI!
  });
});

Ważne: AI-wygenerowany kontent zawiera disclaimer, który musisz wyświetlić użytkownikom (zgodnie z Terms of Service). Nie usuwaj go.

Krok 5: Pamięć podręczna

Codzienne horoskopy są takie same dla wszystkich użytkowników z tego samego dnia urodzenia i podobnych kart urodzeniowych. Pamiętaj agresywnie:

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

W AstroWay jest również wbudowane 5-minutowe serwerowe pamiętanie (X-Cache: HIT), ale dla długotrwałego kontentu potrzebna jest własna pamięć podręczna.

Krok 6: Wdrożenie

Podaje się dowolna platforma. Dla szybkiego startu — Vercel lub Railway:

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

W panelu platformy ustaw środowisko ASTROWAY_API_KEY.

Planowanie budżetu

Jeśli dotarłeś tutaj — oszacuj miesięczne zużycie kredytów przed uruchomieniem:

kredyty/miesiąc = DAU × (średnie_karty_na_użytkownika × 20
                     + średnie_sinastry × 50
                     + średnie_horoskopy × 20) × 30

Dla 100 DAU z 1 kartą + 1 horoskopem + 0,3 sinastrami na użytkownika na dzień:

100 × (20 + 20 + 0,3 × 50) × 30 = 165 000 kredytów / miesiąc

To plan Starter za $19/miesiąc (200K kredytów).

Co dalej

Rozwijane funkcje, które warto dodać ze wzrostem:

Nakładki tranzytów — /v1/transits pokazuje bieżące pozycje planet na karcie urodzeniowej
Progresje — /v1/progressions dla łuków rozwoju psychologicznego
Powrót Słońca — /v1/solar-return na “prognozę na rok od dnia urodzenia”
Human Design — Human Design API otwiera cały nowy obszar funkcjonalny
Astrokartografia — /v1/acg mapuje, gdzie użytkownikowi warto mieszkać

Każda funkcja jest trudna w realizacji od podstaw, ale — jeden wywołanie API z AstroWay.

Start

Pobierz bezpłatny klucz API — 10 000 kredytów / miesiąc
Pełna dokumentacja API — wszystkie 723 endpoint
Birth Chart API — szczegółowa dokumentacja endpointu karty urodzeniowej

AstroWay team

Zespół inżynierski AstroWay API. Pakujemy Swiss Ephemeris w czysty REST i piszemy o nudnych szczegółach, które są naprawdę ważne.

// zbuduj na tym

Ten sam Swiss Ephemeris, co w Solar Fire — w 4 liniach kodu.

Darmowy klucz bez karty. 5 000 wywołań miesięcznie do pierwszej płatności.

Pobierz klucz API → Dokumentacja