Démarrage rapide

Cinq minutes entre l’inscription et une carte natale complète en JSON. Cette page couvre l’installation du SDK, la première requête, les en-têtes de réponse, l’authentification et la gestion des erreurs.

// démarrage rapide

Obtiens une clé API en 60 secondes

10 000 crédits/mois gratuits à vie. Pas de carte.

1. 01
   Inscris-toi

   Email + mot de passe. Un compte pour tous les produits AstroWay.
2. 02
   Crée une clé

   Dans le dashboard, clique sur "Créer une clé". aw_live_ ou aw_test_ (sandbox).
3. 03
   Fais une requête

   POST /v1/chart avec l'en-tête X-Api-Key. Carte natale complète en JSON.

S'inscrire - gratuit→Démarrage rapide

1. Générez une clé API

   Rendez-vous dans le tableau de bord et cliquez sur Generate key. Le plan gratuit offre 10 000 crédits/mois pour toujours, sans carte bancaire. Les clés commencent par:

   • aw_live_*: production, facturation réelle
   • aw_test_*: sandbox, sans débit de crédits, réponse déterministe

   Attention

   Une clé est un secret. Ne la commitez pas dans git et ne l’insérez pas dans du code frontend. Pour le frontend, utilisez un backend proxy ou des jetons de session à courte durée de vie (Phase 3).

2. Installez le SDK

   L’API est du REST + JSON classique, le SDK n’est donc pas obligatoire. Mais les trois sont déjà publiés: TypeScript (@astroway/sdk), Python (astroway) et PHP (astroway/sdk), plus un serveur MCP (@astroway/mcp) pour les agents IA.

   cURL

   # No SDK needed - just curl and a key:
   export AW_KEY="aw_test_demo_replaceme"

   TypeScript

   npm install @astroway/sdk
   # or without an SDK: native fetch, Node 18+ or the browser
   export AW_KEY="aw_test_demo_replaceme"

   Python

   pip install astroway   # or without an SDK: requests or httpx
   export AW_KEY="aw_test_demo_replaceme"

   PHP

   composer require astroway/sdk
   # or without an SDK: guzzlehttp/guzzle + raw HTTP

   MCP

   # For AI agents - Claude Desktop, Cursor IDE, Windsurf,
   # VS Code (llm CLI), GPT with MCP via the OpenAI Realtime API,
   # or any MCP-compatible client:
   npx -y @astroway/mcp   # 700+ tools, OpenAPI auto-sync

3. Faites votre première requête

   Calcul de la carte natale pour le 24 août 1991, 16:30 EEST, Kyiv:

   cURL

   first-request.sh

   curl -X POST https://api.astroway.info/v1/chart \
     -H "X-Api-Key: $AW_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "date": "1991-08-24",
       "time": "16:30:00",
       "timezoneOffset": 3,
       "latitude": 50.4501,
       "longitude": 30.5234,
       "houseSystem": "P"
     }'

   TypeScript

   first-request.ts

   // native fetch - Node 18+ / Bun / Deno / browser. With the SDK: npm install @astroway/sdk
   const r = await fetch('https://api.astroway.info/v1/chart', {
     method: 'POST',
     headers: {
       'X-Api-Key': process.env.AW_KEY!,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
       date: '1991-08-24',
       time: '16:30:00',
       timezoneOffset: 3,
       latitude: 50.4501,
       longitude: 30.5234,
       houseSystem: 'P',
     }),
   });
   
   const { data: chart } = await r.json();
   console.log(chart.planets[0]); // { id: 0, name: 'Sun', longitude: 151.12, ... }

   Python

   first_request.py

   # requests or httpx. With the SDK: pip install astroway
   import os, requests
   
   r = requests.post(
       'https://api.astroway.info/v1/chart',
       headers={'X-Api-Key': os.environ['AW_KEY']},
       json={
           'date': '1991-08-24',
           'time': '16:30:00',
           'timezoneOffset': 3,
           'latitude': 50.4501,
           'longitude': 30.5234,
           'houseSystem': 'P',
       },
   )
   chart = r.json()['data']
   print(chart['planets'][0])

   PHP

   first-request.php

   <?php
   use GuzzleHttp\Client;
   
   $aw = new Client(['base_uri' => 'https://api.astroway.info/v1/']);
   $r = $aw->post('chart', [
       'headers' => ['X-Api-Key' => getenv('AW_KEY')],
       'json' => [
           'date' => '1991-08-24',
           'time' => '16:30:00',
           'timezoneOffset' => 3,
           'latitude' => 50.4501,
           'longitude' => 30.5234,
           'houseSystem' => 'P',
       ],
   ]);
   
   $chart = json_decode($r->getBody(), true)['data'];
   print_r($chart['planets'][0]);

   timezoneOffset est le décalage qu’affichaient les horloges à cette date, en heures. Si vous ne le connaissez pas, envoyez à la place "timezone": "Europe/Kyiv" ou "timezone": "auto" pour déduire la zone des coordonnées, et le serveur calculera lui-même le décalage, heure d’été comprise: formats des champs.

4. Analysez la réponse

   Chaque réponse est un JSON avec les planètes, les maisons, les aspects et un bloc meta (cache hit, crédits, version du moteur).

   JSON

   response.json

   {
     "ok": true,
     "data": {
       "julianDay": 2448493.0625,
       "planets": [
         { "id": 0, "name": "Sun", "longitude": 150.894819, "latitude": 0.00019, "isRetrograde": false, "declination": 11.15726 },
         { "id": 1, "name": "Moon", "longitude": 321.634655, "latitude": 2.834053, "isRetrograde": false, "declination": -11.609723 }
       ],
       "houses": {
         "system": "P",
         "cusps": [264.384681, 306.997683, 353.867426],
         "ascendant": 264.384681,
         "mc": 207.315669
       },
       "aspects": [
         {
           "planet1": "Sun",
           "planet2": "Moon",
           "type": { "name": "Opposition", "angle": 180, "isMajor": true },
           "exactAngle": 170.739837,
           "orb": 9.260163,
           "isApplying": true
         }
       ],
       "chartSect": "diurnal",
       "meta": { "engineVersion": "2.10.03", "calculatedAt": "2026-08-22T20:53:31.431Z" }
     }
   }

   HTTP Headers

   HTTP/2 200
   content-type: application/json
   x-credits-used: 20
   x-credits-remaining: 9980
   x-credits-limit: 10000
   x-credits-reset: 2026-09-01T00:00:00.000Z
   x-ratelimit-limit: 10
   x-ratelimit-remaining: 9
   x-ratelimit-reset: 1787432304
   x-request-id: 8aec43e9bc749b37e998a489bbad1757
   x-cache: MISS

5. Vérifiez votre solde

   Le tableau de bord affiche l’usage en temps réel: api.astroway.info/dashboard. Ou via l’API:

   curl https://api.astroway.info/v1/keys/usage \
     -H "X-Api-Key: $AW_KEY"

Authentification

L’API AstroWay authentifie les requêtes via l’en-tête X-Api-Key. Les jetons Bearer et les clés passées en query string ne sont pas pris en charge.

curl -H "X-Api-Key: aw_live_..." https://api.astroway.info/v1/health

Type de clé	Préfixe	Comportement
Production	aw_live_*	Débite de vrais crédits du compte
Sandbox	aw_test_*	Réponse fictive déterministe, sans facturation
Restreinte (Pro+)	aw_live_* avec restriction	Limitée à des endpoints / IP / RPS précis

La rotation des clés se fait sans interruption: l’ancienne clé continue de fonctionner 24 heures après la génération de la nouvelle. Détails: /authentication/.

Erreurs

Toutes les erreurs sont renvoyées au format ok: false + un objet error. Le champ error.code (UPPER_SNAKE_CASE) est stable pour les scripts: faites votre switch dessus, pas sur message.

error-response.json

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Validation failed: date: Invalid input: expected string, received undefined",
    "details": [
      { "path": "date", "message": "Invalid input: expected string, received undefined" }
    ]
  }
}

Les codes les plus fréquents:

• INVALID_INPUT (400): échec de la validation Zod; details contient un tableau { path, message }
• INVALID_API_KEY (401): la clé n’existe pas ou a été révoquée
• PLAN_UPGRADE_REQUIRED (402): un plan supérieur ou un pack add-on est nécessaire
• CREDITS_EXHAUSTED (429): le budget mensuel de crédits est épuisé
• RATE_LIMIT (429): RPM dépassé; renvoyé avec l’en-tête Retry-After: <sec>
• internal_calc_error (500): erreur d’éphémérides; retry automatique côté SDK

Liste complète et sémantique: /errors/.

Rate limits

Plan	Quota
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1 000 req/min
Enterprise	sur mesure

Dépassement → 429 avec Retry-After (sec). Les SDK officiels effectuent par défaut des retries avec backoff exponentiel. Détails: /rate-limits-credits/.

Pour aller plus loin

• Authentification: bonnes pratiques, rotation des clés, mode sandbox
• Crédits et limites: tableau des coûts, rate limiting, overage
• Exemples: carte natale: analyse détaillée de /v1/chart
• Intégrations prêtes à l’emploi sur GitHub: bots Discord/Slack, outils OpenAI, Cloudflare, FastAPI sur les SDK officiels
• Référence complète de l’API: les 771 endpoints avec playground