Ablecity 万年暦・四柱推命 API Reference

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

内部運用、テストキー発行、パートナー環境を基準にした表記です。Ablecity APIは2025年12月ローンチ以降、APIレベルの無停止運用を継続しています。正式なSLAは契約範囲ごとに定義し、公開文書では内部判断ロジックではなく連携に必要な契約仕様のみを案内します。

クイックスタート

5分で最初の呼び出しを成功させる

サーバー側で管理する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関連構造が含まれます。

コード例

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キー単位でリクエスト量を制限します。より高い上限は事業規模と契約範囲に応じて相談できます。

11. FAQ

12. サポート

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