Ablecity 로고
2026.03.01 v2.5 Updated

🔗 Ablecity 만세력·사주·소개팅 API Reference

AI·매칭·렌탈 플랫폼을 위한 REST API 가이드입니다.
99.99% SLA150ms 미만 레이턴시를 보장하는 인프라 위에서 귀사의 서비스를 구축하세요.

1. Authentication

모든 API 요청에는 HTTP Header에 Bearer Token을 포함해야 합니다.

Authorization: Bearer <API_KEY>

API 키는 상단의 'API 키 발급 신청' 버튼을 통해 신청하실 수 있습니다.

⚡ Performance & Benchmark

Ablecity는 단순한 만세력 산출 도구가 아닙니다. 글로벌 서비스(SaaS, Game, App)를 지탱하기 위해 설계된 엔터프라이즈급 인프라를 제공합니다. 기존 레거시 API 서비스와 성능을 비교해 보세요.

Metrics (성능 지표) Legacy Competitor (타사) Ablecity (Global Std)
Global Latency (US West) 1,200ms ~ 2,500ms 30ms ~ 150ms
Max Concurrency (TPS) ~ 50 TPS (Throttled) 30,000+ TPS
Astronomical Precision 평균 태양시 (KST 고정) GPS 기반 진태양시 보정
Payload Efficiency Heavy HTML/Text Mixed Lightweight JSON
SLA (가용성 보장) None (Best Effort) 99.99% Guaranteed

2. 공통 응답 형식

{
  "status": "success",   // or "error"
  "data": ... ,          // 결과 데이터
  "message": "..."       // 설명 메시지
}

3. Endpoints

3.1 GET /api/v1/saju/fortune

사용자의 생년월일·출생 시각(birth), 성별(gender), (선택) 태어난 도시(city), 자정 처리 방식, 사용 달력을 기반으로 만세력(사주팔자), 오행, 격국, 용신, 대운 및 다양한 행운 요소를 계산합니다.

🧩 신살(SIS) 옵션 안내

  • 기본 만세력 조회는 신살(SIS)을 제외하고 반환합니다.
  • SIS(신살) 포함은 API 키 발급 신청 시 별도 신청/승인이 필요합니다. (승인된 API Key에만 sinsal / relations_ui 등이 포함)
  • 보안 강화를 위해 일부 디버그/정책성 필드(예: analysis_flow, strength_components, hehua.candidates)는 공개 스펙에서 제거되었습니다.
curl -X GET \
          "https://api.ablecity.kr/api/v1/saju/fortune?birth=1990-01-01T01:00:00&gender=male" \
          -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 형식만 지원합니다. (날짜와 시간 사이 대문자 T)
gender string Yes 성별. 남자: male, 여자: female (그 외 값 오류)
city string Optional 태어난 도시 (LMT 보정용). 미입력 시 서울특별시 기준.
지원 도시는 아래 목록 참고.
midnightType integer Optional 0: 야자/조자 분리 (기본값)
1: 정자시 방식 (23:00~00:59를 모두 익일로 처리)
calendar string Optional solar(양력, 기본값), lunar(음력), leap(윤달)
📍 사주 API 지원 도시 목록 (city) 전체 보기

표기 예: city=서울특별시

서울특별시 부산광역시 대구광역시 인천광역시 광주광역시 대전광역시 울산광역시 세종특별자치시 수원시 고양시 용인시 성남시 부천시 안산시 화성시 남양주시 안양시 평택시 의정부시 파주시 시흥시 김포시 광명시 광주시(경기) 군포시 이천시 오산시 하남시 양주시 구리시 안성시 포천시 의왕시 여주시 동두천시 과천시 가평군 양평군 연천군 춘천시 원주시 강릉시 동해시 태백시 속초시 삼척시 홍천군 횡성군 영월군 평창군 정선군 철원군 화천군 양구군 인제군 고성군(강원) 양양군 청주시 충주시 제천시 보은군 옥천군 영동군 증평군 진천군 괴산군 음성군 단양군 천안시 공주시 보령시 아산시 서산시 논산시 계룡시 당진시 금산군 부여군 서천군 청양군 홍성군 예산군 태안군 전주시 군산시 익산시 정읍시 남원시 김제시 완주군 진안군 무주군 장수군 임실군 순창군 고창군 부안군 목포시 여수시 순천시 나주시 광양시 담양군 곡성군 구례군 고흥군 보성군 화순군 장흥군 강진군 해남군 영암군 무안군 함평군 영광군 장성군 완도군 진도군 신안군 포항시 경주시 김천시 안동시 구미시 영주시 영천시 상주시 문경시 경산시 의성군 청송군 영양군 영덕군 청도군 고령군 성주군 칠곡군 예천군 봉화군 울진군 울릉군 독도 창원시 진주시 통영시 사천시 김해시 밀양시 거제시 양산시 의령군 함안군 창녕군 고성군(경남) 남해군 하동군 산청군 함양군 거창군 합천군 제주시 서귀포시 기장군 달성군 군위군 울주군 강화군 옹진군

Response Example

{
  "status": "success",
  "message": "요청이 완료되었습니다.",
  "data": {
    "year":  { "branch_sipseong": "정인", "stem_sipseong": "겁재", "hanja": "庚辰", "hangul": "경진" },
    "month": { "branch_sipseong": "편인", "stem_sipseong": "식신", "hanja": "癸未", "hangul": "계미" },
    "day":   { "branch_sipseong": "편재", "stem_sipseong": "비견", "hanja": "辛卯", "hangul": "신묘" },
    "hour":  { "branch_sipseong": "편관", "stem_sipseong": "정재", "hanja": "甲午", "hangul": "갑오" },

    "fortune": 8,

    "hehua": {
      "effective": [ /* ... */ ],
      "failed": [],
      "applied_true": true,
      "applied_pseudo": false,
      "applied_any": true,
      "applied": true,
      "adjustments": [ /* ... */ ],

      "five_before_points": { /* ... */ },
      "five_before_pct": { /* ... */ },
      "five_after_points": { /* ... */ },
      "five_after_pct": { /* ... */ },
      "five_changed": true,

      "strength_before_score": 1.1,
      "strength_before": "weak",
      "strength_after_score": 1.2,
      "strength_after": "weak",
      "strength_changed": false,
      "strength_delta": 0.1,

      "yongshin_before": { "primary": "earth", "secondary": "metal" },
      "yongshin_after":  { "primary": "earth", "secondary": "metal" },
      "yongshin_changed": false
    },

    "five": { "metal": 2.09, "fire": 1.11, "wood": 1.67, "water": 1.03, "earth": 2.75 },
    "five_pct": { "earth": 31.8, "metal": 24.2, "fire": 12.8, "wood": 19.3, "water": 11.9 },
    "five_star": { "earth": "★★★★☆", "metal": "★★★☆☆", "fire": "★☆☆☆☆", "wood": "★★☆☆☆", "water": "★☆☆☆☆" },
    "five_kor": { "금(金)": 2.09, "목(木)": 1.67, "토(土)": 2.75, "화(火)": 1.11, "수(水)": 1.03 },

    "twelve_growth": { "month": "衰", "hour": "病", "year": "墓", "day": "絶" },
    "twelve_growth_kor": { "month": "쇠", "hour": "병", "year": "묘", "day": "절" },

    "strength_score": 1.2,
    "strength": "weak",

    "geokguk": { /* ... */ },
    "yongshin": { "primary": "earth", "primary_kor": "토(土)", "secondary": "metal", "secondary_kor": "금(金)" },

    "branch_relations": { /* ... */ },
    "branch_relations_kor": { /* ... */ },
    "branch_relations_distance": { /* ... */ },

    "big_luck": [ /* ... */ ],
    "lucky": { /* ... */ },
    "summary": { "pillars": "경진년 계미월 신묘일 갑오시", "strength": "신약(身弱)", "zodiac": "용띠" },
    "zodiac_compatibility": [ /* ... */ ]

    /* SIS(신살) 옵션 승인 시 아래 필드가 추가됩니다. */
    ,"relations_ui": { /* ... */ }
    ,"sinsal": [ /* ... */ ]
    ,"gongmang": { /* ... */ }
  }
}

주요 필드 설명

사주 기둥 (year, month, day, hour)

간지(Hangul/Hanja) 및 십성 정보(branch/stem sipseong) 포함

오행 분포 (five)

오행 절대값, 퍼센트, 별점(star), 한글 키 매핑 데이터 제공

합화 분석 (hehua)

true/pseudo/fail 단계 판정, 적용 여부, 오행 재분배 전후, 합화 전후 강약·용신 비교를 제공합니다.

십이운성 (twelve_growth)

각 기둥별 십이운성 상태(장생, 목욕 등) 한글/한자 제공

일간 강약 (strength)

strength와 함께 strength_score, strength_thresholds, strength_components 제공

격국 (geokguk)

geok_detail, pillar_category_counts, follower_candidate, variant_signal까지 확장 제공

용신/희신 (yongshin)

사주의 균형을 맞추는 핵심 오행 정보

지지 관계 (branch_relations)

합·충·형·해·파 + half_three_harmonies, banghap, bangguks, wonjins, guimuns, amhaps, tam_hap_mang_chung

관계 거리/정책

branch_relations_distance(near/mid/far), branch_relations_policy(optional) 제공

관계 요약 UI (relations_ui)

합·충·해·공망 등 관계 신호를 UI 친화적으로 요약(헤드라인/토큰/톤)해 제공합니다. (SIS 옵션)

신살(SIS) (sinsal)

sis_code 기반의 정식 신살 데이터(요약·속성·판정·권고)를 제공합니다. (SIS 옵션)

대운 (big_luck)

10년 단위의 운세 흐름 배열 (나이/연도 구간 포함)

행운 요소 (lucky)

행운의 숫자, 방향, 색상(추천/비추천 CSS 컬러 코드 포함), 부족한 오행

🆕 신규 응답 필드 상세 (Advanced Analysis)

Field Type Description
hehua Object

육합 합화 판정·적용 결과입니다.

  • effective / failed: 성립/미성립 목록
  • applied*: 실제 반영 플래그
  • adjustments: 오행 이동량
  • five_before_*, five_after_*: 합화 전후 오행 비교
  • strength_before/after, yongshin_before/after: 합화 전후 강약/용신 변화 추적

* 보안상 엔진 내부 후보/조건(candidates 등)은 공개 스펙에서 제외됩니다.

branch_relations_distance Object 관계별 궁위 거리 요약입니다. 관계 키별로 near, mid, far 카운트를 반환합니다.
branch_relations_policy Object 관계 점수화/분류 정책입니다. 공개 스펙에서는 빈 Object({})로 반환될 수 있습니다.
relations_ui Object

관계 신호를 UI 렌더링에 바로 쓰기 좋게 요약한 객체입니다. (SIS 옵션)

  • summary: 헤드라인/카운트/최상위 경고 신호
  • items[]: 그룹(harmony/tension/special)·톤(good/warn/danger)·토큰 목록
  • gongmang: 공망(旬空) 상세(공망지·원국 포함 여부 등)
sinsal Array<Object>

신살(SIS) 정식 버전 응답입니다. (SIS 옵션)

  • sis_code: S001~S056 (아래 ‘지원 목록’의 No.와 1:1 매핑)
  • name_kr / name_en: 신살 명칭
  • chart_vector: 특성 점수 벡터(0~100)
  • attributes: 발생 위치/조합/트리거 등 속성
  • final_verdict: 등급/키워드/해석/조언(필드 구성은 신살 유형별로 일부 상이)
  • is_present: 해당 신살 유무
gongmang Object 공망(旬空) 요약 객체입니다. 공망지(한자/한글) 및 관련 신살 요약을 포함합니다. (SIS 옵션)
strength_score Number 강약 판정을 위한 정량 점수입니다. (문서 예시: weak / strong)
strength_thresholds / strength_components Object Deprecated – 보안상 공개 스펙에서 제거되었습니다.
analysis_flow Array<String> Deprecated – 보안상 공개 스펙에서 제거되었습니다.
geokguk (expanded) Object 기존 격국 필드에 geok_detail, pillar_category_counts, follower_candidate, variant_signal이 포함됩니다.
zodiac_compatibility Array<Object> 본인 띠 기준 12지신 궁합 데이터입니다. animal, score, grade, relation, desc를 반환합니다.
📚 지원하는 신살 전체 목록 (56종) Enum Reference

Ablecity 사주 API는 국내 최다 수준인 56종의 신살을 정밀 분석합니다.
응답 데이터는 SIS(신살) 정식 버전에서 sis_code(S001~S056)·name_kr·name_en를 반환합니다.
아래 목록의 No.sis_code는 1:1로 매핑됩니다. (예: No. 1 ↔ S001) * 상세 산출 로직(공식)은 에이블시티의 핵심 IP로, API 응답을 통해서만 결과를 제공합니다.

No. 구분 한글명 (Name) 영문 키 (Key)
1흉살격각살gyeok-gak-sal
2흉살겁살geop-sal
3흉살고란살go-ran-sal
4흉살고신살go-sin-sal
5기타공망gong-mang
6흉살과숙살gwa-suk-sal
7길신괴강귀인goe-gang-gwi-in
8흉살괴강살goe-gang-sal
9흉살귀문관살gwi-mun-gwan-sal
10길신금여geum-yeo
11길신록신귀인rok-sin-gwi-in
12흉살망신살mang-sin-sal
13길신문곡귀인mun-gok-gwi-in
14길신문창귀인mun-chang-gwi-in
15길신반안살ban-an-sal
16흉살백호살baek-ho-sal
17길신복성귀인bok-seong-gwi-in
18길신삼기sam-gi
19흉살조객살jo-gaek-sal
20흉살상문살sang-mun-sal
21흉살양인살yang-in-sal
22흉살역마살yeok-ma-sal
23흉살도화살(연살,함지살)do-hwa-sal
24흉살원진살won-jin-sal
25길신월덕귀인wol-deok-gwi-in
26흉살월살wol-sal
27흉살육해살yuk-hae-sal
28길신장성살jang-seong-sal
29흉살재살jae-sal
30흉살지복살ji-bok-sal
31길신지살ji-sal
32길신천계귀인cheon-gye-gwi-in
33길신천관성cheon-gwan-seong
34길신천덕귀인cheon-deok-gwi-in
35흉살천라지망cheon-ra-ji-mang
36길신천문성cheon-mun-seong
37길신천복성cheon-bok-seong
38길신천수성cheon-su-seong
39길신천을귀인cheon-eul-gwi-in
40길신천의성cheon-ui-seong
41길신천주귀인cheon-ju-gwi-in
42흉살충살chung-sal
43길신태극귀인tae-geuk-gwi-in
44길신학당귀인hak-dang-gwi-in
45기타현침살hyeon-chim-sal
46흉살형살hyeong-sal
47길신홍염살hong-yeom-sal
48기타화개hwa-gae
49길신천덕합cheon-deok-hap
50길신월덕합wol-deok-hap
51길신협록hyeop-rok
52길신암록am-rok
53흉살파살pa-sal
54흉살천살cheon-sal
55흉살탕화살tang-hwa-sal
56흉살효신살hyo-sin-sal
(총 56종 리스트)

3.2 테마별 운세 및 심화 분석 (Add-ons)

기본 만세력 외에 다양한 테마별 운세, 정밀 분석, 그리고 AI Vision(관상/손금) 서비스를 제공합니다.
서비스의 복잡도와 특성에 따라 동기(GET) 방식과 비동기(POST+Callback) 방식으로 구분됩니다.

  • GET 동기 처리 (Synchronous): 호출 즉시 결과를 반환합니다.
  • POST 비동기 처리 (Asynchronous): 연산 후 X-Callback-URL로 결과를 전송합니다.

🔗 서비스 엔드포인트 목록

Method Endpoint Path (Full URL) 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 필수)
POST /api/v1/saju/fortune/request-analysis/great-luck 대운 분석
(Callback 필수)
POST /api/v1/saju/fortune/request-analysis/yearly-luck 세운 분석
(Callback 필수)
TBD /api/v1/saju/fortune/naming 작명 (업데이트 예정)
TBD /api/v1/vision/palm 손금 (업데이트 예정)
TBD /api/v1/vision/face 관상 (업데이트 예정)

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

소개팅·결혼중개 매칭 요청을 생성하며, 사용자의 선호도(나이, 관심사)와 위치 반경(Radius) 필터링을 지원합니다.

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": 37.5665, "lng": 126.9780, "radiusKm": 30 }
  },
  "maxResults": 10
}'

Response Example (201 Created)

{
  "status": "success",
  "data": {
    "requestId": "REQ-67890",
    "status": "processing",
    "submittedAt": "2025-05-10T11:00:00+09:00"
  }
}

3.3 GET /api/v1/matching/{requestId}/results

비동기로 처리된 매칭 진행 상황과 결과 리스트를 조회합니다. limitoffset을 사용해 페이징 처리가 가능합니다.

GET /api/v1/matching/{requestId}/results

Request Example

curl -X GET \
"https://api.ablecity.kr/v1/matching/REQ-67890/results?limit=5&offset=0" \
-H "Authorization: Bearer <API_KEY>"

Response Example

{
  "status": "success",
  "data": {
    "requestId": "REQ-67890",
    "status": "completed",
    "results": [
      {
        "matchId": "MCH-001",
        "name": "홍길동",
        "age": 29,
        "distanceKm": 3.5,
        "commonInterests": ["travel", "cooking"],
        "matchScore": 0.92,
        "profileImage": "https://ablecity.kr/images/users/hong.jpg"
      },
      {
        "matchId": "MCH-002",
        "name": "김미영",
        "age": 32,
        "distanceKm": 5.8,
        "commonInterests": ["music", "art"],
        "matchScore": 0.88,
        "profileImage": "https://ablecity.kr/images/users/kim.jpg"
      }
    ],
    "totalResults": 8
  }
}

3.4 GET /api/v1/tutoring/availability

특정 날짜와 서비스 유형에 대해 예약 가능한 시간대(Slot) 목록을 조회합니다.

GET /api/v1/tutoring/availability

Request Example

curl -X GET \
"https://api.ablecity.kr/v1/tutoring/availability?date=2025-06-15&serviceType=care" \
-H "Authorization: Bearer <API_KEY>"

Response Example

{
  "status": "success",
  "data": [
    {
      "slotId": "SLT-001",
      "start": "2025-06-15T09:00:00+09:00",
      "end":   "2025-06-15T10:00:00+09:00",
      "price": 35000
    },
    {
      "slotId": "SLT-002",
      "start": "2025-06-15T14:00:00+09:00",
      "end":   "2025-06-15T15:30:00+09:00",
      "price": 50000
    }
  ]
}

3.5 POST /api/v1/tutoring/book

선택한 시간대(Slot ID)로 서비스를 예약하고 결제를 진행합니다.

POST /api/v1/tutoring/book

Request Example

curl -X POST https://api.ablecity.kr/v1/tutoring/book \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "userId":       "USER123",
  "slotId":       "SLT-001",
  "paymentMethod":"card",
  "cardInfo": {
    "cardNumber": "4111111111111111",
    "expiry":     "12/25",
    "cvc":        "123"
  }
}'

Response Example (201 Created)

{
  "status": "success",
  "data": {
    "bookingId":       "BOOK-34567",
    "status":          "confirmed",
    "paidAmount":      35000,
    "confirmationUrl": "https://ablecity.kr/booking/BOOK-34567"
  }
}

3.6 GET /api/v1/otc/listings

거래 가능한 OTC(장외거래) 리스팅을 조회하며, 자산 유형(BTC/ETH 등)과 최소 수량 필터를 지원합니다.

GET /api/v1/otc/listings

Request Example

curl -X GET \
"https://api.ablecity.kr/v1/otc/listings?assetType=BTC&minQuantity=0.5" \
-H "Authorization: Bearer <API_KEY>"

Response Example

{
  "status": "success",
  "data": [
    {
      "listingId":    "LST-1001",
      "assetType":    "BTC",
      "quantity":     1.2,
      "pricePerUnit": 50000000,
      "totalPrice":   60000000,
      "sellerId":     "TraderA",
      "escrowStatus": "pending"
    }
  ]
}

3.7 POST /api/v1/otc/order

선택한 리스팅으로 OTC 거래 주문을 생성하고, 안전 거래를 위한 스마트 컨트랙트 에스크로 주소를 반환합니다.

POST /api/v1/otc/order

Request Example

curl -X POST https://api.ablecity.kr/v1/otc/order \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "listingId": "LST-1001",
  "buyerId":   "USER456",
  "quantity":  0.8
}'

Response Example (201 Created)

{
  "status": "success",
  "data": {
    "orderId":       "ORD-2002",
    "escrowAddress": "0xabcd1234ef567890...",
    "expiresAt":     "2025-05-10T12:00:00+09:00"
  }
}

3.8 GET /api/v1/rental/assets

렌탈 가능한 자산 목록을 조회하며, 카테고리(카메라, 장비 등) 및 위치 기반(반경) 필터를 지원합니다.

GET /api/v1/rental/assets

Request Example

curl -X GET \
"https://api.ablecity.kr/v1/rental/assets?category=camera&lat=37.5665&lng=126.9780&radiusKm=10" \
-H "Authorization: Bearer <API_KEY>"

Response Example

{
  "status": "success",
  "data": [
    {
      "assetId":           "ASSET-3001",
      "name":              "Canon EOS R5",
      "category":          "camera",
      "location": { "lat": 37.5665, "lng": 126.9780 },
      "hourlyRate":        15000,
      "availabilityCount": 3
    }
  ]
}

3.9 POST /api/v1/rental/reserve

선택한 자산을 예약하고, 총 비용 계산 및 예약 확인 URL을 반환합니다.

POST /api/v1/rental/reserve

Request Example

curl -X POST https://api.ablecity.kr/v1/rental/reserve \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "userId":    "USER123",
  "assetId":   "ASSET-3001",
  "startTime": "2025-06-20T09:00:00+09:00",
  "endTime":   "2025-06-20T17:00:00+09:00"
}'

Response Example (201 Created)

{
  "status": "success",
  "data": {
    "reservationId":   "RES-4003",
    "totalCost":       120000,
    "confirmationUrl": "https://ablecity.kr/reservations/RES-4003"
  }
}

4. Error Codes

HTTP Status Code Description
400 INVALID_REQUEST 잘못된 요청입니다.
401 UNAUTHORIZED 인증 실패 또는 토큰 만료.
404 NOT_FOUND 리소스를 찾을 수 없습니다.
429 RATE_LIMIT 요청 한도 초과입니다.
500 SERVER_ERROR 서버 내부 오류.

4.1 공통 message 값

  • 요청이 완료되었습니다. – 성공 처리.
  • 서버 처리 중 오류가 발생했습니다. – 서버 내부 오류. 서버 로그 확인 필요.
  • 서비스를 찾을 수 없습니다. – 지원하지 않는 서비스(URL)를 호출한 경우.

4.2 인증 / Rate Limit 관련 message

  • 유효하지 않은 API Key입니다.
    API Key가 삭제(비활성화)되었거나 만료되었거나, 요청 헤더에 존재하지 않을 때.
  • 허용된 전체 분당 요청 횟수가 초과되었습니다.
    API Key에 할당된 1분당 전체 요청 횟수를 초과.
  • 허용된 전체 일일 요청 횟수가 초과되었습니다.
    API Key에 할당된 일일 전체 요청 횟수를 초과.
  • 허용되지 않은 서비스입니다.
    요청한 서비스(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 Limit

안정적인 서비스 제공을 위해 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건까지 무료이며, 이후에는 구독 형태에 따라(건당 10원~100원)가 적용됩니다.

일일 호출 한도(Rate Limit)는 어떻게 되나요?

모든 엔드포인트는 기본적으로 분당 60건, 하루 50,000건으로 제한됩니다. 대규모 트래픽이 예상되는 경우 고객센터를 통해 상향 요청이 가능합니다.

사주 API는 어떤 프로그래밍 언어에서 사용할 수 있나요?

표준 RESTful JSON 응답을 제공하므로 Python, JavaScript(Node.js), Java, PHP, Go 등 HTTP 클라이언트를 지원하는 모든 언어 및 플랫폼에서 호출할 수 있습니다.

에러 발생 시 재시도 정책은 어떻게 되나요?

429(요청 한도 초과) 또는 5xx 에러 발생 시, 지수 백오프(Exponential Backoff) 방식(예: 1s → 2s → 4s)으로 최대 3회까지 재시도하는 것을 권장합니다.

무료 체험용 API 키는 어떻게 받나요?

👉 API 키 발급 신청서(구글폼)를 통해 접수해 주시면, 관리자가 검토 후 1~2일 이내에 이메일로 키를 발송해 드립니다.

7. Support

도움이 필요하신가요?

API 연동 중 발생하는 기술적인 이슈나 추가 도움말은 이메일로 문의해 주세요.
담당 엔지니어가 빠르게 확인 후 답변드립니다.

✉️ [email protected]