TradAstro Developer API

HTTP JSON APIs for classical chart calculation and theme interpretations. Create an API key on the Open Platform after signing up. Usage is metered in weighted monthly points.

Product UI routes under /api/*/compute are for the website only. **Integrations must use /api/v1/*.**

Table of contents

Quick start

curl -s -X POST https://tradastro.com/api/v1/natal \
  -H "Authorization: Bearer ta_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1990-05-15T14:30:00",
    "timezone": "Asia/Shanghai",
    "latitude": 31.23,
    "longitude": 121.47,
    "house_system": "regiomontanus",
    "terms": "egyptian"
  }'

Success responses are JSON (e.g. { "snapshot": { ... } }) and include monthly quota headers (see below).

Authentication & keys

Headers (either form)

Authorization: Bearer ta_live_...

or

X-Api-Key: ta_live_...

If both are present, X-Api-Key wins. Keys always start with ta_live_.

Key lifecycle

Monthly quota is attached to the account, not to a single key. All keys under one account share the same monthly points pool.

Quota, weights & rate limits

Monthly points (account-level)

Weights

Per-minute rate limit (per key)

Response headers (successful 2xx only)

These headers reflect the monthly account quota (not the per-minute limiter):

Error responses usually omit these headers. There is no Retry-After today.

Plans & billing

Conventions

Shared objects

Person

Used at the top level or nested as natal / chart_a / chart_b:

{
  "datetime": "1990-05-15T14:30:00",
  "timezone": "Asia/Shanghai",
  "latitude": 31.23,
  "longitude": 121.47,
  "label": "A",
  "place_name": "Shanghai"
}

aspect_settings (optional)

Supported on most compute endpoints:

Omit to use engine defaults.

Endpoint reference

Unless noted, all are authenticated POST endpoints returning JSON.

Samples below are abbreviated: arrays usually keep 1–2 items; values are illustrative. Treat live responses as source of truth. Optional fields may appear in later engine versions.

POST /natal — Natal chart · weight 1

Classical natal: planets, houses, aspects, dignities, lots, firdaria, profections, and more.

Body: Person fields + optional house_system, terms, aspect_settings.

curl -s -X POST https://tradastro.com/api/v1/natal \
  -H "Authorization: Bearer ta_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1990-05-15T14:30:00",
    "timezone": "Asia/Shanghai",
    "latitude": 31.23,
    "longitude": 121.47,
    "house_system": "regiomontanus",
    "terms": "egyptian"
  }'

Response: { "snapshot": NatalSnapshot }

{
  "snapshot": {
    "meta": {},
    "label": "Natal",
    "birth": {
      "datetime": "1990-05-15T14:30:00",
      "timezone": "Asia/Shanghai"
    },
    "settings": {
      "house_system": "regiomontanus",
      "aspect_matrix_order": ["sun", "moon", "mercury"]
    },
    "angles": { "asc": 182.45, "mc": 97.12 },
    "chart_ruler": { "planet": "venus" },
    "houses": [
      { "house": 1, "longitude": 182.45, "sign": "libra" }
    ],
    "planets": [
      {
        "id": "sun",
        "symbol": "☉",
        "longitude": 54.32,
        "sign": "taurus",
        "sign_symbol": "♉",
        "degree": 24,
        "minute": 19,
        "position": "24°19′ Taurus",
        "house": 8,
        "house_whole_sign": 8,
        "houses_ruled": [11],
        "houses_exalted": [],
        "speed": 0.96,
        "retrograde": false,
        "dignities": { "domicile": false, "exaltation": false },
        "dignity_score": null,
        "sect": "day",
        "orientality": null,
        "speed_class": "average",
        "solar_phase": null
      }
    ],
    "aspects": [
      {
        "body_a": "sun",
        "body_b": "moon",
        "type": "trine",
        "angle": 120,
        "orb": 1.42,
        "orb_deg": 1,
        "orb_min": 25,
        "orb_display": "1°25′",
        "applying": true,
        "separating": false,
        "phase": "A"
      }
    ],
    "lots": [{ "id": "fortune", "longitude": 210.1, "sign": "scorpio", "house": 2 }],
    "features": [],
    "firdaria": {
      "sect": "day",
      "current": { "major_lord": "venus", "sub_lord": "mercury" }
    },
    "profections": {
      "method": "annual",
      "current": { "house": 1, "lord": "venus", "sign": "libra" }
    }
  }
}

Optional extras may include house_scores, core_life_themes, personality_profile, and planet condition_summary / power.

POST /synastry — Synastry · weight 2

Two-chart synastry (cross aspects and relationship-oriented results).

curl -s -X POST https://tradastro.com/api/v1/synastry \
  -H "Authorization: Bearer ta_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "chart_a": {
      "datetime": "1990-05-15T14:30:00",
      "timezone": "Asia/Shanghai",
      "latitude": 31.23,
      "longitude": 121.47
    },
    "chart_b": {
      "datetime": "1992-08-20T09:00:00",
      "timezone": "Asia/Shanghai",
      "latitude": 39.90,
      "longitude": 116.40
    },
    "inner": "a"
  }'

Sample response:

{
  "snapshot": {
    "meta": {},
    "inner": "a",
    "chart_a": {
      "label": "Person A",
      "angles": { "asc": 182.45, "mc": 97.12 },
      "planets": [{ "id": "venus", "sign": "gemini", "house": 9 }],
      "houses": []
    },
    "chart_b": {
      "label": "Person B",
      "angles": { "asc": 24.1, "mc": 278.6 },
      "planets": [{ "id": "mars", "sign": "aries", "house": 1 }],
      "houses": []
    },
    "cross_aspects": [
      {
        "inner_body": "venus",
        "outer_body": "mars",
        "type": "trine",
        "angle": 120,
        "orb": 1.2,
        "orb_deg": 1,
        "orb_min": 12,
        "orb_display": "1°12′",
        "applying": true,
        "separating": false,
        "phase": "A"
      }
    ],
    "relationship_scoring": {
      "version": "current",
      "symmetric": {
        "attraction": { "score": 78, "label": "Clear attraction" },
        "stability": { "score": 64, "label": "Fairly stable" },
        "tension": { "score": 38, "label": "Moderate tension" },
        "compatibility": { "score": 72, "label": "Good fit" }
      },
      "directional": {
        "a_to_b": { "score": 70, "label": "Clear investment" },
        "b_to_a": { "score": 66, "label": "Steady response" }
      },
      "summary": {
        "relationship_type": {
          "id": "balanced_attraction",
          "label": "Attraction with stability",
          "reasons": ["Interaction feels natural and attention tends to persist."]
        },
        "highlights": ["Emotional expression is often received well."],
        "risks": ["Pace differences may show up under pressure."],
        "suggestions": ["Keep both direct communication and personal space."]
      }
    },
    "settings": {
      "house_system": "regiomontanus",
      "terms": "egyptian",
      "inner_label": "Person A",
      "outer_label": "Person B",
      "include_outer_planets": true
    }
  }
}

relationship_scoring may be absent. Public responses expose scores and qualitative labels, not formula internals.

POST /composite — Composite · weight 2

Davison composite with structure-oriented results. Same body as synastry without inner.

Sample response:

{
  "snapshot": {
    "meta": {},
    "chart": {
      "label": "Davison Composite",
      "angles": { "asc": 113.2, "mc": 15.8 },
      "planets": [{ "id": "sun", "sign": "cancer", "house": 7 }],
      "aspects": [],
      "houses": [],
      "lots": [],
      "features": []
    },
    "chart_a": { "label": "Person A", "angles": { "asc": 182.45, "mc": 97.12 }, "planets": [] },
    "chart_b": { "label": "Person B", "angles": { "asc": 24.1, "mc": 278.6 }, "planets": [] },
    "composite_scoring": {
      "version": "current",
      "indices": {
        "structure": { "score": 74, "label": "Solid structure" },
        "attraction": { "score": 80, "label": "Clear attraction" },
        "stability": { "score": 68, "label": "Fairly stable" },
        "conflict": { "score": 35, "label": "Manageable conflict" },
        "total": { "score": 73, "label": "Overall harmony" }
      },
      "summary": {
        "relationship_type": {
          "id": "stable_growth",
          "label": "Steady growth",
          "reasons": ["The bond has room for ongoing construction."]
        },
        "highlights": ["Shared goals form relatively easily."],
        "risks": ["Major decisions may need more alignment."],
        "suggestions": ["Clarify long-term plans and responsibility boundaries."]
      }
    },
    "settings": {
      "house_system": "regiomontanus",
      "terms": "egyptian",
      "method": "davison",
      "chart_a_label": "Person A",
      "chart_b_label": "Person B",
      "composite_label": "Davison Composite",
      "include_outer_planets": true,
      "davison": {
        "datetime": "1991-07-02T23:45:00",
        "timezone": "UTC",
        "latitude": 35.565,
        "longitude": 118.935
      }
    }
  }
}

POST /transit — Transits · weight 1

{
  "natal": { "datetime": "1990-05-15T14:30:00", "timezone": "Asia/Shanghai", "latitude": 31.23, "longitude": 121.47 },
  "transit_datetime": "2026-07-18T12:00:00",
  "transit_timezone": "Asia/Shanghai"
}

Sample response (transit chart in transit; cross aspects in cross_aspects):

{
  "snapshot": {
    "meta": {},
    "natal": {
      "label": "Natal",
      "angles": { "asc": 182.45, "mc": 97.12 },
      "planets": [{ "id": "sun", "sign": "taurus", "house": 8 }]
    },
    "transit": {
      "label": "Transits 2026-07-18",
      "angles": { "asc": 210.3, "mc": 124.8 },
      "planets": [{ "id": "jupiter", "sign": "cancer", "house": 10, "retrograde": false }]
    },
    "cross_aspects": [
      {
        "inner_body": "sun",
        "outer_body": "jupiter",
        "type": "sextile",
        "angle": 60,
        "orb": 0.75,
        "orb_deg": 0,
        "orb_min": 45,
        "orb_display": "0°45′",
        "applying": true,
        "separating": false,
        "phase": "A"
      }
    ],
    "settings": {
      "house_system": "regiomontanus",
      "terms": "egyptian",
      "natal_label": "Natal",
      "transit_label": "Transits 2026-07-18",
      "transit_datetime": "2026-07-18T12:00:00",
      "transit_timezone": "Asia/Shanghai",
      "include_outer_planets": true,
      "include_minor_aspects": false
    }
  }
}

Directed techniques (shared request body)

These five endpoints share one request shape:

{
  "natal": { "datetime": "1990-05-15T14:30:00", "timezone": "Asia/Shanghai", "latitude": 31.23, "longitude": 121.47 },
  "directed_datetime": "2026-07-18T12:00:00",
  "directed_timezone": "Asia/Shanghai"
}

#### POST /solar-arc — Solar arc · weight 1

Same envelope as /transit (directed chart in transit). settings may include solar_arc_degrees and progressed_datetime.

{
  "snapshot": {
    "natal": { "label": "Natal", "angles": { "asc": 182.45, "mc": 97.12 }, "planets": [] },
    "transit": { "label": "Solar Arc 2026", "angles": { "asc": 218.1, "mc": 132.7 }, "planets": [] },
    "cross_aspects": [],
    "settings": {
      "house_system": "regiomontanus",
      "transit_datetime": "2026-07-18T12:00:00",
      "transit_timezone": "Asia/Shanghai",
      "solar_arc_degrees": 36.18,
      "progressed_datetime": "1990-06-20T08:12:00"
    }
  }
}

#### POST /secondary-progressions — Secondary (single) · weight 1

{
  "snapshot": {
    "meta": {},
    "natal_ref": {
      "label": "Natal",
      "birth": { "datetime": "1990-05-15T14:30:00", "timezone": "Asia/Shanghai" },
      "place_name": "Shanghai"
    },
    "chart": {
      "label": "Secondary Progressions 2026",
      "angles": { "asc": 220.4, "mc": 135.2 },
      "planets": [{ "id": "moon", "sign": "leo", "house": 9 }],
      "aspects": [],
      "houses": []
    },
    "settings": {
      "house_system": "regiomontanus",
      "terms": "egyptian",
      "directed_datetime": "2026-07-18T12:00:00",
      "directed_timezone": "Asia/Shanghai",
      "progressed_datetime": "1990-06-20T08:12:00",
      "age_years": 36.18
    }
  }
}

#### POST /secondary-progressions/comparison — Secondary vs natal · weight 1

Same shape as /transit (progressed chart in transit); settings includes age_years, progressed_datetime, etc.

#### POST /tertiary-progressions — Tertiary (single) · weight 1

Same shape as secondary single; settings may also include age_lunar_months.

{
  "snapshot": {
    "natal_ref": { "label": "Natal", "birth": {}, "place_name": "Shanghai" },
    "chart": {
      "label": "Tertiary Progressions 2026",
      "angles": { "asc": 248.7, "mc": 162.3 },
      "planets": []
    },
    "settings": {
      "directed_datetime": "2026-07-18T12:00:00",
      "age_lunar_months": 447.5,
      "age_years": 36.18
    }
  }
}

#### POST /tertiary-progressions/comparison — Tertiary vs natal · weight 1

Same shape as /transit; settings may include age_lunar_months and age_years.

POST /solar-return — Solar return · weight 1

{
  "natal": { "datetime": "1990-05-15T14:30:00", "timezone": "Asia/Shanghai", "latitude": 31.23, "longitude": 121.47 },
  "return_year": 2026,
  "return_latitude": 31.23,
  "return_longitude": 121.47,
  "return_timezone": "Asia/Shanghai"
}

Sample response:

{
  "snapshot": {
    "meta": {},
    "natal_ref": {
      "label": "Natal",
      "birth": {},
      "sun_longitude": 54.32,
      "place_name": "Shanghai"
    },
    "return_chart": {
      "label": "Solar Return 2026",
      "angles": { "asc": 143.8, "mc": 46.1 },
      "planets": [{ "id": "sun", "sign": "taurus", "house": 10 }],
      "aspects": [],
      "houses": []
    },
    "settings": {
      "return_year": 2026,
      "house_system": "regiomontanus",
      "terms": "egyptian",
      "exact_return_datetime": "2026-05-15T20:18:42+08:00",
      "return_timezone": "Asia/Shanghai",
      "next_return_datetime": "2027-05-16T02:06:00+08:00",
      "return_period_start": "2026-05-15T20:18:42+08:00",
      "return_period_end": "2027-05-16T02:06:00+08:00",
      "return_latitude": 31.23,
      "return_longitude": 121.47,
      "return_place_name": "Shanghai",
      "location_from_natal": false
    }
  }
}

POST /lunar-return — Lunar return · weight 1

Solar-return fields plus required return_month (1–12).

Sample response:

{
  "snapshot": {
    "natal_ref": {
      "label": "Natal",
      "moon_longitude": 287.9,
      "place_name": "Shanghai"
    },
    "return_chart": {
      "label": "Lunar Return July 2026",
      "angles": { "asc": 88.4, "mc": 351.2 },
      "planets": [{ "id": "moon", "sign": "capricorn", "house": 5 }]
    },
    "settings": {
      "return_year": 2026,
      "return_month": 7,
      "natal_moon_longitude": 287.9,
      "exact_return_datetime": "2026-07-09T14:42:00+08:00",
      "next_return_datetime": "2026-08-05T23:10:00+08:00",
      "return_period_start": "2026-07-09T14:42:00+08:00",
      "return_period_end": "2026-08-05T23:10:00+08:00",
      "return_timezone": "Asia/Shanghai"
    }
  }
}

POST /timing/focus — Life-topic timing · weight 3

May be slow (up to ~120s).

{
  "topic": "relationship",
  "natal": { "datetime": "1990-05-15T14:30:00", "timezone": "Asia/Shanghai", "latitude": 31.23, "longitude": 121.47 },
  "at_date": "2026-07-18",
  "locale": "en"
}

Sample response (localized composition; raw facts removed):

{
  "snapshot": {
    "topic": "relationship",
    "at_date": "2026-07-18",
    "headline": "Relationship themes show clearer forward windows ahead.",
    "paragraphs": [
      "Use timing windows as trend signals alongside real-world choices.",
      "This phase favors gradually clarifying how both people invest."
    ],
    "life_context": {
      "firdaria_period": { "lord": "venus", "start": "2024-03-10", "end": "2032-03-10" },
      "profection_year": { "house": 1, "lord": "venus", "start": "2026-05-15", "end": "2027-05-15" }
    },
    "windows": [
      {
        "start": "2026-09-03",
        "end": "2026-10-12",
        "strength": 82,
        "label": "Stronger window",
        "notes": ["Good for relationship confirmation and key conversations."]
      }
    ],
    "reasons": ["Interaction and commitment themes get clearer responses in this phase."],
    "risks": ["Avoid rushing expectations past practical pacing."]
  }
}

POST /electional/scan — Electional scan · weight 5

Slow (up to ~120s).

event_type: marriage, business_open, contract_sign, finance, travel, relocation, job_interview, medical_cosmetic.

Special errors: 502 l1_unavailable, 503 electional_not_ready.

Sample response (heatmap / hourly are long in production — abbreviated here):

{
  "snapshot": {
    "meta": {},
    "event_type": "marriage",
    "anchor_date": "2026-10-10",
    "location": {
      "timezone": "Asia/Shanghai",
      "latitude": 31.23,
      "longitude": 121.47,
      "place_name": "Shanghai"
    },
    "score_summary": {
      "best": 86,
      "median": 61,
      "veto_pct": 18.5,
      "candidates_15m": 1450,
      "windows": 4
    },
    "heatmap": [
      {
        "ts": "2026-10-09T10:00:00+08:00",
        "score": 82,
        "level": "excellent",
        "breakdown": { "natal_cross": 80, "final": 82 }
      }
    ],
    "hourly": [
      {
        "ts": "2026-10-09T10:00:00+08:00",
        "vetoed": false,
        "reasons": [],
        "score": 82,
        "level": "excellent",
        "breakdown": { "natal_cross": 80, "final": 82 }
      }
    ],
    "windows": [
      {
        "start": "2026-10-09T09:30:00+08:00",
        "end": "2026-10-09T11:15:00+08:00",
        "score": 86,
        "peak_ts": "2026-10-09T10:15:00+08:00",
        "breakdown": { "natal_cross": 84, "final": 86 },
        "notes": ["Conditions align well for a formal ceremony."],
        "warnings": []
      }
    ],
    "l1_summary": {
      "scan_start": "2026-09-25",
      "scan_end": "2026-10-25",
      "total_hours": 744,
      "veto_count": 138,
      "veto_pct": 18.5,
      "eclipse_blackout_dates": []
    }
  }
}

POST /horoscope/daily — Daily horoscope · weight 1

Sample response:

{
  "snapshot": {
    "meta": {},
    "natal_label": "Natal",
    "daily": {
      "date": "2026-07-18",
      "timezone": "Asia/Shanghai",
      "variant_seed": "2026-07-18:Natal",
      "focus": {
        "house": 10,
        "near_angle": "mc",
        "moon_sign": "virgo",
        "moon_dignity": "neutral"
      },
      "mood": {
        "level": "steady",
        "moon_dignity": "neutral",
        "aspect": {
          "outer_body": "moon",
          "inner_body": "venus",
          "type": "trine",
          "orb_deg": 1,
          "orb_min": 8,
          "applying": true
        }
      },
      "relations": {
        "level": "supportive",
        "aspect": null,
        "seventh_ruler": "mars"
      },
      "action": {
        "level": "favorable",
        "void_of_course": false,
        "profection_lord_hit": {
          "lord": "venus",
          "trigger": "jupiter",
          "type": "sextile",
          "strength": "strong"
        }
      },
      "risk_window": null
    }
  }
}

POST /horoscope/monthly — Monthly horoscope · weight 1

Sample response:

{
  "snapshot": {
    "meta": {},
    "natal_label": "Natal",
    "monthly": {
      "period_start": "2026-07-09T14:42:00+08:00",
      "period_end": "2026-08-05T23:10:00+08:00",
      "return_datetime": "2026-07-09T14:42:00+08:00",
      "variant_seed": "2026-07:Natal",
      "theme": {
        "lr_asc_in_natal_house": 10,
        "lr_moon_house": 3,
        "lr_chart_ruler": "mercury",
        "lr_chart_ruler_dignity": "neutral",
        "lr_moon_dignity": "strong"
      },
      "scores": {
        "career": { "value": 78, "max": 100, "factors": ["Career momentum feels clearer."] },
        "relationships": { "value": 66, "max": 100, "factors": ["Communication and response stay steadier."] }
      },
      "peak_days": [
        { "date": "2026-07-22", "signal": "Good day to push key conversations.", "weight": 0.86 }
      ]
    }
  }
}

scores keys are dynamic — do not hard-code only career / relationships.

Theme interpretations · weight 2

Body (one of): birth data (same as /natal) + optional format; or { "snapshot": <natal snapshot>, "format": "sections" }.

curl -s -X POST https://tradastro.com/api/v1/interpretations/love \
  -H "Authorization: Bearer ta_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1990-05-15T14:30:00",
    "timezone": "Asia/Shanghai",
    "latitude": 31.23,
    "longitude": 121.47,
    "format": "sections"
  }'

format: "sections" sample:

{
  "sections": [
    {
      "key": "love_overview",
      "title_zh": "Love overview",
      "paragraphs": ["You value steady responses in relationships and also need room for personal space."],
      "facts_zh": [],
      "tone": "positive"
    },
    {
      "key": "love_romance",
      "title_zh": "Romance and attraction",
      "paragraphs": ["Attraction expresses naturally; warmth usually builds through ongoing interaction."],
      "facts_zh": [],
      "tone": "neutral"
    }
  ]
}

format: "report" sample:

{
  "section": {
    "key": "love_fortune",
    "title_zh": "Love fortune",
    "paragraphs": [
      "【Love overview】",
      "You value steady responses in relationships and also need room for personal space.",
      "【Romance and attraction】",
      "Attraction expresses naturally; warmth usually builds through ongoing interaction."
    ],
    "facts_zh": [],
    "tone": "positive"
  }
}

Contract: facts_zh is always []; tone is positive / neutral / caution; paragraphs are conclusions only (no scoring rationale).

Response structure notes

Natal cores: angles, houses, planets, aspects, lots, firdaria, profections. Comparison-style directed techniques put the outer chart in transit (transits, solar arc, secondary/tertiary comparison). Composite uses chart + chart_a / chart_b. Returns use return_chart plus period timestamps.

Integration tip: call each target endpoint once and freeze the live JSON into client types; avoid depending on undocumented internal keys.

Errors

Examples:

{ "error": "invalid_input", "details": { "formErrors": [], "fieldErrors": { "datetime": ["Required"] } } }

{ "error": "quota_exceeded", "used": 2000, "quota": 2000 }

Catalog

No auth required:

GET https://tradastro.com/api/v1
GET https://tradastro.com/api/v1/catalog

Example shape:

{
  "version": "v1",
  "auth": ["Authorization: Bearer <api_key>", "X-Api-Key: <api_key>"],
  "endpoints": [
    {
      "method": "POST",
      "path": "/api/v1/natal",
      "weight": 1,
      "summary_zh": "...",
      "summary_en": "..."
    }
  ]
}

Versioning

Onboarding & FAQ

Suggested flow

FAQ

Q: Is monthly quota per key or per account?

A: Per account (shared across keys). The 60/min limit is per key.

Q: Can I pass a website chartId?

A: Not on public v1. Send full birth data, or reuse a natal snapshot for interpretations.

Q: How are synastry / interpretation scores calculated?

A: Public API does not expose scoring formulas or weight breakdowns — only product-facing scores and conclusions.

Q: Do you offer white-label / mini-program SDKs like some Chinese platforms?

A: Today we ship an HTTP JSON API; white-label and private deploy are available via email.

Q: What timeout should I use?

A: Seconds for most calls; set ≥ 120s for timing/focus and electional/scan.

Endpoint cheat sheet