Bắt đầu nhanh

Năm phút từ lúc đăng ký đến một bản đồ sao cá nhân đầy đủ dưới dạng JSON. Bao gồm cài đặt SDK, request đầu tiên, header phản hồi, xác thực và xử lý lỗi.

// khởi động nhanh

Nhận khóa API trong 60 giây

10.000 tín dụng/tháng miễn phí vĩnh viễn. Không cần thẻ.

1. 01
   Đăng ký

   Email + mật khẩu. Một tài khoản cho tất cả sản phẩm AstroWay.
2. 02
   Tạo khóa

   Trong bảng điều khiển, nhấn "Tạo khóa". aw_live_ hoặc aw_test_ (hộp cát).
3. 03
   Gửi yêu cầu

   POST /v1/chart với header X-Api-Key. Bản đồ tử vi đầy đủ dưới dạng JSON.

Đăng ký - miễn phí→Bắt đầu nhanh

1. Tạo API key

   Vào dashboard và nhấn Generate key. Gói miễn phí cho 10 000 credit/tháng mãi mãi - không cần nhập thẻ. Key bắt đầu bằng:

   • aw_live_*: production, tính phí thật
   • aw_test_*: sandbox, không trừ credit, phản hồi tất định

   Chú ý

   Key là bí mật. Đừng commit nó vào git, đừng chèn vào code frontend. Với frontend, hãy dùng backend proxy hoặc session token ngắn hạn (Phase 3).

2. Cài SDK

   API là REST + JSON thông thường, nên SDK không bắt buộc. Nhưng cả ba đều đã được phát hành: TypeScript (@astroway/sdk), Python (astroway) và PHP (astroway/sdk), cùng với máy chủ MCP (@astroway/mcp) cho AI agent.

   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. Gửi request đầu tiên

   Tính bản đồ sao cá nhân cho 24 tháng 8 năm 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 là độ lệch mà đồng hồ áp dụng vào ngày đó, tính bằng giờ. Nếu bạn không biết, hãy gửi "timezone": "Europe/Kyiv" thay thế, hoặc "timezone": "auto" để lấy múi giờ từ tọa độ, và máy chủ sẽ tự tính độ lệch, bao gồm cả giờ mùa hè: định dạng trường.

4. Phân tích phản hồi

   Mỗi phản hồi là JSON với các hành tinh, nhà, góc chiếu và khối meta (cache hit, credit, phiên bản engine).

   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. Kiểm tra số dư

   Dashboard hiển thị mức sử dụng theo thời gian thực: api.astroway.info/dashboard. Hoặc qua API:

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

Xác thực

AstroWay API xác thực request qua header X-Api-Key. Bearer token và key trong query string không được hỗ trợ.

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

Loại key	Tiền tố	Hành vi
Production	aw_live_*	Trừ credit thật từ tài khoản
Sandbox	aw_test_*	Phản hồi mock tất định, không tính phí
Restricted (Pro+)	aw_live_* có giới hạn	Giới hạn theo endpoint / IP / RPS cụ thể

Key được xoay vòng không downtime - key cũ tiếp tục hoạt động 24 giờ sau khi tạo key mới. Chi tiết: /authentication/.

Lỗi

Mọi lỗi được trả về theo định dạng ok: false + object error. Trường error.code (UPPER_SNAKE_CASE) ổn định cho script - hãy switch theo nó, không theo 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" }
    ]
  }
}

Các mã phổ biến nhất:

• INVALID_INPUT (400): không qua validation của Zod; details chứa mảng { path, message }
• INVALID_API_KEY (401): key không tồn tại hoặc đã bị thu hồi
• PLAN_UPGRADE_REQUIRED (402): cần gói cao hơn hoặc pack add-on
• CREDITS_EXHAUSTED (429): đã dùng hết ngân sách credit của tháng
• RATE_LIMIT (429): vượt RPM; trả về kèm header Retry-After: <sec>
• internal_calc_error (500): lỗi ephemeris; SDK tự động retry

Danh sách đầy đủ và ngữ nghĩa: /errors/.

Rate limit

Gói	Hạn mức
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1 000 req/min
Enterprise	tùy chỉnh

Vượt mức → 429 kèm Retry-After (giây). Các SDK chính thức mặc định có retry với exponential backoff. Chi tiết: /rate-limits-credits/.

Tiếp theo

• Xác thực: best practices, xoay vòng key, chế độ sandbox
• Credit và giới hạn: bảng giá, rate limiting, overage
• Ví dụ: bản đồ sao cá nhân: phân tích chi tiết /v1/chart
• Tích hợp có sẵn trên GitHub: bot Discord/Slack, OpenAI tools, Cloudflare, FastAPI trên các SDK chính thức
• API reference đầy đủ: tất cả 771 endpoint với playground