Natal Chart API
Turn a birth date, local time and location into a structured birth chart. Keep calculated positions and houses in your data layer, then use the separate localized interpretation to build your own reading experience.
POST /v1/astrology/natal50,000 credits per monthly allowance · no trial · no automatic overage charges. Plan details ↗
What this API provides.
Calculate natal charts with tropical planets, ascendant, houses, aspects and optional original SVG. See a real JSON response before subscribing.
Ascendant, midheaven and whole-sign, equal or Placidus houses
Five major aspect types with explicit separations and orbs
Optional original SVG generated from the numerical chart
Send
- Birth date and local clock time, IANA time zone, latitude and longitude
- An explicit fold of 0 or 1 for an ambiguous daylight-saving time
- Optional house_system, locale and include: ["svg"]
Receive
- planets: longitude, sign, degree, speed, retrograde and house
- houses: system, cusps, ascendant and midheaven
- aspects, warnings, calculation profile and fact-linked interpretation
See the calculated chart.
The original renderer uses the exact positions in this example. These are computed charts, not stock diagrams. JSON remains the authoritative source.
Real input. Real output.
Precomputed by the actual calculation engine and response formatter, using synthetic example data. No purchased access or paid provider call was needed.
{
"locale": "en",
"birth": {
"date": "1990-05-21",
"time": "14:30:00",
"timezone": "Europe/Madrid",
"latitude": 40.4168,
"longitude": -3.7038
},
"include": [
"svg"
]
}{
"request_id": "1299830cdfe3ed0bb78549f7be780e77",
"api_version": "v1",
"locale": "en",
"data": {
"at": "1990-05-21T12:30:00Z",
"birth_time_known": true,
"planets": {
"sun": {
"longitude": 60.19554186,
"latitude": 0.00015523,
"distance_au": 1.0121680489,
"sign": "gemini"
},
"moon": {
"longitude": 18.08236232,
"latitude": 4.67747445,
"distance_au": 0.0024294565,
"sign": "aries"
},
"mercury": {
"longitude": 38.664821,
"latitude": -3.37497387,
"distance_au": 0.6700853983,
"sign": "taurus"
},
"venus": {
"longitude": 19.7137408,
"latitude": -1.9474912,
"distance_au": 1.0821255365,
"sign": "aries"
},
"mars": {
"longitude": 352.79743592,
"latitude": -1.79049776,
"distance_au": 1.4212788567,
"sign": "pisces"
},
"jupiter": {
"longitude": 100.70255878,
"latitude": 0.15100962,
"distance_au": 5.9296233345,
"sign": "cancer"
},
"saturn": {
"longitude": 295.11911348,
"latitude": 0.14808899,
"distance_au": 9.3994642274,
"sign": "capricorn"
}
},
"houses": {
"system": "whole_sign",
"ascendant": 158.31543091,
"midheaven": 64.64823285,
"cusps": [
150,
180
]
},
"aspects": [
{
"body1": "mercury",
"body2": "uranus",
"aspect": "trine",
"angle": 120
},
{
"body1": "moon",
"body2": "venus",
"aspect": "conjunction",
"angle": 0
}
],
"warnings": []
},
"interpretation": {
"locale": "en",
"kind": "astrology/natal",
"disclaimer": "Symbolic reflection, not a verified prediction or professional advice.",
"coverage": {
"total_facts": 26,
"selected_facts": 26,
"omitted_count": 0,
"selection_method": "all-source-facts-v1",
"full_numeric_data_unchanged": true
},
"method": {
"engine": "celestack-original-rules-v1",
"corpus": "celestack-original-compositional-v1",
"corpus_version": "2026-11-17.2",
"fallback_locale": null,
"editorial_status": "agent-authored; independent linguistic review pending",
"predictive_validity": "symbolic interpretations are not scientifically validated predictions",
"chinese_solar_terms": "numeric calendar output only; no rule paragraphs in this corpus"
},
"items": [
{
"fact_id": "astrology/natal.planets.sun",
"title": "Natal chart · Sun · Gemini",
"text": "Context: Natal chart. Sun · Gemini · 0.19554° within the sign. Zodiac: tropical. Symbolic focus: self-expression and direction. Ask a new question and compare more than one perspective. House 10: public contribution and long-term aims. Apply the reflection to a real situation rather than a fixed outcome. Reference time: 1990-05-21T12:30:00Z.",
"source": {
"longitude": 60.19554186,
"latitude": 0.00015523,
"distance_au": 1.0121680489,
"sign": "gemini",
"sign_degree": 0.19554186,
"speed_deg_per_day": 0.96229929,
"retrograde": false,
"house": 10,
"id": "astrology/natal.planets.sun",
"type": "astro_placement",
"planet": "sun",
"frame": "tropical",
"at": "1990-05-21T12:30:00Z",
"context": [
"natal_chart"
]
}
}
]
},
"warnings": [],
"credits_used": 5
}The response preview selects whole fields and array entries for readability; no numeric values have been replaced. The full download preserves all fields, arrays and interpretation. The request_id is synthetic, and credits_used shows the configured successful-request cost; no credits were consumed.
cURL request — use your own API key and a new idempotency key
curl --request POST 'https://api.celestackapi.com/v1/astrology/natal' \
+ --header 'Authorization: Bearer YOUR_API_KEY' \
+ --header 'Content-Type: application/json' \
+ --header 'Idempotency-Key: natal-chart-api-example-001' \
+ --data '{
"locale": "en",
"birth": {
"date": "1990-05-21",
"time": "14:30:00",
"timezone": "Europe/Madrid",
"latitude": 40.4168,
"longitude": -3.7038
},
"include": [
"svg"
]
}'Example computed 2026-11-17. Full fixture manifest, engine versions and SHA-256 checksums ↗
Ways to use it.
- Birth-chart onboarding in an astrology app
- Personalized chart pages with a developer-controlled design
- Localized readings backed by the same numerical chart
12 response locales
English, Ukrainian, Japanese, Spanish, French, German, Portuguese, Arabic, Italian, Hindi, Chinese and Korean.
Calculation values remain language-independent. Localized rule text is agent-authored; independent native-language review remains pending. Machine-readable field names stay stable.
Limits and interpretation.
- The Western profile is tropical, apparent geocentric ecliptic of date, using JPL DE440s.
- Unknown birth time does not produce a fabricated timed chart. Time-sensitive fields are omitted with warnings.
- Dates are supported from 1900 through 2100. Placidus may be unavailable at high latitudes; there is no silent house-system substitution.
Interpretive content is for symbolic reflection and entertainment. It is not a verified personal prediction or professional advice. Read the API conventions ↗
Choose your billing.
Both options include 50,000 credits per monthly allowance, resetting monthly. No trial and no automatic overage. Custom needs use a contact form.
Saved results: 7-day retention, up to 128 MiB per organization on this initial shared deployment, with a 512 MiB shared retained-result limit. Capacity can return a temporary error; there are no automatic extra charges. Production artifacts have separate retention. All usage and resource limits ↗. Checkout availability is shown in your account.
Frequently asked questions.
Can I get both JSON and a chart image?
Yes. Add "svg" to include for an original chart in data.svg. The preview below is rendered from the exact sample positions. PDF and PNG are separate asynchronous report jobs.
Which house systems are supported?
Use whole_sign, equal or placidus. Whole sign is the default. The chosen system is returned explicitly, and an unavailable Placidus result is an error rather than a substituted system.
What happens if the birth time is unknown?
Send null or omit birth.time. The engine preserves uncertainty and omits time-sensitive chart results instead of choosing an invented birth time.
What does access cost?
Access is USD 39.99 per month or USD 199 billed annually, with no trial. Both billing options provide 50,000 credits per monthly allowance. 5 credits per successful request or job. Daily credit, attempt, rate and resource limits apply. There are no automatic overage charges.