Mulai cepat

Lima menit dari pendaftaran hingga bagan natal lengkap dalam JSON. Mencakup instalasi SDK, permintaan pertama, header respons, autentikasi, dan penanganan error.

// mulai cepat

Dapatkan kunci API dalam 60 detik

10.000 kredit/bulan selamanya gratis. Tanpa kartu.

1. 01
   Daftar

   Email + kata sandi. Satu akun untuk semua produk AstroWay.
2. 02
   Buat kunci

   Di dashboard, klik "Buat kunci". aw_live_ atau aw_test_ (sandbox).
3. 03
   Buat permintaan

   POST /v1/chart dengan header X-Api-Key. Peta natal lengkap dalam JSON.

Daftar - gratis→Mulai cepat

1. Buat kunci API

   Buka dasbor dan klik Generate key. Paket gratis memberi 10 000 kredit/bln selamanya - tanpa memasukkan kartu. Kunci diawali dengan:

   • aw_live_*: produksi, tagihan nyata
   • aw_test_*: sandbox, tanpa pemotongan kredit, respons deterministik

   Perhatian

   Kunci adalah secret. Jangan commit ke git, jangan sisipkan ke kode frontend. Untuk frontend, gunakan backend proxy atau token sesi berumur pendek (Phase 3).

2. Pasang SDK

   API ini REST + JSON biasa, jadi SDK tidak wajib. Tetapi ketiganya sudah dipublikasikan: TypeScript (@astroway/sdk), Python (astroway), dan PHP (astroway/sdk), ditambah server MCP (@astroway/mcp) untuk agen AI.

   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. Kirim permintaan pertama

   Perhitungan bagan natal untuk 24 Agustus 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 adalah selisih waktu yang berlaku pada jam di tanggal tersebut, dalam jam. Jika kamu tidak mengetahuinya, kirim "timezone": "Europe/Kyiv" sebagai gantinya, atau "timezone": "auto" untuk mengambil zona dari koordinat, dan server akan menghitung selisihnya sendiri, termasuk waktu musim panas: format field.

4. Uraikan respons

   Setiap respons adalah JSON berisi planet, rumah, aspek, dan blok meta (cache hit, kredit, versi 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. Periksa saldo

   Dasbor menampilkan usage secara real time: api.astroway.info/dashboard. Atau melalui API:

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

Autentikasi

AstroWay API mengautentikasi permintaan melalui header X-Api-Key. Token Bearer dan kunci di query string tidak didukung.

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

Tipe kunci	Prefiks	Perilaku
Production	aw_live_*	Memotong kredit nyata dari akun
Sandbox	aw_test_*	Respons mock deterministik, tanpa tagihan
Restricted (Pro+)	aw_live_* dengan batasan	Dibatasi pada endpoint / IP / RPS tertentu

Kunci dirotasi tanpa downtime - kunci lama tetap berfungsi selama 24 jam setelah kunci baru dibuat. Detail: /authentication/.

Error

Semua error dikembalikan dalam format ok: false + objek error. Field error.code (UPPER_SNAKE_CASE) stabil untuk skrip - lakukan switch berdasarkan field ini, bukan berdasarkan 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" }
    ]
  }
}

Kode yang paling sering muncul:

• INVALID_INPUT (400): validasi Zod gagal; details berisi array { path, message }
• INVALID_API_KEY (401): kunci tidak ada atau sudah dicabut
• PLAN_UPGRADE_REQUIRED (402): dibutuhkan paket lebih tinggi atau add-on pack
• CREDITS_EXHAUSTED (429): anggaran kredit bulanan habis
• RATE_LIMIT (429): RPM terlampaui; dikembalikan dengan header Retry-After: <sec>
• internal_calc_error (500): error efemeris; retry otomatis di sisi SDK

Daftar lengkap dan semantiknya: /errors/.

Rate limit

Paket	Kuota
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1 000 req/min
Enterprise	custom

Jika terlampaui → 429 dengan Retry-After (detik). SDK resmi secara default memiliki retry dengan exponential backoff. Detail: /rate-limits-credits/.

Selanjutnya

• Autentikasi: best practice, rotasi kunci, mode sandbox
• Kredit dan batas: tabel biaya, rate limiting, overage
• Contoh: bagan natal: pembahasan rinci /v1/chart
• Integrasi siap pakai di GitHub: bot Discord/Slack, OpenAI tools, Cloudflare, FastAPI dengan SDK resmi
• Referensi API lengkap: semua 771 endpoint dengan playground