Hızlı başlangıç

Kayıttan JSON biçiminde eksiksiz bir doğum haritasına beş dakika. SDK kurulumunu, ilk isteği, yanıt başlıklarını, kimlik doğrulamayı ve hata işlemeyi kapsar.

// hızlı başlangıç

60 saniyede API anahtarı al

Ayda 10.000 kredi ücretsiz. Kartsız.

1. 01
   Kayıt ol

   E-posta + şifre. Tüm AstroWay ürünleri için tek hesap.
2. 02
   Anahtar oluştur

   Konsolda 'Anahtar oluştur' butonuna tıkla. aw_live_ veya aw_test_ (kum havuzu).
3. 03
   İstek gönder

   X-Api-Key başlığıyla POST /v1/chart. Tam natal harita JSON olarak.

Ücretsiz kaydol→Hızlı başla

1. API anahtarı oluşturun

   Panele girin ve Generate key’e tıklayın. Ücretsiz plan süresiz olarak ayda 10 000 kredi verir, kart bilgisi girmeden. Anahtarlar şu öneklerle başlar:

   • aw_live_*: production, gerçek ücretlendirme
   • aw_test_*: sandbox, kredi düşülmez, deterministik yanıt

   Dikkat

   Anahtar bir sırdır. Onu git’e commit etmeyin, frontend koduna koymayın. Frontend için bir proxy backend veya kısa ömürlü oturum token’ları (Phase 3) kullanın.

2. SDK’yı kurun

   API sıradan bir REST + JSON API’sidir, bu yüzden SDK zorunlu değildir. Ama üçü de yayımlandı: TypeScript (@astroway/sdk), Python (astroway) ve PHP (astroway/sdk), ayrıca AI ajanları için MCP sunucusu (@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. İlk isteğinizi yapın

   24 Ağustos 1991, 16:30 EEST, Kyiv için doğum haritası hesaplaması:

   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, o tarihte saatlerin tuttuğu farkın saat cinsinden değeridir. Bilmiyorsanız, bunun yerine "timezone": "Europe/Kyiv" ya da bölgeyi koordinatlardan almak için "timezone": "auto" gönderin; sunucu farkı yaz saatiyle birlikte kendisi hesaplar: alan biçimleri.

4. Yanıtı ayrıştırın

   Her yanıt gezegenler, evler, açılar ve bir meta bloğu (cache hit, krediler, motor sürümü) içeren bir JSON’dur.

   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. Bakiyenizi kontrol edin

   Panel kullanımı gerçek zamanlı gösterir: api.astroway.info/dashboard. Ya da API üzerinden:

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

Kimlik doğrulama

AstroWay API istekleri X-Api-Key başlığıyla doğrular. Bearer token’lar ve query-string anahtarları desteklenmez.

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

Anahtar türü	Önek	Davranış
Production	aw_live_*	Hesaptan gerçek kredi düşer
Sandbox	aw_test_*	Deterministik sahte yanıt, ücretlendirme yok
Restricted (Pro+)	kısıtlamalı aw_live_*	Belirli endpoint’ler / IP / RPS ile sınırlı

Anahtarlar kesintisiz döndürülür: eski anahtar, yenisi oluşturulduktan sonra 24 saat çalışmaya devam eder. Ayrıntılar: /authentication/.

Hatalar

Tüm hatalar ok: false + error nesnesi biçiminde döndürülür. error.code alanı (UPPER_SNAKE_CASE) script’ler için kararlıdır: message’a göre değil, buna göre switch yapın.

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" }
    ]
  }
}

En sık görülen kodlar:

• INVALID_INPUT (400): Zod doğrulaması başarısız; details bir { path, message } dizisi içerir
• INVALID_API_KEY (401): anahtar mevcut değil veya iptal edilmiş
• PLAN_UPGRADE_REQUIRED (402): daha yüksek bir plan veya add-on paketi gerekiyor
• CREDITS_EXHAUSTED (429): aylık kredi bütçesi tükendi
• RATE_LIMIT (429): RPM aşıldı; Retry-After: <sec> başlığıyla döner
• internal_calc_error (500): efemeris hatası; SDK tarafında otomatik yeniden deneme

Tam liste ve anlamları: /errors/.

Rate limit’ler

Plan	Kota
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1 000 req/min
Enterprise	özel

Aşım → Retry-After (sn) ile 429. Resmî SDK’larda varsayılan olarak üstel backoff ile yeniden denemeler bulunur. Ayrıntılar: /rate-limits-credits/.

Sonraki adımlar

• Kimlik doğrulama: en iyi uygulamalar, anahtar döndürme, sandbox modu
• Krediler ve limitler: maliyet tablosu, rate limiting, overage
• Örnekler: doğum haritası: /v1/chart’ın ayrıntılı incelemesi
• GitHub’da hazır entegrasyonlar: resmî SDK’lar üzerinde Discord/Slack botları, OpenAI araçları, Cloudflare, FastAPI
• Tam API referansı: playground ile birlikte 771 endpoint’in tamamı