🕓 Καταχώρηση από 2026-04-14, ενημερώθηκε 2026-05-09. TS / Python / PHP SDK τώρα ζουν σε δημόσια registries -
@astroway/sdk(npm),astroway(PyPI),astroway/sdk(Packagist). Λεπτομέρειες στο changelog.
Θέλεις να φτιάξεις μια αστρολογική εφαρμογή. Από πού να ξεκινήσεις; Σε αυτόν τον οδηγό - λύση και κώδικας: από την επιλογή του API μέχρι την ανάπτυξη του λειτουργικού προϊόντος.
Ερωτήματα αρχιτεκτονικής
Ενότητα με τίτλο «Ερωτήματα αρχιτεκτονικής»Πριν γράψεις κώδικα, αποφάσισε: υπολογισμοί στον πελάτη ή στον διακομιστή;
Πελάτης (π.χ., Swiss Ephemeris WASM στο πρόγραμμα περιήγησης):
- Πλεονεκτήματα: χωρίς κόστος ανά αίτηση, λειτουργεί offline, πλήρης έλεγχος
- Μειονεκτήματα: ~2 MB WASM σε κάθε χρήστη, περίπλοκη αδειοδότηση (η εμπορική χρήση του Swiss Ephemeris έχει περιορισμούς), εσύ μόνο συντηρείς τον υπολογιστικό κώδικα
Διακομιστής API (AstroWay, Prokerala κλπ):
- Πλεονεκτήματα: χωρίς εξαρτήσεις πελάτη, μικρό bundle της εφαρμογής, γρήγορο σε κινητό, χωρίς άλγος αδειοδότησης
- Μειονεκτήματα: κόστος σε credits ανά αίτηση, καθυστέρηση σε “κρύες” αιτήσεις
Για τις περισσότερες εφαρμογές κερδίζει το API διακομιστή. Οι χρήστες κινητών δεν θα περιμένουν 2 MB WASM· δεν αξίζει να ασχοληθείς με τις αδειοδοτικές λεπτομέρειες· και τα σύγχρονα API κάνουν δωρεάν caching των πανομοιότυπων αιτήσεων (το AstroWay κάνει 5‑λεπτό cache με την κεφαλίδα X-Cache: HIT).
Επιλογή API
Ενότητα με τίτλο «Επιλογή API»Τι μετράει:
- Ακρίβεια: ψάξε για Swiss Ephemeris “κάτω από το καπό” (±1 γωνιακό δευτερόλεπτο). Αν το API δεν το δηλώνει ρητά - ρώτησε.
- Κάλυψη: natal + synastry + transits: ελάχιστο. Προόδους και επιστροφές - επόμενο επίπεδο. Σπάνιες τεχνικές (rectification, Human Design) - είναι διακριτικό.
- Ποιότητα SDK: τυποποιημένα TypeScript και Python SDK εξοικονομούν ώρες.
- Μοντέλο τιμολόγησης: credit‑based κλιμακώνεται καλύτερα από per‑request, σε μεικτό φορτίο.
Για αυτό το tutorial θα χρησιμοποιήσουμε το AstroWay API, γιατί έχει και τα τέσσερα (777 endpoint, Swiss Ephemeris, τυποποιημένα SDK, credit‑based).
Βήμα 1: Στήσε backend
Ενότητα με τίτλο «Βήμα 1: Στήσε backend»Ποτέ μην καλέσεις το αστρολογικό API απευθείας από το πρόγραμμα περιήγησης – το κλειδί API σου θα διαρρεύσει. Πάντα περνάει μέσω του δικού σου backend.
mkdir my-astrology-appcd my-astrology-appnpm init -ynpm install express @astroway/sdk zodnpm install -D typescript @types/express @types/node tsxΔημιούργησε το 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'));Τρέξε:
ASTROWAY_API_KEY=aw_test_... npx tsx src/server.tsΈλεγχος με 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}'Λαμβάνεις πλήρη JSON natal chart.
Βήμα 2: Frontend
Ενότητα με τίτλο «Βήμα 2: Frontend»Οποιοδήποτε framework θα δουλέψει. Για παράδειγμα – React με μια απλή φόρμα:
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> );}Βήμα 3: Synastry
Ενότητα με τίτλο «Βήμα 3: Synastry»Η συμβατότητα – η επόμενη προφανής λειτουργία. Πρόσθεσε στο 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, });});Όλα. Ένα endpoint, 50 credits ανά κλήση, επιστρέφει score 0–100 και cross‑aspects.
Βήμα 4: Καθημερινά horoscopes
Ενότητα με τίτλο «Βήμα 4: Καθημερινά horoscopes»Για το content‑engagement, τα καθημερινά horoscopes είναι must have. Το AstroWay τα δημιουργεί από πραγματικά δεδομένα transits:
// 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! });});Σημαντικό: Το AI‑γενόμενο περιεχόμενο περιέχει disclaimer που πρέπει να δείχνεις στους χρήστες (σύμφωνα με τους Terms of Service). Μην το αφαιρέσεις.
Βήμα 5: Caching
Ενότητα με τίτλο «Βήμα 5: Caching»Τα καθημερινά horoscopes είναι τα ίδια για όλους τους χρήστες με την ίδια ημερομηνία γέννησης και παρόμοιες natal charts. Κάνε έντονο caching:
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 υπάρχει επίσης ενσωματωμένο 5‑λεπτο server caching (X-Cache: HIT), αλλά για μακροχρόνιο περιεχόμενο χρειάζεται δικό σου cache.
Βήμα 6: Deploy
Ενότητα με τίτλο «Βήμα 6: Deploy»Οποιαδήποτε πλατφόρμα θα δουλέψει. Για γρήγορη εκκίνηση – Vercel ή Railway:
# vercel.json{ "functions": { "src/server.ts": { "runtime": "@vercel/node" } } }Στο πάνελ της πλατφόρμας όρισε το env ASTROWAY_API_KEY.
Προγραμματισμός προϋπολογισμού
Ενότητα με τίτλο «Προγραμματισμός προϋπολογισμού»Αν έφτασες εδώ – εκτίμησε την μηνιαία κατανάλωση credits πριν το λανσάρισμα:
credits/month = DAU × (avg_charts_per_user × 20 + avg_synastries × 50 + avg_horoscopes × 20) × 30Για 100 DAU με 1 chart + 1 horoscope + 0.3 synastries ανά χρήστη την ημέρα:
100 × (20 + 20 + 0.3 × 50) × 30 = 165,000 credits/monthΑυτό είναι το πλάνο Starter για $19/μήν (200K credits).
Τι έπεται
Ενότητα με τίτλο «Τι έπεται»Αναβαθμισμένες λειτουργίες που αξίζει να προσθέσεις καθώς μεγαλώνεις:
- Overlay transits:
/v1/transitsδείχνει τις τρέχουσες θέσεις των πλανητών στη natal chart - Progressions:
/v1/progressionsγια τις καμπύλες ψυχολογικής ανάπτυξης - Solar return:
/v1/solar-returnγια “πρόβλεψη για το έτος από την ημερομηνία γέννησης” - Human Design: Human Design API ανοίγει έναν ολοκαίνουργιο λειτουργικό τομέα
- Astrocartography:
/v1/acgχαρτογραφεί πού πρέπει να ζει ο χρήστης
Κάθε λειτουργία είναι δύσκολη στην υλοποίηση από το μηδέν, αλλά – μία κλήση API με το AstroWay.
- Πάρε δωρεάν API‑key: 10 000 credits / μήνα
- Πλήρης API reference: όλα τα 777 endpoint
- Birth Chart API: λεπτομερής τεκμηρίωση του endpoint του χάρτη
Αυτή η ίδια Swiss Ephemeris που υπάρχει στο Solar Fire - σε 4 γραμμές κώδικα.
Δωρεάν κλειδί χωρίς κάρτα. 5.000 αιτήματα ανά μήνα μέχρι την πρώτη πληρωμή.