Natal Chart API: Birth Chart Calculations for Developers

What does the Natal Chart API do?

You give the Natal Chart API three inputs - date, time, and place of birth - and it returns a complete birth chart. That includes planetary positions, house cusps, aspects, the Ascendant, the Midheaven, and a renderable wheel image. The output is structured JSON, ready to render in any frontend.

The API sits inside the Western astrology suite of DivineAPI. You get REST endpoints for every building block of a natal chart: planetary positions, house cusps, the aspect table, the natal wheel image, plus supplementary objects like Arabic Lots, asteroids, and fixed stars. The wheel chart adds a base64-encoded SVG so you can drop the chart straight into an <img> tag. It is built for developers integrating astrology features into web and mobile apps, white-label platforms, dashboards, and PDF report generators.

What problems does this API solve?

You have a date, a time, and a city. Turning that into a usable birth chart on your own means an ephemeris, a house-system implementation, an aspect engine with orb tuning, and historically-correct timezone handling. The Natal Chart API removes that whole stack. You POST birth data, you get back a calculated chart.

To build it yourself you would license or port an ephemeris library, validate it across edge cases like polar latitudes, build an aspect engine, and maintain timezone tables that shift every time a government changes DST rules. Six-month build for one engineer, and most teams never finish.

The API does the work. Swiss Ephemeris runs the calculation - the same engine professional astrology software has used for decades, sourced from NASA JPL data. You get arc-second precision on every planet position. Twenty-plus house systems are exposed via a single parameter (Placidus, Koch, Regiomontanus, Campanus, Equal, Whole Sign, Porphyry, Topocentric, Alcabitius, Gauquelin Sectors).

What inputs does the Natal Chart API need?

You pass birth data: full name, date components (day, month, year), time components (hour, minute, second), gender, place of birth as free text, decimal latitude and longitude, and timezone offset from UTC. Optional parameters control language, house system, aspect filtering, and orb mode. Authentication uses a Bearer token plus an api_key field in the body.

Mandatory parameters:

Optional parameters (varies per endpoint):

The wheel chart endpoint adds styling options: wheel_color, text_color, glyph style, and twelve graphic layout presets. Authentication carries through every request via the Bearer token.

How is the API response structured?

Every endpoint returns the same envelope: a top-level success flag (1 = OK) and a data block carrying the calculated payload. Errors return success = 0 with a descriptive message. Rate-limited requests get HTTP 429. The shape of data varies by endpoint, but the wrapper stays consistent across the whole catalog.

You can write a single response handler that unwraps every Natal endpoint. The data block is where the variation lives. Planetary Positions returns an array of celestial bodies. House Cusps returns twelve houses plus the Ascendant, Midheaven, and Vertex. The Aspect Table returns pairwise aspect objects. The Natal Wheel Chart adds an SVG string and a base64-encoded image alongside the structured chart description.

What do the core output objects look like?

You are rendering a chart. You need three object shapes from the response: a planetary body object (sixteen per chart), a house cusp object (twelve plus three derived points), and an aspect object (one per pairwise aspect). Field names stay consistent across endpoints, so you write one renderer and reuse it.

Planetary body (Planetary Positions, transit endpoints):

A full natal call returns sixteen points: Sun, Moon, the eight planets, lunar nodes (mean or true), Chiron, Midheaven, Ascendant, Part of Fortune, and Lilith.

House cusp (House Cusps endpoint):

Aspect object (Aspect Table endpoint):

What does a real API response look like?

Below is a trimmed response from the Planetary Positions endpoint for a sample birth (24 May 2023, 14:40:43 IST, New Delhi). The full response includes sixteen celestial points. The slice below shows the Ascendant, Sun, Moon, and Mars to keep the example readable.

{
  "success": 1,
  "data": [
    {
      "name": "Ascendant",
      "full_degree": "185.7194554",
      "sign": "Libra",
      "sign_no": 7,
      "longitude": "5:43:10",
      "speed": "317.7084874",
      "is_retro": "false",
      "house": 1,
      "element": "Air",
      "modality": "Cardinal"
    },
    {
      "name": "Sun",
      "full_degree": "62.9674391",
      "sign": "Gemini",
      "sign_no": 3,
      "longitude": "2:58:3",
      "speed": "0.9614368",
      "is_retro": "false",
      "house": 8,
      "element": "Air",
      "modality": "Mutable"
    },
    {
      "name": "Moon",
      "full_degree": "117.3008709",
      "sign": "Cancer",
      "sign_no": 4,
      "longitude": "27:18:3",
      "speed": "12.0107241",
      "is_retro": "false",
      "house": 10,
      "element": "Water",
      "modality": "Cardinal"
    },
    {
      "name": "Mars",
      "full_degree": "122.1365708",
      "sign": "Leo",
      "sign_no": 5,
      "longitude": "2:8:12",
      "speed": "0.5736328",
      "is_retro": "false",
      "house": 10,
      "element": "Fire",
      "modality": "Fixed"
    }
  ]
}

What can you build with the Natal Chart API?

You can ship astrology dashboards, white-label personality reports, compatibility tools, transit-based content engines, onboarding widgets, and esoteric calculators. The API gives you the calculation primitives. The experience layer is yours.

1. Astrology dashboards. Render the Natal Wheel Chart SVG, overlay aspect lines, and pull interpretation panels from the report endpoints.

2. White-label personality reports. Combine Planetary Positions, House Cusps, the Aspect Table, and the General Sign / General House report endpoints to generate per-user writeups in twelve languages.

3. Compatibility tools. Pair two charts via the Synastry endpoints. Composite endpoints merge two natives into a single derived chart.

4. Onboarding widgets. Natal Insights gives you element distribution, modality balance, and hemisphere dominance. A snapshot for first-touch UI, not a full chart.

5. Content engines. Store a user's natal chart once, then call Daily, Weekly, or Monthly Transit each cycle. You get personalised forecasts without recomputing the natal.

6. Esoteric tooling. Arabic Lots, Asteroid Positions, Fixed Stars Details, and Planetary Midpoints extend the chart into Hellenistic and modern advanced features.

How accurate is the calculation?

You are quoting specific degrees and signs to your users, so accuracy is non-negotiable. The Natal Chart API runs on Swiss Ephemeris, sourced from NASA JPL ephemeris data. You get arc-second precision on every planet position across the supported date range. More than twenty house systems are exposed via the house_system parameter, with Placidus as the default.

Timezone handling is per-request via the tzone parameter. You pass the offset from UTC; the API does not infer DST or historical offsets, so feed it the correct value for the birth datetime (e.g. 5.5 for IST).

How does this API fit within DivineAPI?

You are picking an entry point for Western astrology features. The Natal Chart API is that entry point. It pairs with the Synastry endpoints for relationship work, Composite endpoints for derived two-person charts, and the Transit endpoints (Daily, Weekly, Monthly, Full, Basic) for time-based predictions that overlay onto a stored natal chart.

Teams building Indian astrology features cross-reference the Indian API suite (Vimshottari Dashas, Vedic chart systems, Panchang). Frontend teams combine the wheel chart with the PDF Report API for downloadable client deliverables. A single integration pattern scales across the catalog: same auth header, same request envelope, same success plus data response shape on every endpoint.

How does this compare to alternatives?

You are evaluating astrology APIs for your product. Many providers ship them, and the comparison usually comes down to four axes: calculation engine, house-system coverage, response shape, and language support. The Natal Chart API exposes the underlying calculation parameters directly - orb mode, aspect filtering, node type, and twenty-plus house systems - so you control the chart instead of accepting whatever the API decides.

Some alternative implementations wrap thin Swiss Ephemeris bindings without exposing tuning options. Others return interpretation-only HTML, which works for an embedded widget but breaks custom UI rendering. The Natal Chart API returns structured JSON with consistent field names across the catalog, and twelve interface languages ship via the lan parameter without a separate translation pipeline.

How do you access and integrate the API?

Access is REST POST. Authentication uses a Bearer token in the Authorization header alongside an api_key field in the request body, both issued from the DivineAPI dashboard. Responses are JSON with a consistent success plus data envelope. Standard HTTP codes apply: 200 OK on success, 429 Too Many Requests when rate-limited, 4xx with descriptive messages on validation errors.

For platform integrations, DivineAPI ships a WordPress plugin, a Shopify app, a Wix integration, and embeddable JavaScript widgets. The live documentation includes code examples in cURL, Node.js, jQuery AJAX, and Python.

Summary

The Natal Chart API turns three inputs (date, time, place of birth) into a complete birth chart: planetary positions, house cusps, aspects, and a renderable wheel image. It runs on Swiss Ephemeris with NASA JPL data underneath, exposes more than twenty house systems and twelve interface languages, and returns structured JSON ready for custom rendering. You ship astrology dashboards, compatibility tools, transit-based content engines, and PDF report pipelines without owning the calculation infrastructure.