Ablecity 로고
2026.01.09 v2.2 Updated

🔗 Ablecity 四柱推命・万勢暦・マッチング API

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)

干支(Ganji)および通変星(branch/stem sipseong)情報を含みます。

五行分布 (five)

五行の絶対値、パーセンテージ、星評価(star)、不足要素の分析データ。

十二運 (twelve_growth)

各柱ごとの十二運の状態(長生、沐浴、胎、養など)を提供。

日干の強弱 (strength)

身強(strong) / 身弱(weak) / 中和(balanced) の判定結果。

格局 (geokguk)

格局の名称(内格/外格)および勢力のシェア率(share)。

用神・喜神 (yongshin)

四柱のバランスを整える核心となる五行情報 (Primary/Secondary)。

地支関係 (branch_relations)

支合、冲、刑、破、害など地支間の相互作用分析。

大運 (big_luck)

10年単位の運勢の流れ配列 (年齢/年度区間を含む)。

開運要素 (lucky)

ラッキーナンバー、吉方位、ラッキーカラー(CSSコード含む)、不足五行。

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キーはどのように取得できますか?

👉 お問い合わせフォーム、 または 申請フォーム(Google Form) からご連絡ください。 担当者が確認後、1〜2営業日以内にメールでキーを送付いたします。

7. Support

お困りですか?

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

✉️ [email protected]