四柱推命・運勢APIドキュメント

API製品紹介 v5.0・日本語PDF ↗

製品とキー権限を確認し、認証、リクエスト、レスポンス、Callbackの順にご覧ください。予定仕様と一般呼び出し可能なAPIを区別して連携を進めます。

製品紹介資料は文書v5.0です。実際のAPI URLは既存の/api/v2/を維持します。文書バージョンとAPIバージョンは別です。

万年暦・四柱推命・相性・命名・画像系占いAPIをアプリやWebサービスに連携するための開発者向けドキュメントです。認証、リクエストパラメータ、JSONレスポンス、v2 add-on API、callback flow、error code、rate limit、APIキー発行手順を案内します。

可用性、サポート時間、障害対応の範囲は、契約ごとのSLAで定めます。

クイックスタート

最初のAPI呼び出しを確認する

サーバー側で管理するAPIキーを準備し、基本の万年暦endpointをGETで呼び出します。相性、命名、年運、愛情運、財運のような生成時間が必要な分析はPOST + callbackで連携します。

基本の万年暦照会

curl -X GET \
  "https://api.ablecity.kr/api/v2/saju/fortune?birth=1990-01-01T01:00:00&gender=male&city=Seoul&calendar=solar&midnightType=0" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Accept: application/json"

1. 認証

すべてのリクエストはHTTP headerにBearer tokenを含める必要があります。APIキーはサーバー側で管理し、クライアントアプリに埋め込まず、連携担当者が変わる場合はローテーションしてください。

Authorization: Bearer <API_KEY>

2. 共通レスポンス形式

すべてのendpointはREST JSON envelopeを返します。エラー時も同じtop-level構造を維持するため、クライアント側で成功・失敗を一貫して処理できます。

{
  "status": "success",
  "message": "Request completed.",
  "data": {}
}

3. 運用基準

Ablecity APIは単発計算だけでなく、実サービス連携を前提に設計されています。認証、使用量管理、課金範囲、モニタリング、SLAオプションを導入時にまとめて整理します。

生年月日、性別、任意の出生地、子時処理方式、暦種別を基に、公開v2万年暦payloadを計算します。公開フィールドには四柱命式、五行、運勢cycle、干支相性、空亡、承認済みキーで利用可能なSIS関連構造が含まれます。

以下はv5.0基準の商品データ範囲です。万年暦Core（四柱推命計算データ）は命式・五行・通変星・十二運・大運などの計算データを返します。専門万年暦＋SISはCore全項目に身強弱・格局・用神・地支関係・空亡と54種類の神殺の位置・状態・影響度を追加します。 既存のお客様は、現在の契約と新製品のデータを比較したうえで個別に移行をご案内します。既存Core契約の専門分析項目は、新しいCoreに含まれる項目と区別して確認します。

両製品は既存のGET /api/v2/saju/fortuneを共用し、APIキーの権限で提供範囲を区分します。以下の統合フィールド・応答例は承認済み権限に対応する構造であり、Coreにすべての専門項目が含まれることを意味しません。SISの相対強度は統計的確率ではなく内部指標です。

コード例

curl -X GET \
  "https://api.ablecity.kr/api/v2/saju/fortune?birth=1990-01-01T01:00:00&gender=male&city=Seoul&calendar=solar&midnightType=0" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Accept: application/json"

import requests

url = "https://api.ablecity.kr/api/v2/saju/fortune"
params = {
    "birth": "1990-01-01T01:00:00",
    "gender": "male",
    "city": "Seoul",
    "calendar": "solar",
    "midnightType": 0,
}
headers = {"Authorization": "Bearer <API_KEY>"}
print(requests.get(url, params=params, headers=headers).json())

const axios = require("axios");

const res = await axios.get("https://api.ablecity.kr/api/v2/saju/fortune", {
  params: {
    birth: "1990-01-01T01:00:00",
    gender: "male",
    city: "Seoul",
    calendar: "solar",
    midnightType: 0
  },
  headers: { Authorization: "Bearer <API_KEY>" }
});
console.log(res.data);

OkHttpClient client = new OkHttpClient();

HttpUrl url = HttpUrl.parse("https://api.ablecity.kr/api/v2/saju/fortune").newBuilder()
    .addQueryParameter("birth", "1990-01-01T01:00:00")
    .addQueryParameter("gender", "male")
    .addQueryParameter("city", "Seoul")
    .addQueryParameter("calendar", "solar")
    .addQueryParameter("midnightType", "0")
    .build();

Request request = new Request.Builder()
    .url(url)
    .addHeader("Authorization", "Bearer <API_KEY>")
    .build();

クエリパラメータ

5. 公開レスポンスフィールド

レスポンスは連携向け公開フィールドを返します。内部score logic、private rule table、debug fieldは公開文書に含めません。

{
  "status": "success",
  "message": "Request completed.",
  "data": {
    "saju": {
      "year": { "heaven": "庚", "earth": "午" },
      "month": { "heaven": "戊", "earth": "子" },
      "day": { "heaven": "丙", "earth": "寅" },
      "hour": { "heaven": "己", "earth": "丑" }
    },
    "five_elements": { "wood": 2, "fire": 2, "earth": 2, "metal": 1, "water": 1 },
    "ten_gods": [],
    "daeun": [],
    "gongmang": [],
    "zodiac_compat": [],
    "sinsal": []
  }
}

6. v2 add-ons と分析API

基本の万年暦照会に加えて、v2は日運、luck-flow、詳細分析モジュールを提供します。fortune/request-analysis/ 配下のendpointはPOST + callback方式です。

9. エラーコード

10. レート制限

本番サービスを安定させるため、発行されたAPIキー単位でリクエスト量を制限します。より高い上限は事業規模と契約範囲に応じて相談できます。

以下の呼び出し頻度制限とSandboxの総利用枠は別です。製品と上限は発行キーの承認範囲に従います。

11. FAQ

12. サポート

連携前の問い合わせはメールでご連絡ください。キー発行後はAPI Dashboardで使用量、サブスクリプション、API照会を確認できます。

連携前に確認する運用条件

想定呼び出し量、応答フィールド、エラー処理をサンプルで確認し、Callback受信・重複処理・再試行を検討します。キー権限、支援時間、障害対応、データ保存・削除、バージョン変更通知は技術検討と契約で定義します。