← 回首頁 English

AstroChart API 文件BETA

占星星盤運算 API — 本命盤、合盤、行運、推運、太陽回歸、組合盤

總覽

Base URL 為 同源（same-origin）：所有路徑皆為相對路徑（例如 /api/v1/charts），直接對本站發送請求即可。

本 API 目前為 Beta、開放測試（open beta）狀態：

• 無需 API 金鑰、無需註冊即可呼叫（伺服器目前為 API_KEY_MODE=open）
• 無限流（rate limit）
• 免費使用

所有請求與回應皆為 JSON（Content-Type: application/json）。所有 /api 回應皆帶有 Access-Control-Allow-Origin: *，可直接從瀏覽器跨域呼叫；OPTIONS /api/v1/* 預檢請求回傳 204，並帶 Access-Control-Allow-Methods: POST,GET,OPTIONS 與 Access-Control-Allow-Headers: Content-Type, Authorization, X-API-Key。

機器可讀的完整規格見 /openapi.json（OpenAPI 3.1）。

出生資料物件（共用格式）

以下所有需要出生資料的端點（/charts 本身、/synastry 的 a/b、/transits・/progressions・/solar-return 的 natal、/composite 的 a/b）都使用同一組欄位與驗證規則：

多語言（lang 參數）

API 回應預設使用繁體中文（zh-TW）詞彙。所有起盤端點（/charts、/synastry、/transits、/progressions、/composite、/solar-return）接受選填的請求主體欄位 lang；GET /api/v1/cities 接受查詢參數 ?lang=。/api/v1/health 無語言參數。

接受的值

其他任何值（含空字串 ""）回 400 invalid_lang，且此錯誤訊息固定為 zh-TW。

翻譯範圍

lang 只翻譯「詞彙值」，不改變任何 JSON 結構：

• 會翻譯 — 詞彙值：planet、a_planet、b_planet、transit_planet、natal_planet、progressed_planet、planet_a、planet_b、apex、ruling_planet、zodiac、aspect_type、pattern_type、element 欄位的值，以及 patterns[].planets 陣列中的星體名稱
• 會翻譯 — 詞彙鍵：a_planets_in_b_houses／b_planets_in_a_houses 的行星名稱鍵，與 element_stats.elements／element_stats.modalities 的元素／模式鍵（宮號、計數等「值」不變）
• 會翻譯 — 錯誤訊息：error.message 依請求的 lang 在地化
• 會翻譯 — 城市：/cities 帶 lang=en／ja／ko 時，name 與 country 改為英文名（不提供日文／韓文城市名）
• 不翻譯：JSON 結構鍵本身（planet、zodiac 等 key 名稱）、input 回聲區塊（原樣回傳）、所有數字、house_system 的 "P"／"W"、錯誤 code 值（語言無關 — 程式邏輯請一律以 code 判斷）

範例：lang: "ja"

請求範例

{
  "birth_date": "1990-01-01",
  "birth_time": "12:00",
  "latitude": 25.033,
  "longitude": 121.5654,
  "timezone": "Asia/Taipei",
  "lang": "ja"
}

回應 200（實際輸出，節錄）

{
  "data": {
    "input": { /* 原樣回傳，不翻譯 */ },
    "chart": {
      "ascendant": { "zodiac": "牡羊座", "degree": 16.4422, "total_degree": 16.4422 },
      "house_system": "P",
      "planets": [
        { "planet": "太陽", "zodiac": "山羊座", "house": 9, "degree": 10.4744, "total_degree": 280.4744, "retrograde": false,
          "aspects": [
            { "planet": "木星", "aspect_type": "オポジション", "orb": 5.28 },
            { "planet": "土星", "aspect_type": "コンジャンクション", "orb": 5.14 }
            // …其餘 2 筆省略
          ] },
        { "planet": "月", "zodiac": "水瓶座", "house": 11, "degree": 28.7886, "total_degree": 328.7886, "retrograde": false },
        { "planet": "ドラゴンヘッド", "zodiac": "水瓶座", "house": 11, "degree": 16.863, "total_degree": 316.863, "retrograde": false }
        // …其餘 14 筆省略（結構不變，共 17 筆）
      ],
      "element_stats": {
        "elements":   { "火": 1, "地": 5, "風": 2, "水": 2 },
        "modalities": { "活動": 6, "不動": 3, "柔軟": 1 }
      }
      // …houses／patterns 結構不變
    }
  }
}

驗證與用量（API 金鑰）

API 金鑰讓你把呼叫用量歸戶、設定每月用量上限，並查詢自己的用量。是否強制帶金鑰由伺服器環境變數 API_KEY_MODE 控制：

傳遞金鑰的方式

金鑰長相為 ak_XXXXXXXX…。以下任一種方式擇一即可（優先序：Authorization > X-API-Key > ?api_key=）：

哪些端點會驗證並計入用量（計費端點）

下列端點在 open 模式允許匿名，成功（HTTP 200）時計入用量一次；在 required 模式則必須帶金鑰：

• POST /api/v1/charts、/synastry、/transits、/progressions、/composite、/solar-return
• GET /api/v1/cities

不計入用量：GET /api/v1/health（永遠公開、免金鑰）與 GET /api/v1/usage（需金鑰，但查詢自身用量本身不計費）。

金鑰相關錯誤

查詢用量

查詢目前金鑰當月的用量摘要。此端點一定需要金鑰（即使在 open 模式；匿名用量無從歸戶），且本身不計費、不翻譯（回應無詞彙欄位）。也接受 ?lang=，但只影響錯誤訊息的語言（如 key_required／invalid_api_key），不影響資料內容。

請求範例

curl -s https://your-host/api/v1/usage \
  -H "Authorization: Bearer ak_7hgEJAyQvsuO4zHntkpoMvnvrecJ_6QJ"

回應 200（實際輸出）

{
  "data": {
    "key": {
      "prefix": "ak_7hgEJAyQ",
      "label": "Acme Web App",
      "tier": "free"
    },
    "month": "2026-07",
    "total": 5,
    "monthly_limit": 1000,
    "remaining": 995,
    "by_endpoint": {
      "charts": 2,
      "cities": 2,
      "synastry": 1
    },
    "by_day": {
      "2026-07-25": 5
    }
  }
}

計費端點帶金鑰的呼叫範例

# Authorization: Bearer（本命盤）
curl -s -X POST https://your-host/api/v1/charts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ak_7hgEJAyQvsuO4zHntkpoMvnvrecJ_6QJ" \
  -d '{"birth_date":"1990-01-01","birth_time":"12:00","latitude":25.033,"longitude":121.5654,"timezone":"Asia/Taipei"}'

# X-API-Key 標頭（城市搜尋）
curl -s "https://your-host/api/v1/cities?q=tai" \
  -H "X-API-Key: ak_7hgEJAyQvsuO4zHntkpoMvnvrecJ_6QJ"

# 查詢參數 ?api_key=（城市搜尋）
curl -s "https://your-host/api/v1/cities?q=tokyo&api_key=ak_7hgEJAyQvsuO4zHntkpoMvnvrecJ_6QJ"

自助申請 API 金鑰（Self-serve signup）

不需要管理權杖，任何人都能自助申請一把免費 API 金鑰。流程採雙重確認（double opt-in），分兩步：

1. 申請：POST /api/v1/signup 送出你的 email。系統暫存一筆待確認申請並寄出一封含確認連結的信。此步驟不會回傳金鑰。
2. 確認：點擊信中的連結（指向 GET /verify?token=…），在該頁按下確認鈕，前端即以該 token 呼叫 POST /api/v1/verify，此時才簽發並只顯示一次明文金鑰。

整個流程公開、免費、不計費、免金鑰。金鑰本身也是免費的；email 這一步只是為了確認你對該信箱的擁有權。取得金鑰後如何傳遞、如何查詢用量，見驗證與用量。另有兩個公開 HTML 頁面：GET /signup（申請頁）與 GET /verify（信件連結的到達頁，內含確認鈕）。

步驟一：申請（寄出確認信）

暫存一筆待確認申請並寄出確認連結。公開端點、不計費、免金鑰。防濫用：同一來源 IP（Fly 會設定的 X-Forwarded-For 第一段）每日申請次數達 SIGNUP_DAILY_IP_LIMIT（預設 5）時回 429 signup_rate_limited。

請求欄位

請求範例

{
  "email": "dev@example.com"
}

回應 202（實際輸出）

{
  "data": {
    "status": "verification_sent",
    "email": "dev@example.com"
  }
}

錯誤

步驟二：確認並取得金鑰

以確認信連結中的 token 確認信箱擁有權，成功時簽發並回傳明文金鑰（只回傳這一次）。一般使用者是經由 GET /verify?token=… 頁面按下確認鈕，由該頁前端 POST 此端點；也可直接以程式呼叫。公開端點、不計費、免金鑰。

請求欄位

請求範例

{
  "token": "3f9c1e7a8b2d4f60a1c3e5d7b9f0a2c4"
}

回應 201（實際輸出，明文 token 只回傳這一次）

{
  "data": {
    "token": "ak_7hgEJAyQvsuO4zHntkpoMvnvrecJ_6QJ",
    "prefix": "ak_7hgEJAyQ",
    "monthly_limit": null,
    "tier": "free"
  }
}

錯誤

健康檢查

確認服務狀態與底層 astro_chart gem 版本。

回應 200

{"status":"ok","gem_version":"0.3.0"}

本命盤

依出生資料計算完整本命盤：上升點、行星位置（含逆行標記、福點、莉莉絲）、宮位（Placidus 或整宮制）、相位、相位圖形（大三角／T三角／大十字）、元素統計。

請求欄位

即為一個出生資料物件（5 個必填欄位 + 選填 house_system）。

請求範例

{
  "birth_date": "1990-01-01",
  "birth_time": "12:00",
  "latitude": 25.033,
  "longitude": 121.5654,
  "timezone": "Asia/Taipei",
  "house_system": "P"
}

回應 200（實際輸出，planets／houses 節錄）

{
  "data": {
    "input": {
      "birth_date": "1990-01-01",
      "birth_time": "12:00",
      "coordinates": { "latitude": 25.033, "longitude": 121.5654 },
      "timezone": "Asia/Taipei"
    },
    "chart": {
      "ascendant": { "zodiac": "牡羊座", "degree": 16.4422, "total_degree": 16.4422 },
      "house_system": "P",
      "planets": [
        {
          "planet": "太陽",
          "zodiac": "摩羯座",
          "house": 9,
          "degree": 10.4744,
          "total_degree": 280.4744,
          "retrograde": false,
          "aspects": [
            { "planet": "木星", "aspect_type": "對分相", "orb": 5.28 },
            { "planet": "土星", "aspect_type": "合相", "orb": 5.14 },
            { "planet": "天王星", "aspect_type": "合相", "orb": 4.71 },
            { "planet": "海王星", "aspect_type": "合相", "orb": 1.55 }
          ]
        },
        {
          "planet": "水星",
          "zodiac": "摩羯座",
          "house": 10,
          "degree": 25.76,
          "total_degree": 295.76,
          "retrograde": true
        },
        // …月亮、金星、火星、木星、土星、天王星、海王星、冥王星、
        //   北交點、南交點省略（12 個實體星體／交點）
        {
          "planet": "福點",
          "zodiac": "雙子座",
          "house": 2,
          "degree": 4.7564,
          "total_degree": 64.7564,
          "retrograde": false
        },
        {
          "planet": "莉莉絲",
          "zodiac": "天蠍座",
          "house": 7,
          "degree": 6.4703,
          "total_degree": 216.4703,
          "retrograde": false
        },
        {
          "planet": "北交點定位星",
          "ruling_planet": "天王星",
          "zodiac": "摩羯座",
          "house": 9,
          "degree": 5.7656,
          "total_degree": 275.7656,
          "aspects": [
            { "planet": "太陽", "aspect_type": "合相", "orb": 4.71 },
            { "planet": "木星", "aspect_type": "對分相", "orb": 0.57 }
            // …其餘 2 筆省略
          ],
          "retrograde": false
        }
        // …南交點定位星、上升星座定位星省略（planets 共 17 筆，見「回應欄位說明」）
      ],
      "houses": [
        { "house_number": 1, "degree": 16.4422, "zodiac": "牡羊座" },
        { "house_number": 2, "degree": 50.317, "zodiac": "金牛座" }
        // …其餘 10 筆省略，共 12 宮
      ],
      "patterns": [],
      "element_stats": {
        "elements":   { "火": 1, "土": 5, "風": 2, "水": 2 },
        "modalities": { "基本": 6, "固定": 3, "變動": 1 }
      }
    }
  }
}

整宮制（Whole Sign）

帶 "house_system": "W" 時，宮首固定落在每個星座 0°（第 1 宮 = 上升星座的 0°），ascendant 本身與 Placidus 完全相同。實際輸出節錄（同一筆出生資料）：

{
  "chart": {
    "ascendant": { "zodiac": "牡羊座", "degree": 16.4422, "total_degree": 16.4422 },
    "house_system": "W",
    "houses": [
      { "house_number": 1, "degree": 0.0,  "zodiac": "牡羊座" },
      { "house_number": 2, "degree": 30.0, "zodiac": "金牛座" },
      { "house_number": 3, "degree": 60.0, "zodiac": "雙子座" }
      // …其餘 9 筆省略，每宮 +30°
    ]
    // …planets／patterns／element_stats 結構相同（行星宮位依整宮制重新歸宮）
  }
}

相位圖形範例

patterns 多數星盤為空陣列；以 1999-08-11（著名的日食大十字）為例，實際輸出：

"patterns": [
  { "pattern_type": "T三角", "planets": ["水星", "海王星", "木星"], "apex": "木星" },
  { "pattern_type": "大十字", "planets": ["天王星", "太陽", "土星", "火星"] },
  { "pattern_type": "大十字", "planets": ["南交點", "太陽", "土星", "火星"] }
  // …共 5 組大十字，此處省略 3 組
]

合盤（Synastry）

計算兩人的本命盤，以及兩張盤之間的相位與「A 的行星落入 B 的宮位」對照。

請求欄位

請求範例

{
  "a": {
    "birth_date": "1990-01-01",
    "birth_time": "12:00",
    "latitude": 25.033,
    "longitude": 121.5654,
    "timezone": "Asia/Taipei"
  },
  "b": {
    "birth_date": "1992-06-15",
    "birth_time": "08:30",
    "latitude": 25.033,
    "longitude": 121.5654,
    "timezone": "Asia/Taipei"
  },
  "orb_limit": 6.0
}

回應 200（實際輸出，節錄）

{
  "data": {
    "a_chart": { /* A 的完整本命盤，結構同 /api/v1/charts 的 data */ },
    "b_chart": { /* B 的完整本命盤 */ },
    "synastry": {
      "aspects": [
        { "a_planet": "冥王星", "b_planet": "天王星", "aspect_type": "六分相", "orb": 0.16 },
        { "a_planet": "太陽", "b_planet": "水星", "aspect_type": "對分相", "orb": 0.19 },
        { "a_planet": "冥王星", "b_planet": "海王星", "aspect_type": "六分相", "orb": 1.13 }
        // …其餘筆數省略；一律依 orb 由小到大排序
      ],
      "a_planets_in_b_houses": {
        "太陽": 6, "月亮": 7, "水星": 6, "金星": 6, "火星": 5, "木星": 11,
        "土星": 6, "天王星": 5, "海王星": 6, "冥王星": 4, "北交點": 7
      },
      "b_planets_in_a_houses": {
        "太陽": 3, "月亮": 9, "水星": 3, "金星": 3, "火星": 1, "木星": 5,
        "土星": 11, "天王星": 10, "海王星": 10, "冥王星": 8, "北交點": 9
      }
    }
  }
}

行運（Transits）

計算某一時刻（預設為「現在」）天上行星的位置、其落入本命盤的宮位，以及行運行星對本命行星的相位。

請求欄位

* 僅在有提供 at 物件時必填。

請求範例

{
  "natal": {
    "birth_date": "1990-01-01",
    "birth_time": "12:00",
    "latitude": 25.033,
    "longitude": 121.5654,
    "timezone": "Asia/Taipei"
  },
  "at": { "date": "2026-07-24", "time": "12:00", "timezone": "Asia/Taipei" },
  "orb_limit": 3
}

回應 200（實際輸出，節錄）

{
  "data": {
    "natal_chart": { /* 完整本命盤，結構同 /api/v1/charts 的 data */ },
    "transit_time_utc": "2026-07-24T04:00:00Z",
    "planets": [
      {
        "planet": "太陽",
        "zodiac": "獅子座",
        "degree": 1.3043,
        "total_degree": 121.3043,
        "natal_house": 4
      },
      {
        "planet": "月亮",
        "zodiac": "射手座",
        "degree": 1.4324,
        "total_degree": 241.4324,
        "natal_house": 8
      }
      // …其餘 10 筆省略，共 12 筆（太陽～冥王星＋北交點＋南交點）
    ],
    "aspects": [
      { "transit_planet": "金星", "natal_planet": "土星", "aspect_type": "三分相", "orb": 0.18 },
      { "transit_planet": "水星", "natal_planet": "土星", "aspect_type": "對分相", "orb": 0.7 },
      { "transit_planet": "水星", "natal_planet": "冥王星", "aspect_type": "三分相", "orb": 0.77 },
      { "transit_planet": "海王星", "natal_planet": "木星", "aspect_type": "四分相", "orb": 0.85 }
      // …其餘筆數省略；依 orb 由小到大排序
    ]
  }
}

二次推運（Secondary Progressions）

「一天推一年」：目標日期距出生每滿一年，推運盤即取出生後一天的天象。回傳推運行星位置（落入本命宮位）與推運行星對本命行星的相位。

請求欄位

請求範例

{
  "natal": {
    "birth_date": "1990-01-01",
    "birth_time": "12:00",
    "latitude": 25.033,
    "longitude": 121.5654,
    "timezone": "Asia/Taipei"
  },
  "target_date": "2026-07-24",
  "orb_limit": 1
}

回應 200（實際輸出，節錄）

{
  "data": {
    "natal_chart": { /* 完整本命盤，結構同 /api/v1/charts 的 data */ },
    "progression": {
      "progressed_jd": 2447929.2259389306,
      "years_elapsed": 36.56,
      "planets": [
        {
          "planet": "太陽",
          "zodiac": "水瓶座",
          "degree": 17.6684,
          "total_degree": 317.6684,
          "natal_house": 11
        }
        // …其餘 11 筆省略，共 12 筆（結構同行運的 planets）
      ],
      "aspects_to_natal": [
        { "progressed_planet": "火星", "natal_planet": "天王星", "aspect_type": "合相", "orb": 0.11 },
        { "progressed_planet": "北交點", "natal_planet": "北交點", "aspect_type": "合相", "orb": 0.37 },
        { "progressed_planet": "太陽", "natal_planet": "冥王星", "aspect_type": "四分相", "orb": 0.58 }
        // …其餘筆數省略；依 orb 由小到大排序
      ]
    }
  }
}

太陽回歸（Solar Return）

找出指定年份中「行運太陽回到本命太陽經度」的精確時刻（牛頓迭代，精度約 10 秒內），並以該時刻起一張完整的回歸盤。可選擇改用其他地點（回歸移置）。

請求欄位

請求範例

{
  "natal": {
    "birth_date": "1990-01-01",
    "birth_time": "12:00",
    "latitude": 25.033,
    "longitude": 121.5654,
    "timezone": "Asia/Taipei"
  },
  "year": 2026
}

回應 200（實際輸出，節錄）

{
  "data": {
    "natal_chart": { /* 完整本命盤，結構同 /api/v1/charts 的 data */ },
    "solar_return": {
      "return_jd": 2461041.407478858,
      "return_time_utc": "2025-12-31T21:46:46Z",
      "location": {
        "latitude": 25.033,
        "longitude": 121.5654,
        "timezone": "Asia/Taipei"
      },
      "chart": {
        "ascendant": { "zodiac": "射手座", "degree": 27.3962, "total_degree": 267.3962 },
        "planets": [
          {
            "planet": "太陽",
            "zodiac": "摩羯座",
            "house": 1,
            "degree": 10.4744,
            "total_degree": 280.4744,
            "aspects": [
              { "planet": "金星", "aspect_type": "合相", "orb": 1.38 },
              { "planet": "北交點", "aspect_type": "六分相", "orb": 0.5 }
              // …其餘筆數省略
            ]
          }
          // …其餘 14 筆省略（回歸盤 planets 共 15 筆，見下方注意事項）
        ],
        "houses": [ /* 12 筆宮首，結構同本命盤 houses */ ]
      }
    }
  }
}

回歸移置（relocation）

帶 latitude／longitude／timezone 覆寫時，回歸時刻不變（太陽經度與地點無關），但回歸盤的上升點與宮位改以新地點計算。實際輸出節錄：

"solar_return": {
  "return_time_utc": "2025-12-31T21:46:46Z",
  "location": { "latitude": 35.6762, "longitude": 139.6503, "timezone": "Asia/Tokyo" }
  // …chart 改以東京座標起盤
}

組合盤（Composite）

兩張本命盤的中點盤：每個星體取兩盤經度的短弧中點（350° 與 10° 的中點是 0°，不是 180°），再計算中點位置彼此之間的相位。

請求欄位

請求範例

{
  "a": {
    "birth_date": "1990-01-01", "birth_time": "12:00",
    "latitude": 25.033, "longitude": 121.5654, "timezone": "Asia/Taipei"
  },
  "b": {
    "birth_date": "1992-06-15", "birth_time": "08:30",
    "latitude": 25.033, "longitude": 121.5654, "timezone": "Asia/Taipei"
  }
}

回應 200（實際輸出，節錄）

{
  "data": {
    "a_chart": { /* A 的完整本命盤，結構同 /api/v1/charts 的 data */ },
    "b_chart": { /* B 的完整本命盤 */ },
    "composite": {
      "planets": [
        { "planet": "太陽", "zodiac": "牡羊座", "degree": 2.3199, "total_degree": 2.3199 },
        { "planet": "月亮", "zodiac": "摩羯座", "degree": 25.4433, "total_degree": 295.4433 }
        // …其餘 10 筆省略，共 12 筆（太陽～冥王星＋北交點＋南交點）
      ],
      "aspects": [
        { "planet_a": "北交點", "planet_b": "南交點", "aspect_type": "對分相", "orb": 0.0 },
        { "planet_a": "金星", "planet_b": "海王星", "aspect_type": "四分相", "orb": 0.28 },
        { "planet_a": "太陽", "planet_b": "土星", "aspect_type": "六分相", "orb": 0.39 }
        // …其餘筆數省略；依 orb 由小到大排序
      ]
    }
  }
}

城市搜尋

供出生地輸入使用的城市座標／時區查詢。內建約 160 筆城市：台灣全部 22 縣市（縣治座標）＋世界主要城市，支援中文名與英文／拼音別名。

查詢參數

回應 200（GET /api/v1/cities?q=tai 實際輸出）

{
  "data": [
    { "name": "台北市", "country": "台灣", "latitude": 25.033, "longitude": 121.5654, "timezone": "Asia/Taipei" },
    { "name": "台中市", "country": "台灣", "latitude": 24.1477, "longitude": 120.6736, "timezone": "Asia/Taipei" },
    { "name": "台南市", "country": "台灣", "latitude": 22.9999, "longitude": 120.2269, "timezone": "Asia/Taipei" },
    { "name": "嘉義縣", "country": "台灣", "latitude": 23.4518, "longitude": 120.2555, "timezone": "Asia/Taipei" },
    { "name": "台東縣", "country": "台灣", "latitude": 22.7583, "longitude": 121.1444, "timezone": "Asia/Taipei" },
    { "name": "新北市", "country": "台灣", "latitude": 25.012, "longitude": 121.4657, "timezone": "Asia/Taipei" }
  ]
}

回應欄位說明

行星物件（chart.planets[]）

行星清單（planets 陣列共 17 筆，依序）

• 12 個行星／交點：太陽、月亮、水星、金星、火星、木星、土星、天王星、海王星、冥王星、北交點、南交點
• 2 個衍生點：福點（Part of Fortune：日盤 ASC＋月−日、夜盤 ASC−月＋日；日夜以太陽是否在地平線上判定）、莉莉絲（平均黑月莉莉絲＝平均月亮遠地點）
• 3 個定位星點位：北交點定位星、南交點定位星、上升星座定位星（各帶 ruling_planet 欄位，位置即其定位星行星的位置）

宮位制（chart.house_system）

相位圖形（chart.patterns[]）

從 12 個星體／交點的位置偵測三種經典圖形；無圖形時為空陣列 []。

每筆皆含 planets（組成星體名稱陣列）。去重規則：大十字會吸收其自身 4 星構成的 T三角（不重複回報）；北交點—南交點這組「定義上的對分相」不作為 T三角／大十字的對分軸（但交點仍可作為端點星等其他角色）；由於南交點恆與北交點正對，對分相被交點軸四分時只回報一筆 T三角（端點星為北交點），不會出現北／南交點鏡像的重複組。

元素統計（chart.element_stats）

統計 10 個古典行星（太陽～冥王星，不含交點與衍生點）落入星座的元素與模式分布，兩組計數各自加總為 10：

"element_stats": {
  "elements":   { "火": 1, "土": 5, "風": 2, "水": 2 },
  "modalities": { "基本": 6, "固定": 3, "變動": 1 }
}

對應規則：牡羊＝火／基本、金牛＝土／固定、雙子＝風／變動⋯依序循環（元素每 4 個星座一輪、模式每 3 個星座一輪）。

相位種類與容許度（orb）

回應中的 orb 為實際角度與準確相位角的偏差（度，四捨五入至小數 2 位），數值越小相位越緊密。行運（預設 3°）與推運（預設 1°）另以 orb_limit 過濾。

上升點與宮位

• chart.ascendant：上升點，含 zodiac、degree（星座內度數）、total_degree（黃道絕對經度）。P／W 兩制的上升點相同。
• chart.houses：12 筆宮首資料，每筆含 house_number（1–12）、degree（宮首的黃道絕對經度 0–360）、zodiac（宮首星座）。

錯誤碼

所有錯誤皆回傳 JSON，格式為：

{ "error": { "code": "<code>", "message": "<訊息（預設中文，依 lang 在地化）>" } }

message 會依請求的 lang 在地化（見多語言；主體無法解析或 lang 本身無效時固定 zh-TW）；code 與語言無關，下表範例皆為預設 zh-TW 訊息。大多數參數錯誤為 HTTP 400，但金鑰相關錯誤帶不同狀態（key_required／invalid_api_key 為 401、quota_exceeded 為 429）——請務必以 code 而非 HTTP 狀態或訊息文字判斷錯誤種類。

限制

• 宮位制支援 Placidus（P）與整宮制（W），無其他宮位制可選。
• Placidus 在極區緯度會被拒絕：約 |緯度| ≥ 66° 時 Placidus 宮位在數學上無定義，回 400 polar_latitude；改用 house_system: "W" 可正常計算。
• 冥王星僅支援 1885–2099 年：出生日期、行運時刻、推運目標日期、太陽回歸年份超出此範圍皆回 400 date_out_of_range。
• 時區必須為 IANA 識別碼（例如 Asia/Taipei、America/New_York），不接受 UTC+8、CST 之類的縮寫或偏移格式。
• 太陽回歸盤沿用舊版盤面結構（15 筆 planets、無逆行標記／福點／莉莉絲／patterns／element_stats，宮位固定 Placidus），詳見該端點的注意事項。

程式範例

curl — 本命盤（整宮制）

curl -s -X POST https://your-host/api/v1/charts \
  -H "Content-Type: application/json" \
  -d '{
    "birth_date": "1990-01-01",
    "birth_time": "12:00",
    "latitude": 25.033,
    "longitude": 121.5654,
    "timezone": "Asia/Taipei",
    "house_system": "W"
  }'

curl — 合盤

curl -s -X POST https://your-host/api/v1/synastry \
  -H "Content-Type: application/json" \
  -d '{
    "a": {"birth_date": "1990-01-01", "birth_time": "12:00",
          "latitude": 25.033, "longitude": 121.5654, "timezone": "Asia/Taipei"},
    "b": {"birth_date": "1992-06-15", "birth_time": "08:30",
          "latitude": 25.033, "longitude": 121.5654, "timezone": "Asia/Taipei"},
    "orb_limit": 6.0
  }'

curl — 此刻行運（省略 at）

curl -s -X POST https://your-host/api/v1/transits \
  -H "Content-Type: application/json" \
  -d '{
    "natal": {"birth_date": "1990-01-01", "birth_time": "12:00",
              "latitude": 25.033, "longitude": 121.5654, "timezone": "Asia/Taipei"}
  }'

JavaScript — fetch()

const res = await fetch("/api/v1/charts", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    birth_date: "1990-01-01",
    birth_time: "12:00",
    latitude: 25.033,
    longitude: 121.5654,
    timezone: "Asia/Taipei",
  }),
});
const json = await res.json();
if (!res.ok) throw new Error(`${json.error.code}: ${json.error.message}`);
console.log(json.data.chart.ascendant); // { zodiac: "牡羊座", degree: 16.4422, … }
const retro = json.data.chart.planets.filter(p => p.retrograde);
console.log(retro.map(p => p.planet)); // ["水星", "金星", "木星"]

Ruby — Net::HTTP

require "net/http"
require "json"

uri = URI("https://your-host/api/v1/charts")
res = Net::HTTP.post(
  uri,
  {
    birth_date: "1990-01-01",
    birth_time: "12:00",
    latitude: 25.033,
    longitude: 121.5654,
    timezone: "Asia/Taipei",
  }.to_json,
  "Content-Type" => "application/json"
)

json = JSON.parse(res.body)
if res.is_a?(Net::HTTPSuccess)
  sun = json.dig("data", "chart", "planets").find { |p| p["planet"] == "太陽" }
  puts "太陽：#{sun["zodiac"]} #{sun["degree"]} 度（第 #{sun["house"]} 宮）"
  puts "元素分布：#{json.dig("data", "chart", "element_stats", "elements")}"
else
  warn "#{json.dig("error", "code")}: #{json.dig("error", "message")}"
end

管理 API（營運用）

驗證方式：以 Authorization: Bearer <ADMIN_TOKEN> 傳入伺服器設定的密鑰（與 API 金鑰無關，是另一組營運機密）。

建立金鑰

請求主體：{"label":"...","tier":"free","monthly_limit":1000|null}（monthly_limit 為 null 表示無上限；須為非負整數或 null）。

回應 201（實際輸出）

{
  "data": {
    "id": 1,
    "token": "ak_7hgEJAyQvsuO4zHntkpoMvnvrecJ_6QJ",
    "prefix": "ak_7hgEJAyQ",
    "label": "Acme Web App",
    "tier": "free",
    "monthly_limit": 1000,
    "created_at": "2026-07-25T04:55:45Z"
  }
}

列出金鑰

依 id 由新到舊列出所有金鑰，不含 token／雜湊。

回應 200（實際輸出，節錄）

{
  "data": [
    {
      "id": 3, "prefix": "ak_IVRZsXlz", "label": "tiny", "tier": "free",
      "monthly_limit": 1, "created_at": "2026-07-25T04:55:45Z", "revoked_at": null
    },
    {
      "id": 1, "prefix": "ak_7hgEJAyQ", "label": "Acme Web App", "tier": "free",
      "monthly_limit": 1000, "created_at": "2026-07-25T04:55:45Z", "revoked_at": null
    }
    // …其餘省略
  ]
}

revoked_at 為 null 表示金鑰仍有效；已撤銷者帶 UTC 時間字串。

撤銷金鑰

撤銷指定金鑰；撤銷後該金鑰立即失效（之後呼叫回 401 invalid_api_key）。

回應 200（實際輸出）

{ "data": { "id": 1, "revoked": true } }

全站用量

檢視某月（省略 month 時為當月 UTC）的全站用量。by_key 以金鑰 id 為鍵對應該金鑰呼叫數，匿名呼叫歸在 "anonymous"。

回應 200（實際輸出）

{
  "data": {
    "month": "2026-07",
    "total": 7,
    "by_endpoint": { "cities": 3, "charts": 3, "synastry": 1 },
    "by_key": { "1": 5, "anonymous": 1, "3": 1 }
  }
}

瀏覽器管理頁

另提供一個瀏覽器管理頁面 /admin：這是一個公開的外殼頁（頁面本身免驗證即可載入），會在前端提示輸入 ADMIN_TOKEN，再以該權杖呼叫上述管理 API。實際操作仍受 ADMIN_TOKEN 保護。

OpenAPI 規格

完整的機器可讀 API 規格（OpenAPI 3.1，含所有端點的請求／回應 schema 與範例）：GET /openapi.json。可直接匯入 Swagger UI、Postman、Insomnia 等工具。