Ablecity 로고
v2.2 Updated (Jan 2026)

Ablecity API Reference

Welcome to the documentation for Ablecity's suite of APIs. Build scalable platforms for Asian Astrology (Saju), Social Discovery, and Asset Rental backed by our 99.99% uptime SLA and sub-300ms global latency infrastructure.

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 AI

Generates 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.

GET Request Example
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

NewYork LosAngeles Chicago Toronto Vancouver SanFrancisco Seattle Boston Washington London Paris Berlin Rome Madrid Amsterdam Sydney Melbourne Singapore HongKong Tokyo Seoul (Default)

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).

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": ["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 be yyyy-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
    The city parameter 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).

Burst Limit Per Minute
60 reqs/min
Daily Quota Per Day
50,000 reqs/day

⚠️ 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.

✉️ Contact Engineering

Ablecity (Seoul HQ)

Managing Partner: H.KWON
Email: [email protected]

© 2026 Ablecity. All rights reserved.