Ablecity 로고
2026.02.13 v2.4 Updated

🔗 Ablecity 万勢暦・四柱推命 API Reference

AI占い、マッチング、レンタルプラットフォーム向けREST APIガイドです。
SLA 99.99%300ms未満のレイテンシを保証するインフラ上で、 サービスを迅速に立ち上げられます。

1. 認証 (Authentication)

すべてのAPIリクエストには、HTTPヘッダーに Bearer Token を含める必要があります。

Authorization: Bearer <API_KEY>

APIキーは、上段の「APIキー発行申請」ボタン、またはお問い合わせフォームから申請してください。

⚡ 性能とベンチマーク

Ablecityは単なる占い計算ツールではありません。グローバルサービス(SaaS, Game, App)を支えるために設計された エンタープライズ級のインフラを提供します。

Metrics (指標) Legacy Competitor (他社) Ablecity (Global Std)
Global Latency (遅延) 1,200ms ~ 2,500ms 180ms ~ 350ms [P90]
Max Concurrency (TPS) ~ 50 TPS (制限あり) 30,000+ TPS
Astronomical Precision (精度) 平均太陽時 (KST固定) GPS基盤 真太陽時補正
SLA (可用性保証) None (Best Effort) 99.99% Guaranteed

2. 共通レスポンス形式

{
  "status": "success",   // or "error"
  "data": ... ,          // 結果データ
  "message": "..."       // 説明メッセージ
}

3. Endpoints Overview

3.1 GET /api/v1/saju/fortune

Best Seller

ユーザーの生年月日・出生時間(birth)、性別(gender)、 出生都市(city)に基づいて、 万勢暦(四柱推命)、五行、格局、用神、大運、および様々な運勢要素を精密に計算して返します。

GET Request Example
curl -X GET \
"https://api.ablecity.kr/api/v1/saju/fortune?birth=1990-01-01T14:30:00&gender=male&city=東京&midnightType=0" \
-H "Authorization: Bearer <API_KEY>" \
-H "Accept: application/json"

* midnightType(0:夜子時/朝子時分離)と calendar(solar:陽暦)は、未入力時にデフォルト値が適用されます。

Query Parameters

Name Type Required Description
birth string Yes 生年月日と時間。yyyy-MM-ddTHH:mm:ss 形式のみ対応。
(例: 1990-01-01T14:30:00 - 時間区切り文字 'T' 必須)
gender string Yes 性別。男性: male, 女性: female (それ以外の値はエラー)
city string Optional 出生都市 (真太陽時補正用)。未入力時は東京(Tokyo)基準。
対応都市は下段リストを参照してください。
midnightType integer Optional 0: 夜子時/朝子時 分離 (デフォルト, 日本標準)
1: 正子時方式 (23:00~00:59をすべて翌日として処理)
calendar string Optional solar(陽暦, デフォルト), lunar(陰暦), leap(閏月)
📍 対応都市リスト (city) - 日本国内主要都市

使用例: city=東京 または city=大阪

東京 (Tokyo) 大阪 (Osaka) 京都 (Kyoto) 札幌 (Sapporo) 横浜 (Yokohama) 名古屋 (Nagoya) 神戸 (Kobe) 福岡 (Fukuoka) 千葉 (Chiba) 広島 (Hiroshima) 仙台 (Sendai) 新潟 (Niigata) 長野 (Nagano) 静岡 (Shizuoka) 金沢 (Kanazawa) 松山 (Matsuyama) 熊本 (Kumamoto) 宮崎 (Miyazaki) 鹿児島 (Kagoshima) 沖縄 (Okinawa) 福島 (Fukushima) 青森 (Aomori)

Response Example

{
  "status": "success",
  "message": "リクエストが完了しました。",
  "data": {
    "year": {
      "branch_sipseong": "正財",
      "stem_sipseong": "正印",
      "hangul": "무인",
      "hanja": "戊寅"
    },
    "month": {
      "branch_sipseong": "正財",
      "stem_sipseong": "正財",
      "hangul": "갑인",
      "hanja": "甲寅"
    },
    "day": {
      "branch_sipseong": "傷官",
      "stem_sipseong": "比肩",
      "hangul": "신해",
      "hanja": "辛亥"
    },
    "hour": {
      "branch_sipseong": "食神",
      "stem_sipseong": "正印",
      "hangul": "무자",
      "hanja": "戊子"
    },
    "fortune": 9,
    "five": {
      "earth": 2.59,
      "metal": 0.97,
      "fire": 0.66,
      "wood": 6.14,
      "water": 2.90
    },
    "five_pct": {
      "earth": 19.5,
      "metal": 7.3,
      "fire": 5.0,
      "wood": 46.3,
      "water": 21.9
    },
    "five_star": {
      "earth": "★★☆☆☆",
      "metal": "★☆☆☆☆",
      "fire": "★☆☆☆☆",
      "wood": "★★★★★",
      "water": "★★★☆☆"
    },
    "twelve_growth": {
      "year": "胎",
      "month": "胎",
      "day": "沐浴",
      "hour": "長生"
    },
    "strength": "weak",
    "geokguk": {
      "geok_jp": "従財格",
      "geok": "從財格",
      "share": 50.0,
      "is_follower": true
    },
    "yongshin": {
      "primary": "fire",
      "primary_jp": "火",
      "secondary": "earth",
      "secondary_jp": "土"
    },
    "branch_relations": {
      "harmonies": ["寅-亥 (支合)", "寅-亥 (支合)"],
      "breaks": [],
      "clashes": []
    },
    "big_luck": [
      { "age_range": "9–18",  "year_range": "2007–2016", "pillar": "癸丑", "pillar_jp": "癸丑" },
      { "age_range": "19–28", "year_range": "2017–2026", "pillar": "壬子", "pillar_jp": "壬子" },
      { "age_range": "29–38", "year_range": "2027–2036", "pillar": "辛亥", "pillar_jp": "辛亥" }
    ],
    "lucky": {
      "good_num": 2,
      "bad_num": 7,
      "good_dir": "西",
      "bad_dir": "東",
      "need_elem_jp": "火",
      "need_elem": "fire",
      "good_colors": ["bg-red-300", "bg-orange-300"],
      "bad_color": "bg-gray-300"
    }
  }
}

主要フィールド説明 (Field Description)

四柱 (year, month, day, hour)

干支(Hanja/Hangul)および通変星マッピングを含む中核データです。

五行分布 (five)

絶対値、比率、星評価、ローカライズ済みキーを提供します。

合化分析 (hehua)

true / pseudo / failed 判定、適用フラグ、合化前後の五行・用神変化を返します。

十二運 (twelve_growth)

各柱の十二運状態を多言語ラベルで提供します。

日干強弱 (strength)

strength_scorestrength_thresholdsstrength_components で根拠を可視化します。

格局 (geokguk)

geok_detail、柱別カテゴリ集計、follower/variant シグナルを含む拡張オブジェクトです。

用神・喜神 (yongshin)

命式バランスを調整する主要/副次の五行情報です。

地支関係 (branch_relations)

合・冲・刑・害に加え、half_three_harmoniesbanghaptam_hap_mang_chung まで提供します。

距離/ポリシー

branch_relations_distancebranch_relations_policy で関係強度ロジックを確認できます。

分析フロー (analysis_flow)

エンジン内部の計算順序を配列で返し、検証・デバッグに活用できます。

大運 (big_luck)

10年単位の運勢配列 (年齢帯 / 年度帯) を返します。

開運要素 (lucky)

吉数・吉方位・推奨色 (CSSトークン含む) を返します。

🆕 新規レスポンス項目 (Advanced Analysis)

Field Type Description
hehua Object 六合合化の判定結果。候補群、適用フラグ、補正量、合化前後の比較を含みます。
branch_relations_distance Object 関係別に near / mid / far / avg_factor を返します。
branch_relations_policy Object 関係スコア化ポリシー (core / aux / school_specific) を返します。
analysis_flow Array<String> 内部計算フロー追跡配列です。
strength_* Number / Object 日干強弱判定の定量根拠を提供します。
geokguk (expanded) Object 格局の詳細と柱別カテゴリ集計を含む拡張項目です。
sinsal Array<Object> 適用された神殺(最大56種)の詳細リストを返します。

3.1-A テーマ別運勢・精密分析 (Add-ons)

基本命式に加え、テーマ別運勢、詳細リーディング、AI Vision 拡張向けエンドポイントを提供します。
同期 GET非同期 POST + Callback の2方式に分かれます。

  • GET 同期処理: リクエスト応答で即時に結果を返します。
  • POST 非同期処理: 処理後に X-Callback-URL へ結果を送信します。

🔗 エンドポイント一覧

Method Endpoint Path Description
GET /api/v1/saju/fortune/daily 今日の運勢
GET /api/v1/saju/fortune/zodiac-luck 今日の干支運勢
POST /api/v1/saju/fortune/request-analysis/match 相性分析 (Callback 必須)
POST /api/v1/saju/fortune/request-analysis/week-luck 週間運勢 (Callback 必須)
POST /api/v1/saju/fortune/request-analysis/this-year-luck 年運 (Callback 必須)
POST /api/v1/saju/fortune/request-analysis/love-luck 恋愛運 (Callback 必須)
POST /api/v1/saju/fortune/request-analysis/rich-luck 金運分析 (Callback 必須)
POST /api/v1/saju/fortune/request-analysis/telling 四柱推命リーディング (Callback 必須)

Request Example (POST / Callback)

* 非同期分析(POST)では X-Callback-URL ヘッダーが必須です。

curl -X POST \
"https://api.ablecity.kr/api/v1/saju/fortune/request-analysis/rich-luck" \
-H "Authorization: Bearer <API_KEY>" \
-H "X-Callback-URL: https://your-server.com/webhook/result" \
-H "Content-Type: application/json" \
-d '{
  "birth": "1990-01-01T00:00:00",
  "gender": "male",
  "city": "東京",
  "calendar": "solar",
  "midnightType": 0
}'

3.2 POST /api/v1/matching

マッチングアプリ向けのリクエストを作成します。ユーザーの好み(年齢、趣味)や位置情報(半径)フィルタリングをサポートします。

POST /api/v1/matching

Request Example

curl -X POST https://api.ablecity.kr/v1/matching \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "userId": "USER123",
  "preferences": {
    "ageRange": [25, 35],
    "interests": ["travel", "music"],
    "location": { "lat": 35.6895, "lng": 139.6917, "radiusKm": 10 }
  },
  "maxResults": 10
}'

3.6 ~ 3.9 OTC & Rental API

取引所(OTC)およびレンタルプラットフォーム構築のためのAPIセットです。
※ 詳細な仕様書が必要な場合は、お問い合わせください。

4. Error Codes (エラーコード)

HTTP Status Code Description
400 INVALID_REQUEST 不正なリクエストです (パラメータ不足など)。
401 UNAUTHORIZED 認証失敗、またはAPIキーの有効期限切れ。
404 NOT_FOUND リソースが見つかりません。
429 RATE_LIMIT リクエスト制限数を超過しました。
500 SERVER_ERROR サーバー内部エラー。管理者にお問い合わせください。

4.1 共通 message 値

  • 요청이 완료되었습니다. – リクエスト成功 (Success)。
  • 서버 처리 중 오류가 발생했습니다. – サーバー処理中のエラー。ログ確認が必要です。
  • 서비스를 찾을 수 없습니다. – サポートされていないサービス(URL)を呼び出した場合。

4.2 認証 / Rate Limit 関連 message

  • 유효하지 않은 API Key입니다.
    API Keyが無効、削除済み、またはヘッダーに含まれていない場合。
  • 허용된 전체 분당 요청 횟수가 초과되었습니다.
    1分あたりのリクエスト許容数を超過しました。
  • 허용된 전체 일일 요청 횟수가 초과되었습니다.
    1日あたりのリクエスト許容数を超過しました。
  • 허용되지 않은 서비스입니다.
    リクエストしたサービス(URI)が、現在のAPI Keyプランに含まれていません。
  • 서비스가 일시적으로 불안정합니다. 잠시 후 다시 시도해주세요.
    Redis等の内部エラーにより一時的にサービスが不安定です。再試行してください。

4.3 四柱推命 API 専用 message

  • ℹ️ invalid birth date format
    birth 形式エラー。yyyy-MM-dd HH:mm:ss 形式のみ許可されます。
  • ℹ️ gender must be 'male' or 'female'
    gender 値が male または female ではありません。
  • ℹ️ invalid timezone
    出生地のタイムゾーンエラー。IANA tzデータベース基準で検証されます。

5. Rate Limiting (制限)

安定したサービス提供のため、API呼び出し頻度を制限しています。 すべてのエンドポイントには、発行された API Key を基準に以下の基本制限が適用されます。

Per Minute 分間制限
60 requests
Per Day 一日制限
50,000 requests

⚠️ 制限超過時の処理 (Throttling)

サービス別または全体制限を超過すると、HTTP Status 429 (Too Many Requests) とともに Rate Limit 関連の message が返されます。

ビジネス規模に応じてより高い制限が必要な場合は、 サポート ([email protected]) まで制限緩和を申請してください。

6. FAQ (よくある質問)

APIの利用料金はどうなっていますか?

テスト呼び出しは100件まで無料です。その後はサブスクリプション形態により(1件あたり約1円〜10円程度)の料金が適用されます。 詳細な見積もりはお問い合わせください。

一日の呼び出し制限 (Rate Limit) はありますか?

すべてのエンドポイントは基本的に 分間60件、一日50,000件 に制限されています。 大規模なトラフィックが予想される場合は、事前にご相談いただければ上限の引き上げが可能です。

どのプログラミング言語で使用できますか?

標準的な RESTful JSON レスポンスを提供するため、 Python, JavaScript (Node.js), Java, PHP, Go, Rubyなど、 HTTPクライアントをサポートする すべての言語およびプラットフォーム で使用可能です。

エラー発生時の再試行 (Retry) ポリシーは?

429 (Too Many Requests) または 5xx エラーが発生した場合、 指数バックオフ (Exponential Backoff) 方式(例: 1秒 → 2秒 → 4秒)で 最大3回まで再試行することを推奨します。

無料体験用のAPIキーはどのように取得できますか?

👉 APIキー申請フォーム からお申し込みください。 内容確認後、通常 1〜2 営業日以内にメールでご案内します。

7. Support

お困りですか?

APIの導入や、占いサービスの開発に関するご相談はメールにて承ります。
日本語での対応が可能です。

✉️ [email protected]