1. Authentication
All API requests must include a Bearer Token in the HTTP Header.
Authorization: Bearer <API_KEY>
You can obtain your API key by submitting a request via the button above.
⚡ Performance & SLAs
Ablecity is designed for high-throughput global applications. We guarantee enterprise-grade performance compared to traditional legacy providers.
| Metrics | Legacy Competitors | Ablecity (Global Cloud) |
|---|---|---|
| Global Latency (US West) | 1,200ms ~ 2,500ms | 180ms ~ 350ms [P90] |
| Max Concurrency (TPS) | ~ 50 TPS (Throttled) | 30,000+ TPS |
| Calculation Precision | Mean Solar Time (Fixed KST) | GPS-based True Solar Time |
| Uptime SLA | None (Best Effort) | 99.99% Guaranteed |
2. Standard Response Format
{
"status": "success", // or "error"
"data": ... , // Payload
"message": "..." // Description or error message
}
3. Endpoints Overview
3.1 GET /api/v1/saju/fortune
Predictive AIGenerates a complete Asian Astrology (Four Pillars of Destiny) chart. It calculates the user's elemental balance, personality archetypes (Ten Gods), and future fortune trends based on precise astronomical data.
curl -X GET \
"https://api.ablecity.kr/api/v1/saju/fortune?birth=1995-06-15T14:30:00&gender=male&city=NewYork" \
-H "Authorization: Bearer <API_KEY>" \
-H "Accept: application/json"
* midnightType (0: Standard) and calendar (solar) are applied as defaults if omitted.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| birth | string | Yes |
Date and time of birth in ISO 8601 format. (e.g., 1995-06-15T14:30:00 - The 'T' separator is mandatory)
|
| gender | string | Yes |
Biological sex for calculation logic. Values: male or female.
|
| city | string | Optional |
Birth city for True Solar Time correction. Defaults to Seoul.See the supported Western cities list below. |
| midnightType | integer | Optional |
0: Split Rat Hour (Standard / Recommended)1: Combined Rat Hour (23:00~00:59 as next day)
|
| calendar | string | Optional |
solar (Gregorian, default), lunar, leap (Lunar Leap Month)
|
📍 Supported Cities List (Major Western Cities) ▼
Usage: city=NewYork or city=London
Response Example
{
"status": "success",
"message": "Request successful.",
"data": {
"year": {
"pillar": "Wu-Yin",
"translation": "Earth Tiger",
"archetype": "Direct Resource (The Scholar)"
},
"month": {
"pillar": "Jia-Yin",
"translation": "Wood Tiger",
"archetype": "Direct Officer (The Leader)"
},
"day": {
"pillar": "Xin-Hai",
"translation": "Metal Pig",
"archetype": "Self (The Core)"
},
"hour": {
"pillar": "Wu-Zi",
"translation": "Earth Rat",
"archetype": "Direct Resource (The Mentor)"
},
"elemental_balance": {
"wood": { "count": 3, "percentage": 46.3, "rating": "High" },
"fire": { "count": 1, "percentage": 5.0, "rating": "Low" },
"earth": { "count": 2, "percentage": 19.5, "rating": "Moderate" },
"metal": { "count": 1, "percentage": 7.3, "rating": "Low" },
"water": { "count": 1, "percentage": 21.9, "rating": "Moderate" }
},
"chart_strength": "Weak",
"balancing_element": {
"primary": "Fire",
"secondary": "Earth",
"advice": "Your chart is cold and damp. You need Fire energy (passion, activity) to balance it."
},
"lucky_factors": {
"color": "#FF5733 (Red/Orange)",
"direction": "South",
"number": [2, 7]
}
}
}
Field Descriptions
Pillars (year, month, day, hour)
Core stem/branch structure including Hanja/Hangul and Ten-Gods mapping.
Five-Element Distribution (five)
Absolute values, percentages, star ratings, and localized label mappings.
Hehua Analysis (hehua)
true / pseudo / failed staging, application flags, and before/after five-element + Yongshin tracking.
Twelve Growth (twelve_growth)
Lifecycle states for each pillar (Birth, Bath, Crown, etc.) in multilingual labels.
Strength (strength)
strength plus quantitative evidence via strength_score, strength_thresholds, and strength_components.
Pattern (geokguk)
Expanded pattern data including geok_detail, pillar_category_counts, and follower/variant signals.
Yongshin / Hishin (yongshin)
Primary and secondary balancing elements for practical guidance.
Branch Relations (branch_relations)
Harmony/clash/punishment/harm plus advanced sets like half_three_harmonies, banghap, and tam_hap_mang_chung.
Distance & Policy
branch_relations_distance (near/mid/far, avg_factor) and branch_relations_policy (core/aux/school tiers).
Analysis Flow (analysis_flow)
Traceable internal calculation steps for QA and debugging workflows.
Luck Cycles (big_luck)
10-year cycles with age ranges and year ranges for long-horizon forecasting.
Lucky Factors (lucky)
Actionable numbers, directions, and color hints (including CSS-style color tokens).
🆕 New Response Fields (Advanced Analysis)
| Field | Type | Description |
|---|---|---|
| hehua | Object | Six-harmony transformation evaluation result with candidates, effective groups, apply flags, adjustments, and before/after balance tracking. |
| branch_relations_distance | Object | Distance summary by relation key: near, mid, far, and avg_factor. |
| branch_relations_policy | Object | Scoring policy profile and relation tier sets (core, aux, school_specific). |
| analysis_flow | Array<String> | Engine flow trace array, e.g. branch_relations → hehua_condition_check → five_elements_recalculate. |
| strength_* | Number / Object | Quantified evidence for strength judgment, including score, thresholds, and components. |
| geokguk (expanded) | Object | Extended pattern object with geok_detail, pillar-level category counts, and variant signals. |
| sinsal | Array<Object> | Detailed list of all applied auspicious/inauspicious stars (up to 56 types) with score and position metadata. |
3.1-A Thematic Fortune & Deep Analysis (Add-ons)
Beyond the base natal chart endpoint, Ablecity provides thematic fortune modules,
deep narrative analysis, and AI Vision-ready expansion paths.
Endpoints are split into synchronous GET and asynchronous POST + callback flows.
- GET Synchronous: Returns results immediately in response.
-
POST
Asynchronous: Delivers results to
X-Callback-URLafter processing.
🔗 Endpoint List
| Method | Endpoint Path | Description |
|---|---|---|
| GET | /api/v1/saju/fortune/daily | Today's fortune |
| GET | /api/v1/saju/fortune/zodiac-luck | Today's zodiac fortune |
| POST | /api/v1/saju/fortune/request-analysis/match | Compatibility analysis (Callback required) |
| POST | /api/v1/saju/fortune/request-analysis/week-luck | Weekly fortune (Callback required) |
| POST | /api/v1/saju/fortune/request-analysis/this-year-luck | Yearly fortune (Callback required) |
| POST | /api/v1/saju/fortune/request-analysis/love-luck | Love forecast (Callback required) |
| POST | /api/v1/saju/fortune/request-analysis/rich-luck | Wealth forecast (Callback required) |
| POST | /api/v1/saju/fortune/request-analysis/telling | Narrative Saju reading (Callback required) |
Request Example (POST + Callback)
* For asynchronous analysis requests, X-Callback-URL is required.
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": "Seoul",
"calendar": "solar",
"midnightType": 0
}'
3.2 POST /api/v1/matching
Creates a matching request for social discovery apps. Supports filtering by age, interests, and geolocation (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": ["tech", "hiking"],
"location": { "lat": 40.7128, "lng": -74.0060, "radiusKm": 15 }
},
"maxResults": 10
}'
3.6 ~ 3.9 OTC & Rental API
Endpoints for building decentralized exchange (OTC) and asset rental platforms.
Please contact sales for full documentation on these modules.
4. Error Codes
| HTTP Status | Code | Description |
|---|---|---|
| 400 | INVALID_REQUEST | Bad request. Missing required parameters or invalid syntax. |
| 401 | UNAUTHORIZED | Authentication failed. Invalid or expired API Key. |
| 404 | NOT_FOUND | The requested resource could not be found. |
| 429 | RATE_LIMIT | Too many requests. Quota exceeded. |
| 500 | SERVER_ERROR | Internal server error. Please contact support. |
4.1 Standard Messages
Request completed successfully.– 200 OK.Internal Server Error.– Unexpected failure. Check server logs or status page.Service not found.– The requested endpoint URI is invalid.
4.2 Auth & Throttling Messages
-
●
Invalid API Key.
The key is missing from the header, malformed, or has been revoked. -
●
Minute limit exceeded.
You have exceeded the per-minute request quota (60 req/min). -
●
Daily limit exceeded.
You have exceeded the daily request quota (50,000 req/day). -
●
Service not enabled.
Your API Key does not have permission to access this specific endpoint.
4.3 Domain Specific Errors (Saju)
-
ℹ️
invalid birth date format
Must beyyyy-MM-dd HH:mm:ss. Check for the 'T' separator or spacing. -
ℹ️
gender must be 'male' or 'female'
Case-sensitive. Only 'male' or 'female' strings are accepted. -
ℹ️
invalid timezone
Thecityparameter does not map to a valid IANA timezone.
5. Rate Limits & Quotas
To maintain high availability and performance stability, API usage is capped on a per-key basis. We enforce both Burst Limits (short-term) and Daily Quotas (long-term).
⚠️ Handling Rate Limit Errors
If you exceed these limits, the API will return a 429 Too Many Requests status.
Clients should handle this gracefully using an Exponential Backoff strategy.
Need higher throughput for a production launch? Contact Sales to upgrade your quota.
6. FAQ
What is the pricing model? ▼
We offer a Free Tier (first 100 requests) for testing. For production, we use a usage-based pricing model (approx. $0.01 - $0.10 per call) or fixed monthly Enterprise contracts.
Can I increase my Rate Limits? ▼
Yes. The default limit (60 req/min) is sufficient for most startups. If you expect high traffic spikes or batch processing needs, please contact support to upgrade to an Enterprise Plan.
What SDKs or languages are supported? ▼
Our API is language-agnostic. It returns standard RESTful JSON, compatible with any HTTP client in Python, Node.js, Go, Java, PHP, Ruby, etc.
How should I handle errors? ▼
For 429 (Rate Limit) or 5xx (Server) errors, we strongly recommend implementing Exponential Backoff (e.g., retry after 1s, then 2s, then 4s) with a maximum of 3 retries.
How do I get a Test API Key? ▼
Submit your request via the API key form. Our team reviews requests manually and usually replies within 1-2 business days.
7. Developer Support
Stuck on integration?
Our engineering team is available to assist with API integration, debugging, and best practices.
For critical issues, please include your API Key (partial) and request details.