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)に基づいて、
万勢暦(四柱推命)、五行、格局、用神、大運、および様々な運勢要素を精密に計算して返します。
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=大阪
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_score、strength_thresholds、strength_components で根拠を可視化します。
格局 (geokguk)
geok_detail、柱別カテゴリ集計、follower/variant シグナルを含む拡張オブジェクトです。
用神・喜神 (yongshin)
命式バランスを調整する主要/副次の五行情報です。
地支関係 (branch_relations)
合・冲・刑・害に加え、half_three_harmonies、banghap、tam_hap_mang_chung まで提供します。
距離/ポリシー
branch_relations_distance と branch_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
マッチングアプリ向けのリクエストを作成します。ユーザーの好み(年齢、趣味)や位置情報(半径)フィルタリングをサポートします。
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 を基準に以下の基本制限が適用されます。
⚠️ 制限超過時の処理 (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の導入や、占いサービスの開発に関するご相談はメールにて承ります。
日本語での対応が可能です。