AstroWay/api v2.295.7 · pl
wszystkie systemy w normie

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

Krok po kroku przewodnik tworzenia aplikacji astrologicznej od podstaw - wybór API, architektura, pierwsza mapa natalska, dodanie synastrii i transytów, wdrożenie.

🕓 Nagranie z 2026-04-14, zaktualizowane 2026-05-09. SDK TS / Python / PHP żyją teraz na publicznych rejestrach - @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Szczegóły w changelogu.

Chcesz zbudować aplikację astrologiczną. Od czego zacząć? W tym przewodniku - decyzje i kod: od wyboru API po wdrożenie działającego produktu.

Zanim napiszesz kod, zdecyduj: obliczenia po stronie klienta czy serwera?

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

  • Plusy: brak kosztu za żądanie, działa offline, pełna kontrola
  • Minusy: ~2 MB WASM dla każdego użytkownika, skomplikowane licencjonowanie (komercyjne użycie Swiss Ephemeris ma ograniczenia), sam utrzymujesz kod obliczeniowy

Serwerowe API (AstroWay, Prokerala itp.):

  • Plusy: brak zależności po stronie klienta, mały bundle aplikacji, szybko na mobilu, bez problemów licencyjnych
  • Minusy: koszt w kredytach za żądanie, opóźnienie przy “zimnych” żądaniach

Dla większości aplikacji wygrywa serwerowe API. Mobilni użytkownicy nie będą czekać na 2 MB WASM; z niuansami licencyjnymi nie warto się bawić; a nowoczesne API darmowo cache’ują identyczne żądania (AstroWay robi 5-minutowy cache z nagłówkiem X-Cache: HIT).

Co się liczy:

  • Dokładność: szukaj Swiss Ephemeris “pod maską” (±1 sekunda kątowa). Jeśli API wprost tego nie mówi - zapytaj.
  • Pokrycie: natal + synastria + tranzyty: minimum. Progresje i powroty - kolejny poziom. Rzadkie techniki (rektyfikacja, Human Design) - to wyróżnik.
  • Jakość SDK: typowane SDK TypeScript i Python oszczędzają godziny.
  • Model taryfowy: credit-based skaluje się lepiej niż per-request przy mieszanym obciążeniu.

Do tego tutoriala weźmiemy AstroWay API, bo ma wszystkie cztery (777 endpointów, Swiss Ephemeris, typowane SDK, credit-based).

Nigdy nie wywołuj API astrologicznego bezpośrednio z przeglądarki - twój klucz API wycieknie. Zawsze idź przez własny backend.

Okno terminala
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

Utwó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.compute({
...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:

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

Sprawdzenie przez curl:

Okno terminala
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-ową kartę natalną.

Nada się dowolny framework. Dla przykładu - React z prostym formularzem:

import { useState } from 'react';
type Chart = {
planets: { name: string; longitude: number; isRetrograde: boolean }[];
aspects: { planet1: string; planet2: string; type: { name: string }; orb: number }[];
};
// Planets come with ecliptic longitude, not a sign: the sign is that longitude
// divided by 30. Work it out on your side, it is cheaper than another call.
const SIGNS = ['Aries', 'Taurus', 'Gemini', 'Cancer', 'Leo', 'Virgo',
'Libra', 'Scorpio', 'Sagittarius', 'Capricorn', 'Aquarius', 'Pisces'];
const signOf = (longitude: number) => SIGNS[Math.floor(longitude / 30) % 12];
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 (e.g. 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}: {signOf(p.longitude)} {(p.longitude % 30).toFixed(2)}°{p.isRetrograde ? ' R' : ''}</li>
))}
</ul>
<h2>Aspects</h2>
<ul>
{chart.aspects.map((a, i) => (
<li key={i}>{a.planet1} {a.type.name} {a.planet2} (orb {a.orb.toFixed(2)}°)</li>
))}
</ul>
</div>
)}
</div>
);
}

Kompatybilność - 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.compute(parsed.data);
res.json({
score: result.compatibility.score,
label: result.compatibility.label,
aspects: result.crossAspects,
});
});

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

Dla zaangażowania treścią codzienne horoskopy to must have. AstroWay generuje je z rzeczywistych danych tranzytów:

// The daily horoscope is keyed by sign and date, not by the birth chart.
const DailyInput = z.object({
sign: z.enum(['aries', 'taurus', 'gemini', 'cancer', 'leo', 'virgo',
'libra', 'scorpio', 'sagittarius', 'capricorn', 'aquarius', 'pisces']),
date: z.string(),
});
app.post('/api/horoscope/daily', async (req, res) => {
const parsed = DailyInput.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: parsed.error });
const horoscope = await client.horoscope.daily({ ...parsed.data, language: 'uk' });
res.json({
text: horoscope.horoscope,
disclaimer: horoscope.disclaimer, // must be shown in the UI!
});
});

Ważne: treść generowana przez AI zawiera disclaimer, który masz obowiązek pokazać użytkownikom (zgodnie z Terms of Service). Nie usuwaj go.

Codzienne horoskopy są takie same dla wszystkich użytkowników z tego samego dnia urodzenia i o podobnych kartach natalnych. Cache’uj 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.horoscope.daily(req.body);
cache.set(key, horoscope);
res.json(horoscope);
});

AstroWay ma też wbudowane 5-minutowe cache’owanie po stronie serwera (X-Cache: HIT), ale dla długożyjącej treści potrzebujesz własnego cache.

Nada się dowolna platforma. Dla szybkiego startu - Vercel lub Railway:

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

W panelu platformy ustaw env ASTROWAY_API_KEY.

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

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

Dla 100 DAU z 1 kartą + 1 horoskopem + 0.3 synastrii na użytkownika dziennie:

100 × (20 + 20 + 0.3 × 50) × 30 = 165,000 credits/month

To plan Starter za $19/mies. (200K kredytów).

Zaawansowane funkcje, które warto dodać wraz ze wzrostem:

  • Overlay tranzytów: /v1/transits pokazuje bieżące pozycje planet na karcie natalnej
  • Progresje: /v1/progressions dla łuków rozwoju psychologicznego
  • Solar return: /v1/solar-return na “prognozę na rok od dnia urodzenia”
  • Human Design: Human Design API otwiera całkowicie nową domenę funkcjonalną
  • Astrokartografia: /v1/acg mapuje, gdzie użytkownikowi warto mieszkać

Każda funkcja jest ciężka do zrealizowania od zera, ale - to jedno wywołanie API z AstroWay.

MakSeong · AstroWay

Robię AstroWay API: pakuję Swiss Ephemeris w czysty REST i piszę o nudnych detalach, które naprawdę są 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.

Więcej z bloga wszystkie posty →

Ephemeris 2026-07-19

Jak trzymamy dokładność pod kontrolą: CI kontra swetest i NASA

Dokładność astrologicznego API łatwo zepsuć jednym refaktoringiem efemeryd. Opisujemy zabezpieczenia: jeden rdzeń Swiss Ephemeris dla aplikacji i API, setki zamrożonych snapshotów na horoskopach wzorcowych i triangulacja każdego PR względem swetest CGI, Kerykeion, Prokerala i katalogu zaćmień NASA.

Engineering 2026-07-15

Trzy oficjalne SDK: TypeScript, Python i PHP zamiast surowego curl

Surowe HTTP działa, ale typowany klient oszczędza godziny: podpowiadanie ścieżek, typy żądań i odpowiedzi, wbudowany retry dla 408/409/429/5xx i hierarchia błędów w stylu Stainless. Omawiamy trzy oficjalne SDK - @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist) - i to, jak powstają z jednego kontraktu OpenAPI.

Industry 2026-06-05

Free Astrology API: Which One Has the Best Free Tier in 2026?

A side-by-side of free tiers across the major astrology APIs - credits, request caps, card requirements - and how much you can actually build for free.