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

🕓 Note du 2026-04-14, mise à jour 2026-05-09. TS / Python / PHP SDK sont maintenant disponibles sur les registres publics — @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Détails dans le changelog.

Tu veux créer une application astrologique. Par où commencer ? Dans ce guide — solutions et code : du choix de l’API à la mise en production d’un produit fonctionnel.

Avant de commencer à coder, réfléchis : les calculs doivent-ils être effectués sur le client ou sur le 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 complexe (utilisation commerciale de Swiss Ephemeris a des limitations), tu gères toi-même le code de calcul

API serveur (AstroWay, Prokerala, etc.) :

• Avantages : pas de dépendances client, petit bundle d’application, rapide sur mobile, pas de problème de licence
• Inconvénients : coût en crédits par requête, retard sur les requêtes « froides »

Pour la plupart des applications, l’API serveur est gagnant. Les utilisateurs mobiles n’attendent pas 2 Mo de WASM ; les nuances de licence ne valent pas la peine ; et les API modernes mettent en cache gratuitement les requêtes identiques (AstroWay met en cache pendant 5 minutes avec l’en-tête X-Cache: HIT).

Qu’est-ce qui compte :

• Précision — cherche Swiss Ephemeris « sous le capot » (±1 seconde angulaire). Si l’API ne le dit pas explicitement — demande.
• Couverture — natif + synastrie + transits — minimum. Progrès et retours — niveau suivant. Techniques rares (rectification, Human Design) — c’est un différentiateur.
• Qualité du SDK — TypeScript et Python SDK typés économisent des heures.
• Modèle de tarification — credit-based évolue mieux que per-request, sur une charge mixte.

Pour ce tutoriel, nous allons prendre AstroWay API, car il a les quatre (723 points de terminaison, Swiss Ephemeris, SDK typés, credit-based).

Ne jamais appeler l’API astrologique directement depuis le navigateur — ta clé API sera compromise. Toujours passer par ton propre 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

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({
      ...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.ts

Vérifie via 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}'

Reçois la carte natale JSON complète.

N’importe quel framework fera l’affaire. Pour l’exemple — React avec un formulaire simple :

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="Timezone offset (par exemple 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>Construire la carte</button>
      </form>

      {chart && (
        <div>
          <h2>Planètes</h2>
          <ul>
            {chart.planets.map(p => (
              <li key={p.name}>{p.name}: {p.sign} (maison {p.house})</li>
            ))}
          </ul>
          <h2>Aspects</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>
  );
}

La compatibilité est 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(parsed.data);
  res.json({
    score: result.compatibility.score,
    label: result.compatibility.label,
    aspects: result.crossAspects,
  });
});

Voilà. Un point de terminaison, 50 crédits par appel, retourne un score 0-100 et des aspects croisés.

Pour l’engagement des contenus, les horoscopes quotidiens sont un must. AstroWay les génère à partir de données réelles de transits :

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, // obligatoire de le conserver dans l'UI !
  });
});

Important : le contenu généré par l’IA contient un disclaimer que tu es obligé d’afficher aux utilisateurs (selon les Conditions de service). Ne le supprime pas.

Les horoscopes quotidiens sont identiques pour tous les utilisateurs ayant le même jour de naissance et des cartes natales similaires. Mets en cache de manière agressive :

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

AstroWay a également une mise en cache serveur intégrée de 5 minutes (X-Cache: HIT), mais pour le contenu à longue durée de vie, un cache personnalisé est nécessaire.

N’importe quelle plate-forme fera l’affaire. Pour un démarrage rapide — Vercel ou Railway :

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

Dans le panneau de la plate-forme, configure l’environnement ASTROWAY_API_KEY.

Si tu es arrivé jusqu’ici — évalue la consommation mensuelle de crédits avant de lancer :

crédits/mois = DAU × (avg_charts_par_utilisateur × 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 crédits / mois

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

Fonctionnalités améliorées qui valent la peine d’être ajoutées avec la croissance :

• Superposition de transits — /v1/transits montre les positions actuelles des planètes sur la carte natale
• Progrès — /v1/progressions pour les arcs de développement psychologique
• Retour solaire — /v1/solar-return pour la « prévision pour l’année de naissance »
• Human Design — Human Design API ouvre un tout nouveau domaine fonctionnel
• Astrocartographie — /v1/acg mappe où l’utilisateur devrait vivre

Chaque fonctionnalité est difficile à mettre en œuvre à partir de zéro, mais — un défi d’appel API avec AstroWay.

• Obtenez une clé API gratuite — 10 000 crédits / mois
• Référence complète de l’API — tous les 723 points de terminaison
• API de carte de naissance — documentation détaillée du point de terminaison de la carte