---
title: "Render a natal SVG wheel"
method: POST
path: "/api/astro/natal-svg"
tags: ["Calculations"]
---

# Render a natal SVG wheel

`POST /api/astro/natal-svg`

## Request

- Base URL: `https://api.cosmicephemeris.com`
- URL: `https://api.cosmicephemeris.com/api/astro/natal-svg`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Additive current calculation. Strict request shape; unknown fields, explicit nulls, noncanonical enums and numeric coordinate strings return 400. Exact poles and ambiguous/nonexistent civil times are rejected. Numerical checks are not practitioner sign-off. Placidus, Porphyry, Meridian, Campanus, Regiomontanus, Alcabitius, Koch, Morinus, Topocentric, Sripati, and Vehlow are opt-in with explicit geometry rejection and no fallback; Regiomontanus, Alcabitius, Koch, Morinus, Topocentric, Sripati, and Vehlow remain calculation-only. An optional additional_points list renders only the selected Vertex/Antivertex, Equatorial Ascendant/Descendant, and/or sect-reversed Lots of Fortune/Spirit. Optional neutral aspect_profile presets (major, standard, extended) or a mutually exclusive custom aspects list render selected aspect geometry; omitting both preserves the original major-only SVG. Rendering crowding returns 400. Opt-in include_png returns a deterministic metadata-free PNG derived from the same internal SVG; omission or false preserves the predecessor response exactly. No uploaded image, SVG, URL or font is accepted. 

Each admitted request reserves one monthly usage unit before route validation or engine work; failed or timed-out admitted attempts are not refunded. Do not automatically retry.
Historical mode uses an explicit BCE/CE date object and UT1 conventions. Its response is the versioned historical envelope, not the modern UTC envelope. Read result for calculation fields and metadata for limits and uncertainty.

## Request body

- union
  - NatalSvgRequest: Supported server-rendered natal wheel with optional deterministic PNG export. Inputs are calculation settings only; no SVG/chart/URL/image/font uploads. aspect_profile and aspects are mutually exclusive; omission preserves the original major-only SVG. Ayanamsa applies only to sidereal; exact lowercase enum remains required if supplied. Dense labels that cannot fit safely are rejected with 400, not silently omitted.
    - `birth` CalculationBirthInput, required: Strict nested birth input; no unknown properties, nulls, booleans or numeric strings. Known civil time required; semantic date/DST/undefined-angle validation occurs on the server.
      - `date` string, date, required: Valid Gregorian YYYY-MM-DD local civil date, inclusive 1800-01-01 through 2200-12-31. Calendar validity and timezone conversion are checked by the server.
      - `time` string, required: HH:MM or HH:MM:SS; no offset in this field. Use timezone to select the civil-time zone.
      - `timezone` string: Valid IANA zone; UTC when omitted. Ambiguous and nonexistent civil times are rejected.
      - `lat` number, required
      - `lon` number, required
    - `zodiac` 'tropical' | 'sidereal'
    - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks'
    - `house_system` 'equal' | 'whole_sign' | 'placidus' | 'porphyry' | 'meridian' | 'campanus' | 'regiomontanus' | 'alcabitius' | 'koch' | 'morinus' | 'topocentric' | 'sripati' | 'vehlow' | 'horizon' | 'krusinski' | 'sunshine' | 'sunshine_alt' | 'savard' | 'pullen_sd' | 'pullen_sr' | 'carter' | 'apc' | 'equal_mc' | 'natural'
    - `theme` 'light' | 'dark' | 'monochrome'
    - `show_aspects` boolean
    - `include_png` boolean: When true, also returns a deterministic PNG derived only from this response's server-rendered SVG. Omission or false preserves the predecessor response exactly.
    - `additional_points` AdditionalChartPoint[]
    - `aspect_profile` 'major' | 'standard' | 'extended': Neutral preset name. major uses five Ptolemaic aspects; standard preserves the existing six-aspect natal-analysis default; extended admits all eleven documented geometric aspects.
    - `aspects` NatalAnalysisAspectOption[]: Custom unique aspect/orb options, mutually exclusive with aspect_profile.
      - `aspect` 'conjunction' | 'semisextile' | 'semisquare' | 'sextile' | 'quintile' | 'square' | 'trine' | 'sesquiquadrate' | 'biquintile' | 'quincunx' | 'opposition', required
      - `max_orb_degrees` number, required
  - HistoricalNatalSvgRequest: Explicit historical mode, 1000 BCE (BC)–2500 CE (AD). No year zero, implicit calendar, UTC or IANA zone. Preserve tool-specific mathematical, geographic and search limits; calendar/time conventions and estimated Delta-T are not certified historical accuracy.
    - `birth` HistoricalBirthInput, required
      - `date` HistoricalDate, required: Explicit civil date, 1000 BCE (BC)–2500 CE (AD); no year zero. Calendar validity is checked by the server. Available only on documented connected historical operations, with explicit UT1/fixed-offset conventions.
        - `year` integer, required
        - `era` 'BCE' | 'CE', required: Display BCE (BC) / CE (AD); API values remain BCE / CE. No year zero.
        - `month` integer, required
        - `day` integer, required
        - `calendar` 'proleptic_gregorian' | 'proleptic_julian', required: Explicit choice; applies the selected calendar rules throughout history without a regional adoption switch.
      - `time` string, required: Explicit HH:MM[:SS]; whole seconds only, no leap seconds. Normalized helper output includes seconds.
      - `timezone` string, required: Explicit UT1 or fixed offset UT1+/-HH:MM[:SS], within 14 hours. Local clock minus offset yields UT1, not UTC. No IANA timezone inference. Original offset spelling is preserved.
      - `lat` number, required
      - `lon` number, required
    - `zodiac` 'tropical' | 'sidereal'
    - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks'
    - `house_system` 'equal' | 'whole_sign' | 'placidus' | 'porphyry' | 'meridian' | 'campanus' | 'regiomontanus' | 'alcabitius' | 'koch' | 'morinus' | 'topocentric' | 'sripati' | 'vehlow' | 'horizon' | 'krusinski' | 'sunshine' | 'sunshine_alt' | 'savard' | 'pullen_sd' | 'pullen_sr' | 'carter' | 'apc' | 'equal_mc' | 'natural'
    - `theme` 'light' | 'dark' | 'monochrome'
    - `show_aspects` boolean
    - `include_png` boolean: When true, also returns a deterministic PNG derived only from this response's server-rendered SVG. Omission or false preserves the predecessor response exactly.
    - `additional_points` AdditionalChartPoint[]
    - `aspect_profile` 'major' | 'standard' | 'extended': Neutral preset name. major uses five Ptolemaic aspects; standard preserves the existing six-aspect natal-analysis default; extended admits all eleven documented geometric aspects.
    - `aspects` NatalAnalysisAspectOption[]: Custom unique aspect/orb options, mutually exclusive with aspect_profile.
      - `aspect` 'conjunction' | 'semisextile' | 'semisquare' | 'sextile' | 'quintile' | 'square' | 'trine' | 'sesquiquadrate' | 'biquintile' | 'quincunx' | 'opposition', required
      - `max_orb_degrees` number, required

## Response `200`

Successful calculation. Field nesting is specific to this route.

- union
  - NatalSvgResponse
    - `type` 'natal_svg', required
    - `status` 'current', required
    - `svg` string, required: Original static SVG source in JSON, not a URL. UTF-8 renderer output capped at 128 KiB; do not treat arbitrary external SVG as trusted.
    - `house_system` 'equal' | 'whole_sign' | 'placidus' | 'porphyry' | 'meridian' | 'campanus' | 'regiomontanus' | 'alcabitius' | 'koch' | 'morinus' | 'topocentric' | 'sripati' | 'vehlow' | 'horizon' | 'krusinski' | 'sunshine' | 'sunshine_alt' | 'savard' | 'pullen_sd' | 'pullen_sr' | 'carter' | 'apc' | 'equal_mc' | 'natural', required
    - `theme` 'light' | 'dark' | 'monochrome', required
    - `zodiac` 'tropical' | 'sidereal', required
    - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks', required
    - `metadata` NatalSvgMetadata, required
      - `renderer` 'cosmicephemeris-original-svg-v1', required
      - `position_source` 'engine-chart', required
      - `layout` '1200x1100', required
      - `aspects` 'supplied-major-only' | 'configured' | 'hidden', required
      - `house_status` 'current' | 'current', required
      - `polar_policy` 'reject-without-fallback', required
      - `additional_points` 'cosmicephemeris-natal-points-v1'
    - `additional_points` AdditionalPointsResult
      - `points` AdditionalChartPointMap, required
        - `vertex` AdditionalChartPointPosition
          - `label` 'Vertex' | 'Antivertex' | 'Equatorial Ascendant' | 'Equatorial Descendant' | 'Lot of Fortune' | 'Lot of Spirit', required
          - `category` 'angle' | 'lot', required
          - `longitude_degrees` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `degree_in_sign` number, required
        - `antivertex` AdditionalChartPointPosition
          - `label` 'Vertex' | 'Antivertex' | 'Equatorial Ascendant' | 'Equatorial Descendant' | 'Lot of Fortune' | 'Lot of Spirit', required
          - `category` 'angle' | 'lot', required
          - `longitude_degrees` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `degree_in_sign` number, required
        - `equatorial_ascendant` AdditionalChartPointPosition
          - `label` 'Vertex' | 'Antivertex' | 'Equatorial Ascendant' | 'Equatorial Descendant' | 'Lot of Fortune' | 'Lot of Spirit', required
          - `category` 'angle' | 'lot', required
          - `longitude_degrees` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `degree_in_sign` number, required
        - `equatorial_descendant` AdditionalChartPointPosition
          - `label` 'Vertex' | 'Antivertex' | 'Equatorial Ascendant' | 'Equatorial Descendant' | 'Lot of Fortune' | 'Lot of Spirit', required
          - `category` 'angle' | 'lot', required
          - `longitude_degrees` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `degree_in_sign` number, required
        - `lot_of_fortune` AdditionalChartPointPosition
          - `label` 'Vertex' | 'Antivertex' | 'Equatorial Ascendant' | 'Equatorial Descendant' | 'Lot of Fortune' | 'Lot of Spirit', required
          - `category` 'angle' | 'lot', required
          - `longitude_degrees` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `degree_in_sign` number, required
        - `lot_of_spirit` AdditionalChartPointPosition
          - `label` 'Vertex' | 'Antivertex' | 'Equatorial Ascendant' | 'Equatorial Descendant' | 'Lot of Fortune' | 'Lot of Spirit', required
          - `category` 'angle' | 'lot', required
          - `longitude_degrees` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `degree_in_sign` number, required
      - `metadata` object, required
        - `model` 'cosmicephemeris-natal-points-v1', required
        - `status` 'current', required
        - `frame` 'apparent_ecliptic_of_date', required
        - `zodiac` 'tropical' | 'sidereal', required
        - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks', required
        - `chart_sect` 'day' | 'night', required
        - `sect_boundary` 'apparent_topocentric_sun_center_strictly_above_geometric_horizon', required
        - `vertex_definition` 'western_intersection_of_prime_vertical_and_ecliptic', required
        - `equatorial_ascendant_definition` 'ascendant_at_geographic_latitude_zero', required
        - `lot_formula` string, required
        - `interpretations` unknown, required
    - `aspect_configuration` AspectConfiguration
      - `source` 'profile' | 'custom', required
      - `profile` 'major' | 'standard' | 'extended': Neutral preset name. major uses five Ptolemaic aspects; standard preserves the existing six-aspect natal-analysis default; extended admits all eleven documented geometric aspects.
      - `aspects` NatalAnalysisAspectOption[], required
        - `aspect` 'conjunction' | 'semisextile' | 'semisquare' | 'sextile' | 'quintile' | 'square' | 'trine' | 'sesquiquadrate' | 'biquintile' | 'quincunx' | 'opposition', required
        - `max_orb_degrees` number, required
    - `png` PngExport: Deterministic, metadata-free PNG rendered from Cosmic Ephemeris's own SVG primitive subset. No uploaded SVG, URL, font, browser, or external rendering service is accepted.
      - `media_type` 'image/png', required
      - `base64` string, required: Base64-encoded PNG bytes; decode as an image, never HTML.
      - `bytes` integer, required
      - `sha256` string, required
      - `width` 1200, required
      - `height` 800 | 1100 | 1120 | 1420, required
      - `renderer` 'cosmicephemeris-original-png-v1', required
      - `source_svg_sha256` string, required
  - HistoricalNatalSvgResponse
    - `schema` 'cosmicephemeris-historical-calculation-v1', required
    - `status` 'historical', required
    - `type` 'natal-svg', required
    - `input` HistoricalNatalSvgRequest, required: Explicit historical mode, 1000 BCE (BC)–2500 CE (AD). No year zero, implicit calendar, UTC or IANA zone. Preserve tool-specific mathematical, geographic and search limits; calendar/time conventions and estimated Delta-T are not certified historical accuracy.
      - `birth` HistoricalBirthInput, required
        - `date` HistoricalDate, required: Explicit civil date, 1000 BCE (BC)–2500 CE (AD); no year zero. Calendar validity is checked by the server. Available only on documented connected historical operations, with explicit UT1/fixed-offset conventions.
          - `year` integer, required
          - `era` 'BCE' | 'CE', required: Display BCE (BC) / CE (AD); API values remain BCE / CE. No year zero.
          - `month` integer, required
          - `day` integer, required
          - `calendar` 'proleptic_gregorian' | 'proleptic_julian', required: Explicit choice; applies the selected calendar rules throughout history without a regional adoption switch.
        - `time` string, required: Explicit HH:MM[:SS]; whole seconds only, no leap seconds. Normalized helper output includes seconds.
        - `timezone` string, required: Explicit UT1 or fixed offset UT1+/-HH:MM[:SS], within 14 hours. Local clock minus offset yields UT1, not UTC. No IANA timezone inference. Original offset spelling is preserved.
        - `lat` number, required
        - `lon` number, required
      - `zodiac` 'tropical' | 'sidereal'
      - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks'
      - `house_system` 'equal' | 'whole_sign' | 'placidus' | 'porphyry' | 'meridian' | 'campanus' | 'regiomontanus' | 'alcabitius' | 'koch' | 'morinus' | 'topocentric' | 'sripati' | 'vehlow' | 'horizon' | 'krusinski' | 'sunshine' | 'sunshine_alt' | 'savard' | 'pullen_sd' | 'pullen_sr' | 'carter' | 'apc' | 'equal_mc' | 'natural'
      - `theme` 'light' | 'dark' | 'monochrome'
      - `show_aspects` boolean
      - `include_png` boolean: When true, also returns a deterministic PNG derived only from this response's server-rendered SVG. Omission or false preserves the predecessor response exactly.
      - `additional_points` AdditionalChartPoint[]
      - `aspect_profile` 'major' | 'standard' | 'extended': Neutral preset name. major uses five Ptolemaic aspects; standard preserves the existing six-aspect natal-analysis default; extended admits all eleven documented geometric aspects.
      - `aspects` NatalAnalysisAspectOption[]: Custom unique aspect/orb options, mutually exclusive with aspect_profile.
        - `aspect` 'conjunction' | 'semisextile' | 'semisquare' | 'sextile' | 'quintile' | 'square' | 'trine' | 'sesquiquadrate' | 'biquintile' | 'quincunx' | 'opposition', required
        - `max_orb_degrees` number, required
    - `result` object, required: Complete historical calculation adapter result. Times are explicit UT1 date records, never UTC strings; derived times may include fractional seconds and years outside the input range.
    - `metadata` object, required
      - `time_standard` 'UT1', required
      - `historical_accuracy_certified` unknown, required
      - `warnings` string[], required

## Other responses

- `400`: Invalid request, malformed JSON, out-of-range date/location, unknown model, invalid timezone or ambiguous/nonexistent clock-change time. Invalid attempts reaching quota reservation consume one unit.
- `401`: Missing, invalid, revoked API key or unavailable activated key owner. Dashboard cookies do not authenticate calculation routes.
- `403`: Origin not allowed by production CORS policy. Server-to-server requests can omit Origin.
- `404`: Wrong/case-variant/noncanonical or trailing-slash route; public paths have no version prefix.
- `413`: Request exceeds the body limit; gateway JSON is capped at 128 KiB. Edge failures may be HTML.
- `429`: Monthly quota exhausted, per-user two-request concurrency reached, or nginx rate/connection admission refused. Retry-After: 2 is sent for application per-user concurrency only, not a promise that monthly quota resets in two seconds.
- `500`: Bounded gateway/database/internal failure. An admitted attempt can still consume quota.
- `502`: Engine unavailable, unsuccessful internal server response or invalid upstream JSON. No engine internals are exposed.
- `503`: Four-request global calculation pool full (Retry-After: 2), maintenance or upstream service unavailable.
- `504`: Application engine timeout: 15 seconds normally; planetary events, house ingresses, aspect windows, event calendar, eclipse geometry, electional search, and event-rule search use 30 seconds; Nakshatra Timeline plus the explicitly enumerated readiness, robustness, location, uncertainty, and electional-audit family use 60 seconds. Timer includes response-body parsing; an admitted timeout consumes quota.

---

[API](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api.md) · [All operations](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api/revisions/f041e924cea3?raw)