Skip to content

Birth Chart SVG Image

The Birth Chart SVG Image endpoint returns natal wheel SVG output from the in-house engine with full wheel/render option support.

Language: All 26 Languages

Language support: All 26 languages supported. Non-English responses are translated on the fly by the translator helper (LibreTranslate default; DeepL BYOK, MyMemory, or Google selectable per request).

Endpoint

Method Path
POST https://api.numerologyapi.com/api/v1/birth-chart/svg

Request Body

Top-Level Fields

Name Required Type Example Description
sign No string CANCER Zodiac sign. Allowed: ARIES, TAURUS, GEMINI, CANCER, LEO, VIRGO, LIBRA, SCORPIO, SAGITTARIUS, CAPRICORN, AQUARIUS, PISCES.
target_date No string 2026-04-08 Public/sign fallback date (YYYY-MM-DD).
birth No object {...} Engine-native birth block (see nested table).
sections No array[string] ["general"] Requested sections.
zodiac_system No string tropical Allowed: sidereal, tropical.
ayanamsa No string lahiri Allowed: lahiri, fagan_bradley, krishnamurti, raman, yukteswar.
house_system No string placidus Allowed: placidus, whole_sign, equal, koch.
node_type No string true Allowed: true, mean.
tenant_id No string docs-smoke Optional tenant/cache namespace override.
user_name No string Docs Smoke User User label for chart rendering.
output_mode No string wheel_only Allowed: full, report_only, wheel_only.
include_wheel_svg No boolean true Include wheel SVG artifact in render path.
split No boolean false false: binary SVG response. true: split JSON SVG bundle when supported.
round_wheel_only No boolean true Render circular wheel only.
transparent_background No boolean true Transparent background mode.
svg_compression No string none Allowed: none, gzip.
language No string en Engine language key (2-16 chars).
locale No string en-US Engine locale key (2-20 chars).
wheel No object {...} Wheel rendering options (see nested table).
theme No string classic Legacy compatibility key mapped to wheel.theme (classic->paper, light->day, dark->night, dark-high-contrast->obsidian).
lang No string en Legacy compatibility key mapped to language.
name No string User Legacy alias for user_name.
year No integer 1992 Legacy flattened birth year (use with month and day).
month No integer 7 Legacy flattened birth month.
day No integer 16 Legacy flattened birth day.
hour No integer 13 Legacy flattened birth hour.
minute No integer 45 Legacy flattened birth minute.
lat No number 40.7128 Legacy flattened latitude (must pair with lng).
lng No number -74.0060 Legacy flattened longitude (must pair with lat).
tz_str No string America/New_York Legacy flattened timezone alias.
city No string New York Legacy compatibility field.
country No string US Legacy compatibility field.

birth Object Fields

Name Required Type Example Description
birth.date Yes (if birth supplied) string 1992-07-16 Birth date (YYYY-MM-DD).
birth.time No string 13:45 Birth time (HH:MM, 24h).
birth.coordinates No object { "latitude": 40.7128, "longitude": -74.006 } Coordinate block.
birth.coordinates.latitude No number 40.7128 Range: -90 to 90.
birth.coordinates.longitude No number -74.0060 Range: -180 to 180.
birth.timezone No string America/New_York IANA timezone.

wheel Object Fields

Name Required Type Example Description
wheel.preset_id No string minimal_app Allowed: minimal_app, editorial_full, print_clean.
wheel.preset_override_mode No string merge Allowed: merge, preset_only.
wheel.size No integer 720 Range: 720 to 2400.
wheel.theme No string custom Allowed: night, day, aurora, paper, obsidian, sunset, zenith, mono, custom. Use custom together with wheel.theme_palette for full color control.
wheel.panel_layout No string bottom Allowed: right, bottom.
wheel.accent_color No string #3ddd77 Hex color.
wheel.background_gradient No array[string] ["#0b1020", "#111b3b", "#1b2f6d"] Optional 3-color gradient override.
wheel.panel_opacity No number 0.78 Range: 0.2 to 1.0.
wheel.theme_palette No object { "center_fill": "#0d1832", "panel_opacity": 0.78 } Optional custom theme palette override (see Custom Wheel Themes). Partial overrides are allowed on any theme; required when theme is custom.
wheel.aspect_line_opacity No number 0.58 Range: 0.1 to 1.0.
wheel.show_aspect_lines No boolean true Show aspect lines.
wheel.show_house_cusps No boolean true Show house cusp markers.
wheel.show_house_numbers No boolean true Show house numbers.
wheel.show_sign_symbols No boolean true Show zodiac symbols.
wheel.show_sign_names No boolean true Show zodiac labels.
wheel.show_degree_ticks No boolean true Show degree ticks.
wheel.show_degree_labels No boolean true Show degree labels.
wheel.degree_tick_interval No integer 5 Range: 1 to 30.
wheel.show_planet_symbols No boolean true Show planet glyphs.
wheel.planet_symbol_size No number 15.0 Range: 10.0 to 30.0.
wheel.planet_marker_size No number 6.3 Range: 3.0 to 12.0.
wheel.show_planet_table No boolean true Show planet table panel.
wheel.show_aspect_table No boolean true Show aspect table panel.
wheel.show_sign_legend No boolean true Show sign legend.
wheel.show_element_balance No boolean true Show element balance panel.
wheel.show_metadata No boolean true Show metadata panel.
wheel.show_title No boolean true Show title/subtitle.
wheel.show_angle_markers No boolean true Show ASC/MC markers.
wheel.show_center_signature No boolean true Show center signature text.
wheel.title No string Docs SVG Optional wheel title.
wheel.subtitle No string Expanded parity example Optional wheel subtitle.
wheel.custom_planet_colors No object { "Sun": "#ffbb33" } Planet-name to hex-color map.

Custom Wheel Themes (theme: "custom" + theme_palette)

The wheel's colors and transparency are fully customizable: set wheel.theme to custom and pass a theme_palette object. Only the keys you provide are overridden — everything else falls back to the dark night base palette.

{
  "wheel": {
    "theme": "custom",
    "accent_color": "#3ddd77",
    "theme_palette": {
      "bg_0": "#0b1730",
      "bg_1": "#101d38",
      "bg_2": "#0a1326",
      "panel_fill": "#0c1730",
      "panel_opacity": 0.78,
      "sign_line": "#2b3f63",
      "ring_inner": "#34486a",
      "center_fill": "#0d1832",
      "center_stroke": "#1e2f4a",
      "divider": "#2a3f64",
      "subtitle": "#8fa2c2",
      "text": "#dbe7f8",
      "soft_text": "#9fb0cd"
    }
  }
}

theme_palette keys

Key Type What it controls
bg_0 / bg_1 / bg_2 hex (#rrggbb) Background gradient stops
panel_fill hex Planet/legend panel fill
panel_opacity float 0–1 Panel transparency
sign_line hex Zodiac sign boundary lines
ring_inner hex Inner wheel ring stroke
center_fill hex Wheel center fill (center signature disc)
center_stroke hex Wheel center stroke
divider hex Dividers / card borders
subtitle / text / soft_text hex Typography colors

Rules

  • Partial overrides — only the keys you provide are applied; the rest fall back to the theme's base palette (custom uses the dark night base).
  • Color values must be 7-char hex (#rrggbb); panel_opacity must be a float in [0, 1]. Unknown keys or invalid values → 422 validation error.
  • theme_palette is required when theme is "custom".
  • On named themes (e.g. paper) theme_palette acts as a partial override.
  • Only the wheel visuals change — chart calculations, positions, and aspects are never affected.

Custom theme example

curl --request POST \
  --url "https://api.numerologyapi.com/api/v1/birth-chart/svg" \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "birth": {
    "date": "1992-07-16",
    "time": "13:45",
    "coordinates": { "latitude": 40.7128, "longitude": -74.006 },
    "timezone": "America/New_York"
  },
  "wheel": {
    "theme": "custom",
    "accent_color": "#3ddd77",
    "theme_palette": {
      "bg_0": "#0b1730",
      "bg_1": "#101d38",
      "bg_2": "#0a1326",
      "panel_fill": "#0c1730",
      "panel_opacity": 0.78,
      "sign_line": "#2b3f63",
      "ring_inner": "#34486a",
      "center_fill": "#0d1832",
      "center_stroke": "#1e2f4a",
      "divider": "#2a3f64",
      "subtitle": "#8fa2c2",
      "text": "#dbe7f8",
      "soft_text": "#9fb0cd"
    }
  }
}'

Legacy theme precedence on this endpoint

The legacy top-level theme field is still supported:

  1. Explicit top-level theme (e.g. "theme": "dark") wins.
  2. Otherwise wheel.theme (e.g. "custom" + theme_palette) is used.
  3. Otherwise the historical default classic (→ paper) applies.

Legacy aliases: classic → paper, light → day, dark → night, dark-high-contrast → obsidian.

Response

This endpoint returns SVG (image/svg+xml) by default. It can return split JSON SVG parts when split=true.

curl --request POST \
  --url "https://api.numerologyapi.com/api/v1/birth-chart/svg" \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "sign": "CANCER",
  "target_date": "2026-04-08",
  "zodiac_system": "tropical",
  "ayanamsa": "lahiri",
  "house_system": "placidus",
  "node_type": "true",
  "tenant_id": "docs-smoke",
  "user_name": "Docs Smoke User",
  "output_mode": "wheel_only",
  "include_wheel_svg": true,
  "split": false,
  "round_wheel_only": true,
  "transparent_background": true,
  "svg_compression": "none",
  "language": "en",
  "locale": "en-US",
  "birth": {
    "date": "1992-07-16",
    "time": "13:45",
    "coordinates": { "latitude": 40.7128, "longitude": -74.006 },
    "timezone": "America/New_York"
  },
  "wheel": {
    "preset_id": "minimal_app",
    "theme": "paper",
    "panel_layout": "bottom",
    "size": 720
  }
}'

Public Mode Example (General Sign-Based)

curl --request POST \
  --url "https://api.numerologyapi.com/api/v1/birth-chart/svg" \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "sign": "CANCER",
  "target_date": "2026-04-08",
  "output_mode": "wheel_only",
  "split": false,
  "round_wheel_only": true,
  "language": "en",
  "locale": "en-US",
  "wheel": { "preset_id": "minimal_app", "theme": "paper", "size": 720 }
}'

Example Response

Example birth chart SVG response

Rendered SVG Examples

Print preset with aspect lines

Tropical Zenith Example

Tropical zenith example

Sidereal Obsidian Example

Sidereal obsidian example