クイックスタート

登録から JSON の完全な出生図まで 5 分です。SDK のインストール、最初のリクエスト、レスポンスヘッダー、認証、エラー処理を扱います。

API キーを生成する
Section titled “API キーを生成する”

ダッシュボードを開き、Generate key をクリックします。無料プランでは 毎月 10 000 クレジットが永久に 使え、カードの入力も不要です。キーは次のように始まります。
- aw_live_*: 本番用、実際に課金されます
- aw_test_*: サンドボックス用、クレジットを消費せず、決定論的なレスポンスを返します
キーは秘密情報です。git にコミットしたり、フロントエンドのコードに入れたりしないでください。フロントエンドには、プロキシ用のバックエンドか短命のセッショントークン (Phase 3) を使ってください。
SDK をインストールする
Section titled “SDK をインストールする”

API は通常の REST + JSON なので、SDK は必須ではありません。ただし 3 つとも公開済みです: TypeScript (@astroway/sdk)、Python (astroway)、PHP (astroway/sdk)。さらに AI エージェント向けの MCP サーバー (@astroway/mcp) もあります。
Terminal window
# No SDK needed - just curl and a key: export AW_KEY="aw_test_demo_replaceme"
Terminal window
npm install @astroway/sdk # or without an SDK: native fetch, Node 18+ or the browser export AW_KEY="aw_test_demo_replaceme"
Terminal window
pip install astroway # or without an SDK: requests or httpx export AW_KEY="aw_test_demo_replaceme"
Terminal window
composer require astroway/sdk # or without an SDK: guzzlehttp/guzzle + raw HTTP
Terminal window
# 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

最初のリクエストを送る

1991 年 8 月 24 日 16:30 EEST、キーウ の出生図の計算:

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

// 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, ... }

# 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
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 は、その日付に時計が示していた UTC からのずれを時間単位で表したものです。わからない場合は、代わりに "timezone": "Europe/Kyiv"、または座標からゾーンを求める "timezone": "auto" を送れば、サーバーが夏時間も含めてずれを計算します: フィールドの形式。

レスポンスを読み解く
Section titled “レスポンスを読み解く”

どのレスポンスも、惑星、ハウス、アスペクト、meta ブロック (cache hit、credits、engine version) を含む JSON です。
- JSON
- HTTP Headers
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/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
残高を確認する
Section titled “残高を確認する”

ダッシュボードは使用量をリアルタイムで表示します: api.astroway.info/dashboard。API からも確認できます。
Terminal window
```
curl https://api.astroway.info/v1/keys/usage \
  -H "X-Api-Key: $AW_KEY"
```

Authentication

AstroWay API は X-Api-Key ヘッダーでリクエストを認証します。Bearer トークンやクエリ文字列のキーには対応していません。

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/。

Errors

すべてのエラーは ok: false と error オブジェクトの形式で返されます。error.code フィールド (UPPER_SNAKE_CASE) はスクリプト向けに安定しています。分岐は message ではなくこれで行ってください。

{
  "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): キーが存在しない、または revoke 済み
PLAN_UPGRADE_REQUIRED (402): 上位のプランまたはアドオンパックが必要
CREDITS_EXHAUSTED (429): 月間のクレジット予算を使い切った
RATE_LIMIT (429): RPM を超過。Retry-After: <sec> ヘッダー付きで返されます
internal_calc_error (500): 天体暦のエラー。SDK 側で自動リトライされます

完全な一覧と意味: /errors/。

Rate limits

プラン	上限
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1 000 req/min
Enterprise	custom

超過すると Retry-After (秒) 付きの 429 になります。公式 SDK はデフォルトで指数バックオフのリトライを行います。詳細: /rate-limits-credits/。

認証: ベストプラクティス、キーのローテーション、サンドボックスモード
クレジットと制限: コスト表、レート制限、overage
例: 出生図: /v1/chart の詳しい解説
GitHub の既成の連携例: 公式 SDK を使った Discord/Slack ボット、OpenAI tools、Cloudflare、FastAPI
完全な API リファレンス: playground 付きの 771 件すべてのエンドポイント

参考になりましたか？

最終更新日: 2026/09/29

クイックスタート

API キーを生成する

SDK をインストールする

最初のリクエストを送る

レスポンスを読み解く

残高を確認する

Authentication

Errors

Rate limits

次へ