AstroWay/api v2.295.7 · fr
tous les systèmes sont opérationnels

Construire une application d'astrologie : guide complet pour les développeurs

Guide étape par étape pour créer une application d'astrologie à partir de zéro - choix de l'API, architecture, première carte natale, ajout de synastrie et de transits, déploiement.

🕓 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.

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).

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).

Ne jamais appeler l’API d’astrologie directement depuis le navigateur – ta clé API fuit. Passe toujours par ton backend.

Fenêtre de terminal
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

Cré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 :

Fenêtre de terminal
ASTROWAY_API_KEY=aw_test_... npx tsx src/server.ts

Vérification avec curl :

Fenêtre de terminal
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.

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

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.

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.

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.

N’importe quelle plateforme convient. Pour un démarrage rapide – Vercel ou Railway :

Fenêtre de terminal
# 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.

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) × 30

Pour 100 DAU avec 1 carte + 1 horoscope + 0.3 synastries par utilisateur par jour :

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

C’est le plan Starter à $19/mois (200 K crédits).

Fonctionnalités avancées à ajouter à mesure que tu grandis :

  • Overlay des transits : /v1/transits montre les positions actuelles des planètes sur la carte natale
  • Progressions : /v1/progressions pour les arcs de développement psychologique
  • Solar return : /v1/solar-return pour 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/acg cartographie où l’utilisateur devrait vivre

Chaque fonctionnalité est lourde à implémenter de zéro, mais – un seul appel API avec AstroWay.

MakSeong · AstroWay

Je fais l'API AstroWay : j'enveloppe Swiss Ephemeris dans du REST pur et j'écris sur les détails ennuyeux qui sont en fait importants.

// construis avec ça

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.

Plus d'articles du blog voir tous les articles →

Ephemeris 2026-07-19

Comment nous gardons la précision sous contrôle : la CI contre swetest et la NASA

Dans une API d'astrologie, la précision se dégrade facilement après un seul refactoring des éphémérides. Voici notre protection : un seul noyau Swiss Ephemeris pour l'application et l'API, des centaines de snapshots figés sur des thèmes de référence et la triangulation de chaque PR contre swetest CGI, Kerykeion, Prokerala et le catalogue d'éclipses de la NASA.

Engineering 2026-07-15

Trois SDK officiels : TypeScript, Python, PHP au lieu de curl brut

Le HTTP brut fonctionne, mais un client typé fait gagner des heures : autocomplétion des chemins, types de requête et de réponse, retry intégré sur 408/409/429/5xx et hiérarchie d'erreurs à la Stainless. Tour d'horizon des trois SDK officiels, @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist), et de la manière dont ils sont générés à partir d'un même contrat 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.