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 | 180ms ~ 350ms [P90] |
| 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), 자정 처리 방식, 사용 달력을 기반으로
만세력(사주팔자), 오행, 격국, 용신, 대운 및 다양한 행운 요소를 계산합니다.
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": { "hangul": "경진", "hanja": "庚辰", "branch_sipseong": "정인", "stem_sipseong": "겁재" },
"month": { "hangul": "계미", "hanja": "癸未", "branch_sipseong": "편인", "stem_sipseong": "식신" },
"day": { "hangul": "신묘", "hanja": "辛卯", "branch_sipseong": "편재", "stem_sipseong": "비견" },
"hour": { "hangul": "무자", "hanja": "戊子", "branch_sipseong": "식신", "stem_sipseong": "정인" },
"fortune": 8,
"five": { "earth": 3.46, "metal": 2.09, "fire": 0.23, "wood": 0.96, "water": 1.87 },
/* ... (중략: 기존 five_pct, geokguk 등 유지) ... */
"summary": {
"pillars": "경진년 계미월 신묘일 무자시",
"strength": "중화(中和)",
"zodiac": "용띠"
},
"zodiac_compatibility": [
{
"score": 95,
"grade": "best",
"animal": "쥐",
"branch": "子",
"relation": "삼합(三合)",
"desc": "서로 부족한 점을 채워주는 최상의 궁합입니다."
},
{
"score": 20,
"grade": "bad",
"animal": "개",
"branch": "戌",
"relation": "충(沖)",
"desc": "서로 부딪히는 기운으로, 갈등에 주의가 필요합니다."
}
/* ... 후략 ... */
],
"sinsal": [
{
"name": "천주귀인",
"score": 85,
"desc": "평생 마르지 않는 식복. 요식업/사업 번창의 기운",
"relatedChar": "子",
"descCount": 1,
"positions": ["HOUR"]
},
{
"name": "현침살",
"score": 41,
"desc": "예리한 정밀함과 전문성. (총 보유: 2개) 섬세한 손재주와 디테일",
"relatedChar": "未, 辛卯",
"descCount": 2,
"positions": ["MONTH", "DAY"]
},
{
"name": "괴강살",
"score": 45,
"desc": "압도적 리더십과 결단력",
"relatedChar": "庚辰",
"descCount": 1,
"positions": ["YEAR"]
}
],
"gongmang": {
"sinsals": [
{
"name": "공망",
"score": 38,
"desc": "[토(土)]비움과 채움의 미학. 해당 궁위의 결핍.",
"relatedChar": "丑",
"descCount": 1,
"positions": ["MONTH"]
}
],
"hanja": ["午", "未"],
"hangul": ["오", "미"]
}
}
}
주요 필드 설명
사주 기둥 (year, month, day, hour)
간지(Hangul/Hanja) 및 십성 정보(branch/stem sipseong) 포함
오행 분포 (five)
오행 절대값, 퍼센트, 별점(star), 한글 키 매핑 데이터 제공
오행 분포 (five complex)
오행 에너지의 정밀 분석 데이터입니다.
five: 내부 알고리즘으로 산출된 에너지 절대값 (Float)five_pct: 전체 합을 100%로 보았을 때의 상대 비율 (%)five_star: 에너지 강약을 5점 만점 별점으로 시각화
십이운성 (twelve_growth)
각 기둥별 십이운성 상태(장생, 목욕 등) 한글/한자 제공
일간 강약 (strength)
신강/신약/중화(balanced) 판정 결과
격국 (geokguk)
격국 명칭 및 카테고리별 세력 점유율(share)
용신/희신 (yongshin)
사주의 균형을 맞추는 핵심 오행 정보
지지 관계 (branch_relations)
합, 충, 형, 파, 해 등 지지 간의 상호작용 분석
대운 (big_luck)
10년 단위의 운세 흐름 배열 (나이/연도 구간 포함)
행운 요소 (lucky)
행운의 숫자, 방향, 색상(추천/비추천 CSS 컬러 코드 포함), 부족한 오행
🆕 신규 응답 필드 상세 (Advanced Analysis)
| Field | Type | Description |
|---|---|---|
| sinsal | Array<Object> |
사주팔자에 적용된 모든 신살(길신/흉살) 목록입니다.
|
| zodiac_compatibility | Array<Object> |
본인 띠 기준, 12지신 상대방과의 궁합 분석 데이터입니다.
|
📚 지원하는 신살 전체 목록 (56종) Enum Reference ▼
Ablecity 사주 API는 국내 최다 수준인 56종의 신살을 정밀 분석합니다.
응답 데이터의 name은 한글명을, key는 아래 영문 코드를 반환합니다.
* 상세 산출 로직(공식)은 에이블시티의 핵심 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 |
3.2 사주 분석 및 부가 서비스 (Add-ons)
기본 만세력 외에 심화 분석(궁합, 대운)이나 테마별 운세(재물, 연애)를 조회할 수 있는 전용 엔드포인트입니다.
* 모든 요청에는 Authorization: Bearer <API_KEY> 헤더가 필요합니다.
📝 상세 분석 및 궁합 (POST)
| Method | Endpoint URL | Description |
|---|---|---|
| POST | /api/v1/saju/fortune/request-analysis/ | 사주 상세 분석 요청 (Callback 방식 지원) |
| POST | /api/v1/saju/fortune/request-analysis/match | 2인 궁합 분석 요청 (male/female 객체 전송) |
🔮 테마별 운세 조회 (GET)
* Base URL: https://api.ablecity.kr
* 공통 파라미터: birth, gender, city 등 (기본 만세력과 동일)
| Category | Endpoint Path | Note |
|---|---|---|
| 오늘의 운세 | /api/v1/saju/fortune/daily | 일진(日辰) 분석 |
| 오늘의 띠별 운세 | /api/v1/saju/fortune/zodiac-luck | 12개 전체 띠의 운세 |
| 주간 운세 | /api/v1/saju/fortune/request-analysis/week-luck | 주 단위 흐름 |
| 올해 운세 (세운) | /api/v1/saju/fortune/request-analysis/this-year-luck | 신년 운세 |
| 올해 애정운 | /api/v1/saju/fortune/request-analysis/love-luck | 연애/결혼 |
| 올해 재물운 | /api/v1/saju/fortune/request-analysis/rich-luck | 금전/투자 |
| 사주 풀이 | /api/v1/saju/fortune/request-analysis/telling | 종합 해설 |
| 대운 분석 | /api/v1/saju/fortune/request-analysis/great-luck | 10년 주기 |
| 세운 분석 | /api/v1/saju/fortune/request-analysis/yearly-luck | 연 단위 흐름 |
| 작명 | /api/v1/saju/fortune/naming | 업데이트 예정 |
| 손금 | /api/v1/vision/palm | 업데이트 예정 |
| 관상 | /api/v1/vision/face | 업데이트 예정 |
3.2 POST /api/v1/matching
소개팅·결혼중개 매칭 요청을 생성하며, 사용자의 선호도(나이, 관심사)와 위치 반경(Radius) 필터링을 지원합니다.
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
비동기로 처리된 매칭 진행 상황과 결과 리스트를 조회합니다. limit과 offset을 사용해 페이징 처리가 가능합니다.
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) 목록을 조회합니다.
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)로 서비스를 예약하고 결제를 진행합니다.
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 등)과 최소 수량 필터를 지원합니다.
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 거래 주문을 생성하고, 안전 거래를 위한 스마트 컨트랙트 에스크로 주소를 반환합니다.
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
렌탈 가능한 자산 목록을 조회하며, 카테고리(카메라, 장비 등) 및 위치 기반(반경) 필터를 지원합니다.
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을 반환합니다.
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를 기준으로 아래의 기본 한도가 적용됩니다.
⚠️ 한도 초과 시 처리 (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 연동 중 발생하는 기술적인 이슈나 추가 도움말은 이메일로 문의해 주세요.
담당 엔지니어가 빠르게 확인 후 답변드립니다.