• エンドポイント
• 認証
• リクエストパラメータ
• レスポンス
• エラーレスポンス
• クレジット消費
• サンプルコード
• 備考

POST または GET /api/v1/calculate

四柱推命の計算結果を取得します。

APIキーによる認証が必要です。以下のいずれかの方法でAPIキーを提供してください。

1. Authorization ヘッダー (推奨):
   Authorization: Bearer YOUR_API_KEY
2. クエリパラメータ:
   ?api_key=YOUR_API_KEY

APIキーはダッシュボードで確認できます。

以下のパラメータを application/json 形式のPOSTボディ、またはURLクエリパラメータとして含めてください。

成功した場合、以下の構造を持つJSONオブジェクトを返します。

{
  "status": "success",
  "message": "API処理が正常に完了しました。",
  "credits_consumed": 10, // 消費されたクレジット数 (Enterpriseプランは0)
  "credits_remaining": 990, // 残りクレジット数 (Enterpriseプランは上限値)
  "result": {
    "input_date": "YYYY-MM-DD HH:MM", // 入力された日時
    "true_solar_time": "YYYY-MM-DD HH:MM", // 真太陽時
    "spring_date": "YYYY-MM-DD HH:MM", // 節入りの日時
    "year_ganzhi": "干支", // 年柱の干支
    "month_ganzhi": "干支", // 月柱の干支
    "day_ganzhi": "干支", // 日柱の干支
    "time_ganzhi": "干支", // 時柱の干支 (時刻が指定された場合)
    "month_ganzhi_date": "YYYY-MM-DD HH:MM", // 月の干支が変わる日時
    "month_ganzhi_biko": "備考", // 月の干支に関する備考
    "julian_day": 2442323.5, // ユリウス日
    "day_ganzhi_details": {
      // 日干支の詳細情報 (五行、陰陽、蔵干など)
      "gan": "干",
      "zhi": "支",
      "gan_gogyo": "五行",
      "zhi_gogyo": "五行",
      "gan_inyo": "陰陽",
      "zhi_inyo": "陰陽",
      "zogan": [
        { "element": "蔵干", "gogyo": "五行", "inyo": "陰陽", "tukan": "通変星" }
        // ...
      ]
    }
  },
  "transaction_id": "...", // クレジット消費のトランザクションID (Enterprise以外)
  "log_id" => "..." // API利用ログID
}

result オブジェクト内のキーの順序は上記と異なる場合があります。

エラーが発生した場合、以下の構造を持つJSONオブジェクトを返します。

{
  "status": "error",
  "message": "エラーメッセージ"
  // 必要に応じて追加のデバッグ情報が含まれる場合があります
}

主なエラーコードとメッセージ：

API呼び出しごとに API_COST (現在: 10) クレジットが消費されます。Enterpriseプランのユーザーはクレジットを消費しません。

APIを利用するためのサンプルコードです。YOUR_API_KEY をご自身のAPIキーに置き換えてください。

cURL (Bash)

curl -X POST "https://gothbox.com/api/v1/calculate" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "year": 1974,
  "month": 10,
  "day": 3,
  "hour": 12,
  "minute": 0,
  "location": 140.47
}'

PHP

<?php
$apiKey = 'YOUR_API_KEY';
$url = 'https://gothbox.com/api/v1/calculate';
$data = [
    'year' => 1974,
    'month' => 10,
    'day' => 3,
    'hour' => 12,
    'minute' => 0,
    'location' => 140.47
];

$options = [
    'http' => [
        'method' => 'POST',
        'header' => "Content-Type: application/json\r\n" .
                    "Authorization: Bearer " . $apiKey . "\r\n",
        'content' => json_encode($data)
    ]
];

$context  = stream_context_create($options);
$response = file_get_contents($url, false, $context);

if ($response === FALSE) {
    // エラー処理
    echo "APIリクエストに失敗しました。";
} else {
    $result = json_decode($response, true);
    print_r($result);
}
?>

JavaScript (Fetch API)

const apiKey = 'YOUR_API_KEY';
const url = 'https://gothbox.com/api/v1/calculate';
const data = {
    year: 1974,
    month: 10,
    day: 3,
    hour: 12,
    minute: 0,
    location: 140.47
};

fetch(url, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => {
    console.log(data);
})
.catch(error => {
    console.error('APIリクエストエラー:', error);
});

Python

import requests
import json

api_key = 'YOUR_API_KEY';
url = 'https://gothbox.com/api/v1/calculate';
data = {
    'year': 1974,
    'month': 10,
    'day': 3,
    'hour': 12,
    'minute': 0,
    'location': 140.47
}

headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {api_key}'
}

response = requests.post(url, headers=headers, data=json.dumps(data))

if response.status_code == 200:
    result = response.json()
    print(json.dumps(result, indent=2, ensure_ascii=False))
else:
    print(f"APIリクエストエラー: {response.status_code}")
    print(response.text)

真太陽時は、入力された日時と経度に基づいて計算されます。日本標準時子午線（東経135度）からの経度差により時間が補正されます。

時柱は、真太陽時と日干支に基づいて計算されます。