🕓 Enregistrement du 2026-04-14, mis à jour le 2026-05-09. TS / Python / PHP SDK sont maintenant sur les registres publics -
@astroway/sdk(npm),astroway(PyPI),astroway/sdk(Packagist). Détails dans journal des modifications.
Tu veux créer une application d’astrologie. Par où commencer ? Dans ce guide – solution et code : du choix de l’API au déploiement d’un produit fonctionnel.
Questions d’architecture
Section intitulée « Questions d’architecture »Avant d’écrire du code, décide : calcul côté client ou côté serveur ?
Client (par exemple, Swiss Ephemeris WASM dans le navigateur) :
- Avantages : pas de coût par requête, fonctionne hors ligne, contrôle total
- Inconvénients : ~2 Mo de WASM par utilisateur, licence compliquée (l’utilisation commerciale de Swiss Ephemeris est limitée), tu maintiens toi‑même le code de calcul
API serveur (AstroWay, Prokerala, etc.) :
- Avantages : aucune dépendance côté client, bundle d’application réduit, rapide sur mobile, sans problème de licence
- Inconvénients : coût en crédits par requête, latence sur les requêtes “à froid”
Pour la plupart des applications, l’API serveur l’emporte. Les utilisateurs mobiles n’attendront pas 2 Mo de WASM ; les problèmes de licence sont à éviter ; et les API modernes mettent en cache gratuitement les requêtes identiques (AstroWay fait un cache de 5 minutes avec l’en‑tête X-Cache: HIT).
Choix de l’API
Section intitulée « Choix de l’API »Ce qui compte :
- Précision : cherche Swiss Ephemeris “sous le capot” (±1 seconde d’arc). Si l’API ne le précise pas – demande.
- Couverture : natal + synastrie + transits : le minimum. Progressions et retours – le niveau suivant. Techniques rares (rectification, Human Design) – différenciateur.
- Qualité du SDK : SDK typés TypeScript et Python font gagner des heures.
- Modèle tarifaire : credit‑based s’adapte mieux que per‑request sous charge mixte.
Pour ce tutoriel, prenons AstroWay API, car il possède les quatre : (777 endpoint, Swiss Ephemeris, SDK typés, credit‑based).
Étape 1 : Mettre en place le backend
Section intitulée « Étape 1 : Mettre en place le backend »Ne jamais appeler l’API d’astrologie directement depuis le navigateur – ta clé API fuit. Passe toujours par ton backend.
mkdir my-astrology-appcd my-astrology-appnpm init -ynpm install express @astroway/sdk zodnpm install -D typescript @types/express @types/node tsxCrée 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'));Lance :
ASTROWAY_API_KEY=aw_test_... npx tsx src/server.tsVérification avec 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}'Tu obtiens la carte natale complète au format JSON.
Étape 2 : Frontend
Section intitulée « Étape 2 : Frontend »N’importe quel framework convient. Par exemple – React avec un formulaire simple :
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> );}Étape 3 : Synastrie
Section intitulée « Étape 3 : Synastrie »Compatibilité – la prochaine fonctionnalité évidente. Ajoute dans 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, });});Voilà. Un endpoint, 50 crédits par appel, renvoie un score 0–100 et les cross‑aspects.
Étape 4 : Horoscopes quotidiens
Section intitulée « Étape 4 : Horoscopes quotidiens »Pour l’engagement de contenu, les horoscopes quotidiens sont indispensables. AstroWay les génère à partir des données réelles de 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! });});Important : le contenu généré par IA contient un disclaimer que tu dois afficher aux utilisateurs (selon les Terms of Service). Ne le retire pas.
Étape 5 : Caching
Section intitulée « Étape 5 : Caching »Les horoscopes quotidiens sont identiques pour tous les utilisateurs nés le même jour et ayant des cartes natales similaires. Cache agressivement :
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 propose également un cache serveur intégré de 5 minutes (X-Cache: HIT), mais pour du contenu durable, un cache propre est nécessaire.
Étape 6 : Déploiement
Section intitulée « Étape 6 : Déploiement »N’importe quelle plateforme convient. Pour un démarrage rapide – Vercel ou Railway :
# vercel.json{ "functions": { "src/server.ts": { "runtime": "@vercel/node" } } }Dans le tableau de bord de la plateforme, définis la variable d’environnement ASTROWAY_API_KEY.
Planification du budget
Section intitulée « Planification du budget »Si tu es arrivé jusqu’ici – estime la consommation mensuelle de crédits avant le lancement :
credits/month = DAU × (avg_charts_per_user × 20 + avg_synastries × 50 + avg_horoscopes × 20) × 30Pour 100 DAU avec 1 carte + 1 horoscope + 0.3 synastries par utilisateur par jour :
100 × (20 + 20 + 0.3 × 50) × 30 = 165,000 credits/monthC’est le plan Starter à $19/mois (200 K crédits).
Et après
Section intitulée « Et après »Fonctionnalités avancées à ajouter à mesure que tu grandis :
- Overlay des transits :
/v1/transitsmontre les positions actuelles des planètes sur la carte natale - Progressions :
/v1/progressionspour les arcs de développement psychologique - Solar return :
/v1/solar-returnpour la “prévision de l’année à partir de la date de naissance” - Human Design : Human Design API ouvre tout un nouveau domaine fonctionnel
- Astrocartographie :
/v1/acgcartographie où l’utilisateur devrait vivre
Chaque fonctionnalité est lourde à implémenter de zéro, mais – un seul appel API avec AstroWay.
Démarrage
Section intitulée « Démarrage »- Obtiens une clé API gratuite: 10 000 crédits / mois
- Référence API complète: tous les 777 endpoint
- Birth Chart API: documentation détaillée de l’endpoint de la carte
Le même Swiss Ephemeris que Solar Fire - en 4 lignes de code.
Clé gratuite sans carte. 5 000 appels par mois avant le premier paiement.