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)
干支(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
マッチングアプリ向けのリクエストを作成します。ユーザーの好み(年齢、趣味)や位置情報(半径)フィルタリングをサポートします。
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キーはどのように取得できますか? ▼
👉 お問い合わせフォーム、 または 申請フォーム(Google Form) からご連絡ください。 担当者が確認後、1〜2営業日以内にメールでキーを送付いたします。
7. Support
お困りですか?
APIの導入や、占いサービスの開発に関するご相談はメールにて承ります。
日本語での対応が可能です。