Γρήγορη εκκίνηση

Πέντε λεπτά από την εγγραφή μέχρι έναν πλήρη γενέθλιο χάρτη σε JSON. Καλύπτει εγκατάσταση SDK, πρώτο αίτημα, κεφαλίδες απάντησης, αυθεντικοποίηση και χειρισμό σφαλμάτων.

// γρήγορη εκκίνηση

Λάβετε κλειδί API σε 60 δευτερόλεπτα

10.000 πιστώσεις/μήνα δωρεάν για πάντα. Χωρίς κάρτα.

1. 01
   Εγγραφείτε

   Email + κωδικός πρόσβασης. Ένας λογαριασμός για όλα τα προϊόντα AstroWay.
2. 02
   Δημιουργήστε κλειδί

   Στον πίνακα ελέγχου, κάντε κλικ στο "Δημιουργία κλειδιού". aw_live_ ή aw_test_ (πλατφόρμα δοκιμών).
3. 03
   Κάντε αίτημα

   POST /v1/chart με header X-Api-Key. Πλήρης ωριαία χάρτα σε JSON.

Εγγραφή - δωρεάν→Γρήγορη εκκίνηση

1. Δημιούργησε κλειδί API

   Μπες στο dashboard και πάτησε Generate key. Το δωρεάν πλάνο δίνει 10 000 credits/μήνα για πάντα, χωρίς να βάλεις κάρτα. Τα κλειδιά ξεκινούν με:

   • aw_live_*: production, πραγματικές χρεώσεις
   • aw_test_*: sandbox, χωρίς χρέωση credits, ντετερμινιστική απάντηση

   Προσοχή

   Το κλειδί είναι μυστικό. Μην το κάνεις commit στο git και μην το βάζεις σε κώδικα frontend. Για το frontend χρησιμοποίησε ένα proxy backend ή βραχύβια session tokens (Phase 3).

2. Εγκατάστησε το SDK

   Το API είναι απλό REST + JSON, οπότε το SDK δεν είναι υποχρεωτικό. Όμως και τα τρία έχουν ήδη δημοσιευτεί: TypeScript (@astroway/sdk), Python (astroway) και PHP (astroway/sdk), καθώς και ο MCP server (@astroway/mcp) για AI agents.

   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. Κάνε το πρώτο αίτημα

   Υπολογισμός γενέθλιου χάρτη για 24 Αυγούστου 1991, 16:30 EEST, Κίεβο:

   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 είναι η απόκλιση που έδειχναν τα ρολόγια εκείνη την ημερομηνία, σε ώρες. Αν δεν την ξέρεις, στείλε αντί γι’ αυτήν "timezone": "Europe/Kyiv" ή "timezone": "auto" για να ληφθεί η ζώνη από τις συντεταγμένες, και ο server θα υπολογίσει μόνος του την απόκλιση, μαζί με τη θερινή ώρα: μορφές πεδίων.

4. Ανάλυσε την απάντηση

   Κάθε απάντηση είναι JSON με πλανήτες, οίκους, όψεις και ένα μπλοκ meta (cache hit, credits, έκδοση μηχανής).

   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. Έλεγξε το υπόλοιπο

   Το dashboard δείχνει τη χρήση σε πραγματικό χρόνο: api.astroway.info/dashboard. Ή μέσω του API:

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

Αυθεντικοποίηση

Το AstroWay API αυθεντικοποιεί τα αιτήματα μέσω της κεφαλίδας X-Api-Key. Bearer tokens και κλειδιά στο query string δεν υποστηρίζονται.

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

Τύπος κλειδιού	Πρόθεμα	Συμπεριφορά
Production	aw_live_*	Χρεώνει πραγματικά credits από τον λογαριασμό
Sandbox	aw_test_*	Ντετερμινιστική mock απάντηση, χωρίς χρέωση
Restricted (Pro+)	aw_live_* με περιορισμό	Περιορισμένο σε συγκεκριμένα endpoints / IP / RPS

Τα κλειδιά εναλλάσσονται χωρίς downtime: το παλιό κλειδί συνεχίζει να λειτουργεί για 24 ώρες μετά τη δημιουργία του νέου. Λεπτομέρειες: /authentication/.

Σφάλματα

Όλα τα σφάλματα επιστρέφονται στη μορφή ok: false + αντικείμενο error. Το πεδίο error.code (UPPER_SNAKE_CASE) είναι σταθερό για scripts: κάνε switch σε αυτό, όχι στο 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" }
    ]
  }
}

Οι πιο συχνοί κωδικοί:

• INVALID_INPUT (400): αποτυχημένη επικύρωση Zod. Το details περιέχει πίνακα { path, message }
• INVALID_API_KEY (401): το κλειδί δεν υπάρχει ή έχει ανακληθεί
• PLAN_UPGRADE_REQUIRED (402): απαιτείται ανώτερο πλάνο ή add-on πακέτο
• CREDITS_EXHAUSTED (429): ο μηνιαίος προϋπολογισμός credits εξαντλήθηκε
• RATE_LIMIT (429): ξεπεράστηκε το RPM. Επιστρέφεται με την κεφαλίδα Retry-After: <sec>
• internal_calc_error (500): σφάλμα εφημερίδων. Αυτόματο retry από τη μεριά του SDK

Πλήρης λίστα και σημασίες: /errors/.

Όρια ρυθμού

Πλάνο	Quota
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1 000 req/min
Enterprise	custom

Υπέρβαση → 429 με Retry-After (sec). Τα επίσημα SDK έχουν από προεπιλογή retries με exponential backoff. Λεπτομέρειες: /rate-limits-credits/.

Επόμενα βήματα

• Αυθεντικοποίηση: best practices, εναλλαγή κλειδιών, sandbox mode
• Credits και όρια: πίνακας κόστους, rate limiting, overage
• Παραδείγματα: γενέθλιος χάρτης: αναλυτική εξέταση του /v1/chart
• Έτοιμες ενσωματώσεις στο GitHub: bots για Discord/Slack, OpenAI tools, Cloudflare, FastAPI με τα επίσημα SDK
• Πλήρης αναφορά API: όλα τα 771 endpoints με playground