البداية السريعة

خمس دقائق من التسجيل إلى خريطة ولادية كاملة بصيغة JSON. تغطي تثبيت الـ SDK، وأول طلب، وترويسات الاستجابة، والمصادقة، ومعالجة الأخطاء.

// بدء سريع

احصل على مفتاح API في 60 ثانية

10,000 رصيد شهريًا مجانًا إلى الأبد. بدون بطاقة.

1. 01
   سجل حسابك

   البريد الإلكتروني + كلمة المرور. حساب واحد لجميع منتجات AstroWay.
2. 02
   أنشئ مفتاحًا

   في لوحة التحكم، انقر على "إنشاء مفتاح". aw_live_ أو aw_test_ (الوضع التجريبي).
3. 03
   أرسل طلبًا

   POST /v1/chart مع header X-Api-Key. خريطة ميلاد كاملة بتنسيق JSON.

سجل مجاناً→بدء سريع

1. أنشئ مفتاح API

   ادخل إلى لوحة التحكم واضغط Generate key. الخطة المجانية تمنح 10 000 رصيد شهريًا إلى الأبد، دون إدخال بطاقة. تبدأ المفاتيح بـ:

   • aw_live_*: الإنتاج، رسوم حقيقية
   • aw_test_*: sandbox، بلا خصم أرصدة، استجابة حتمية

   تنبيه

   المفتاح سرّ. لا تُدرجه في git، ولا تضعه في كود الواجهة الأمامية. للواجهة الأمامية استخدم خادمًا خلفيًا وسيطًا أو رموز جلسة قصيرة العمر (Phase 3).

2. ثبّت الـ SDK

   الـ API هو REST + JSON عادي، فالـ SDK ليس إلزاميًا. لكن الثلاثة منشورة بالفعل: TypeScript (@astroway/sdk)، وPython (astroway)، وPHP (astroway/sdk)، إضافة إلى خادم MCP (@astroway/mcp) لوكلاء الذكاء الاصطناعي.

   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" لأخذ المنطقة من الإحداثيات، وسيحسب الخادم الإزاحة بنفسه، مع التوقيت الصيفي: صيغ الحقول.

4. حلّل الاستجابة

   كل استجابة هي JSON فيه الكواكب والبيوت والجوانب وكتلة meta (cache hit، credits، engine version).

   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. تحقق من الرصيد

   تعرض لوحة التحكم الاستخدام في الوقت الفعلي: 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 والمفاتيح في query-string غير مدعومة.

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

نوع المفتاح	البادئة	السلوك
Production	aw_live_*	يخصم أرصدة حقيقية من الحساب
Sandbox	aw_test_*	استجابة وهمية حتمية، بلا رسوم
Restricted (Pro+)	aw_live_* مع قيود	مقيّد بنقاط نهاية / IP / RPS محددة

تُدوَّر المفاتيح دون توقف: يستمر المفتاح القديم في العمل 24 ساعة بعد إنشاء الجديد. التفاصيل: /authentication/.

الأخطاء

تُعاد جميع الأخطاء بصيغة ok: false مع كائن error. الحقل error.code (UPPER_SNAKE_CASE) ثابت للسكربتات: بدّل عليه، لا على 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): استُنفدت ميزانية الأرصدة الشهرية
• RATE_LIMIT (429): تجاوز الـ RPM؛ يُعاد مع الترويسة Retry-After: <sec>
• internal_calc_error (500): خطأ في الـ ephemeris؛ إعادة محاولة تلقائية على جانب الـ SDK

القائمة الكاملة والدلالات: /errors/.

حدود المعدل

الخطة	الحصة
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 (بالثواني). الـ SDK الرسمية تعيد المحاولة افتراضيًا مع exponential backoff. التفاصيل: /rate-limits-credits/.

التالي

• المصادقة: أفضل الممارسات، تدوير المفاتيح، وضع sandbox
• الأرصدة والحدود: جدول التكلفة، الـ rate limiting، الاستهلاك الزائد
• أمثلة: الخريطة الولادية: شرح مفصّل لـ /v1/chart
• تكاملات جاهزة على GitHub: بوتات Discord/Slack، أدوات OpenAI، Cloudflare، FastAPI على الـ SDK الرسمية
• مرجع الـ API الكامل: جميع نقاط النهاية الـ 771 مع playground