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
Four Pillars (Natal Chart)
The core chart derived from birth data. Contains Year, Month, Day, and Hour pillars, translated into Element + Animal format (e.g., Wood Dragon).
Archetypes (Ten Gods)
10 distinct personality personas (e.g., The Scholar, The Leader) derived from the interaction between your 'Self' element and other elements.
Elemental Balance
Percentage breakdown of the 5 elements (Wood, Fire, Earth, Metal, Water) in your chart. Used to determine strengths and health tendencies.
Balancing Element (Yongshin)
The specific element required to harmonize your chart. This is critical for generating lucky colors, directions, and advice.
12 Life Stages (Twelve Growth)
Describes the energy lifecycle of each pillar (e.g., Birth, Peak, Decay). Indicates the potential power of a specific time period.
Luck Cycles (Daewoon)
10-year environmental trends that influence your life path. Essential for long-term forecasting.
Lucky Factors
Actionable recommendations including lucky colors (CSS hex codes), directions, and numbers based on your Balancing Element.
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? ▼
Please fill out the API Access Request Form. Our team reviews requests manually to prevent abuse and typically issues keys within 24 hours.
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.