Back to Docs
SVG Secondary Progressions Chart

SVG Secondary Progressions Chart

POST/api/v1/natal/chart/progressions

Render a natal and secondary-progressed bi-wheel as SVG or PNG. The natal chart sits inside the sign ring and the progressed chart is drawn around it: progressed planets, and optionally the progressed ASC/MC and house cusps, all on the outer side. The progressed positions follow the classic rule of one ephemeris day after birth per tropical year of life, so they match the secondary progressions JSON endpoint to the arc-second.

The alias /api/v1/natal/chart/secondary-progressions serves the same chart. Aspect lines between the two wheels default to a 1° orb, the same default as the JSON endpoint, so the lines you see are the aspects it reports.

Full URL

https://api.freeastroapi.com/api/v1/natal/chart/progressions

Request fields

The request has the same shape as the SVG transit chart. Only the outer-wheel fields differ: progression_date replaces transit_date, the progression_* location fields replace current_*, and show_progressed_aspects / progressed_planet_color replace their transit counterparts.

Field
natal
Type
object
Required
Yes
Description
Birth data and the shared SVG/PNG rendering configuration. Same contract as the SVG transit endpoint.
Field
progression_date
Type
string
Required
No
Description
Real-world date the chart is progressed to. "YYYY-MM-DD" means local midnight at the progression location; a full ISO datetime is accepted and a UTC offset is honoured when present. Defaults to now (UTC).
Field
progression_city
Type
string
Required
No
Description
Location used for the progressed houses and angles, and for interpreting a local progression_date. Defaults to the birth location when the city and both coordinates are omitted.
Field
progression_lat
Type
float
Required
No
Description
Progression latitude. Supply it together with progression_lng when the city is omitted.
Field
progression_lng
Type
float
Required
No
Description
Progression longitude. Supply it together with progression_lat when the city is omitted.
Field
tz_str
Type
string
Required
No
Description
IANA timezone of progression_date. Defaults to "AUTO", which resolves it from the progression location.
Field
dst_policy
Type
"reject" | "earlier" | "later" | "shift_forward"
Required
No
Description
Optional daylight-saving fold and gap policy applied to progression_date, as for transit_date on the transit endpoint.
Field
layout
Type
"progressed_outside" | "progressed_inside"
Required
No
Description
Defaults to "progressed_outside": the French layout with natal planets inside the sign ring and everything progressed on the outer ring. "progressed_inside" uses the transit-chart lanes. Explicit chart_config.french_style or french_transit_natal_planets_inside values always win.
Field
show_natal_aspects
Type
boolean
Required
No
Description
Draw natal-to-natal aspect lines using the natal chart's own orbs. Defaults to false.
Field
show_inter_aspects
Type
boolean
Required
No
Description
Draw progressed-to-natal aspect lines. Defaults to true.
Field
show_progressed_aspects
Type
boolean
Required
No
Description
Draw aspects within the progressed chart. Defaults to false.
Field
orb_deg
Type
float
Required
No
Description
Maximum orb in degrees for progressed-to-natal and progressed-to-progressed lines (0 < orb ≤ 5). Defaults to 1.0, matching the secondary progressions JSON endpoint.
Field
aspect_set
Type
"major" | "major_plus"
Required
No
Description
Defaults to "major" (conjunction, opposition, trine, square, sextile). "major_plus" also draws the quincunx.
Field
orb_settings
Type
object
Required
No
Description
Per-aspect orb overrides in degrees for progressed lines, e.g. {"conjunction": 1.5, "trine": 0.5}. Aspects the renderer cannot draw are ignored.
Field
show_progressed_angles
Type
boolean
Required
No
Description
Draw the progressed ASC and MC glyphs on the outer ring. Defaults to false. Requires a known birth time.
Field
show_progressed_houses
Type
boolean
Required
No
Description
Draw the progressed house cusps as a numbered secondary house wheel. In the default layout the cusp ring sits outside the progressed planets; with progressed_inside it sits inside the sign ring. Defaults to false. Requires a known birth time.
Field
natal_planet_color
Type
string | null
Required
No
Description
Natal-ring color. Defaults to "#1565C0"; null uses the body or sign colors selected by chart_config.planet_color_mode.
Field
progressed_planet_color
Type
string | null
Required
No
Description
Progressed-ring color. Defaults to "#C62828"; null uses the body or sign colors selected by chart_config.planet_color_mode.
Field
chart_config
Type
object
Required
No
Description
Top-level visual overrides merged after natal.chart_config, matching the SVG transit endpoint. The same top-level style aliases (custom_sign_bg_color, show_retrograde_markers, retrograde_marker_style, ...) are accepted.

Natal object

The nested natal object uses the same birth-data and visual configuration contract as the SVG transit endpoint. See the SVG Natal Chart reference for the full display_settings and chart_config options.

Field
name
Type
string
Required
No
Description
Display name. Defaults to "User".
Field
year
Type
integer
Required
Yes
Description
Birth year.
Field
month
Type
integer
Required
Yes
Description
Birth month (1-12).
Field
day
Type
integer
Required
Yes
Description
Birth day (1-31).
Field
hour
Type
integer
Required
No
Description
Birth hour (0-23). Defaults to 12.
Field
minute
Type
integer
Required
No
Description
Birth minute (0-59). Defaults to 0.
Field
time_known
Type
boolean
Required
No
Description
Whether the birth time is known. Defaults to true. When false, progressed angles and houses are not drawn and both wheels hide time-dependent factors.
Field
city
Type
string
Required
No
Description
Birth city. Required unless lat and lng are both supplied.
Field
lat
Type
float
Required
No
Description
Birth latitude; provide it together with lng.
Field
lng
Type
float
Required
No
Description
Birth longitude; provide it together with lat.
Field
tz_str
Type
string
Required
No
Description
Birth timezone. Defaults to "AUTO".
Field
format
Type
"svg" | "png"
Required
No
Description
Response format. Defaults to "svg".
Field
size
Type
integer
Required
No
Description
Square chart size in pixels. Defaults to 700.
Field
theme_type
Type
string
Required
No
Description
One of "light", "dark", or "mono". Backgrounds stay white unless chart_config.chart_background is set.
Field
zodiac_type
Type
string
Required
No
Description
Use "tropical" or "sidereal". Defaults to "tropical".
Field
house_system
Type
string
Required
No
Description
House system used by both wheels. Defaults to "placidus".
Field
include_minor_aspects
Type
boolean
Required
No
Description
Adds the quincunx to the natal-to-natal lines. Progressed lines are controlled by aspect_set instead.
Field
orb_settings
Type
object
Required
No
Description
Orbs for the natal-to-natal lines only. Progressed lines use the top-level orb_deg and orb_settings.
Field
display_settings
Type
object
Required
No
Description
Body and angle visibility controls shared with the natal and transit SVG endpoints.
Field
chart_config
Type
object
Required
No
Description
Detailed ring geometry, colors, glyph sizes, labels, backgrounds, and line styles.

Defaults specific to this chart

A few rendering defaults differ from the transit chart so the progressed wheel reads cleanly out of the box. Each one is an ordinary chart_config field and can be overridden.

Field
chart_config.chart_background
Type
string
Required
No
Description
Defaults to "#FFFFFF" on this endpoint, in every theme, so the disk, rings and the outer progressed zone render white. Set it explicitly to change it.
Field
chart_config.show_degree_labels
Type
boolean
Required
No
Description
Defaults to false on this endpoint. Set it to true to show planet degree labels. ASC and MC angle labels are a separate setting and stay visible.
Field
chart_config.show_retrograde_markers
Type
boolean
Required
No
Description
Off by default. When degree labels are hidden the R or ℞ marker is drawn on its own next to the planet; retrograde_marker_style selects "R" or "rx".
Field
chart_config.retrograde_marker_scale
Type
float
Required
No
Description
Size of that standalone marker relative to the degree-label font (0 < scale ≤ 3). Defaults to 1.0.
Field
chart_config.data2_house_wheel_placement
Type
"inner" | "outer"
Required
No
Description
Where the progressed cusp ring is drawn. The layout field sets this for you ("outer" for progressed_outside); pass it explicitly to override.

Layout and the progressed house wheel

With the default layout: "progressed_outside", the natal planets and natal houses stay inside the sign ring. The progressed planets are drawn just outside it, and show_progressed_houses adds a numbered cusp ring beyond them, as thick as the natal house ring. Each progressed cusp line runs from the sign ring out to that cusp ring, and the progressed ASC, DSC, MC and IC cusps use the same line width and color as the natal angle lines. The zone between the sign ring and the cusp ring is painted with the inner chart's background, including house background colors and opacity when those are enabled.

layout: "progressed_inside" reproduces the transit-chart geometry: the progressed lane sits inside the natal planets and the progressed cusp ring, if requested, sits inside the sign ring, as on the synastry chart.

Progressed angles are those of the progressed ephemeris moment at the progression location, exactly as the JSON endpoint reports them. They are not a solar-arc-directed MC.

cURL example

curl -X POST "https://api.freeastroapi.com/api/v1/natal/chart/progressions" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "natal": {
      "name": "Maya",
      "year": 1990,
      "month": 5,
      "day": 15,
      "hour": 14,
      "minute": 30,
      "city": "London",
      "tz_str": "AUTO",
      "format": "svg",
      "size": 700,
      "theme_type": "light"
    },
    "progression_date": "2026-03-30",
    "show_inter_aspects": true,
    "show_progressed_angles": true,
    "show_progressed_houses": true
  }' \
  --output secondary_progressions_chart.svg

Python example

import requests

response = requests.post(
    "https://api.freeastroapi.com/api/v1/natal/chart/progressions",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "natal": {
            "name": "Maya",
            "year": 1990,
            "month": 5,
            "day": 15,
            "hour": 14,
            "minute": 30,
            "city": "London",
            "tz_str": "AUTO",
            "format": "svg",
        },
        "progression_date": "2026-03-30",
        "show_inter_aspects": True,
        "show_progressed_angles": True,
        "show_progressed_houses": True,
    },
)
response.raise_for_status()

print(response.headers["X-Progressed-Datetime-UTC"])

with open("secondary_progressions_chart.svg", "wb") as output:
    output.write(response.content)

Orbs, aspect sets and styling

This request widens the progressed orbs to 2.5°, allows a 4° conjunction, adds the quincunx, draws progressed-to-progressed lines as well, colors every planet by its sign on both wheels by passing null for the two ring colors, and shows small ℞ retrograde markers. Send a JSON null, not the string "null".

{
  "natal": {
    "name": "Maya",
    "year": 1990,
    "month": 5,
    "day": 15,
    "hour": 14,
    "minute": 30,
    "city": "London",
    "tz_str": "AUTO",
    "format": "svg",
    "chart_config": {
      "planet_color_mode": "sign",
      "show_retrograde_markers": true,
      "retrograde_marker_style": "rx",
      "retrograde_marker_scale": 0.6
    }
  },
  "progression_date": "2026-03-30T12:00",
  "layout": "progressed_outside",
  "orb_deg": 2.5,
  "aspect_set": "major_plus",
  "orb_settings": { "conjunction": 4 },
  "show_inter_aspects": true,
  "show_progressed_aspects": true,
  "show_progressed_angles": true,
  "show_progressed_houses": true,
  "natal_planet_color": null,
  "progressed_planet_color": null
}

Sample output (PNG)

A natal chart for 15 June 1990, 14:30 in Paris, progressed to 22 October 2026. Natal planets sit inside the sign ring; the progressed planets, the progressed ASC and MC and the numbered progressed house cusps are drawn outside it. Planets are colored by sign on both wheels, degree labels are hidden, retrograde planets carry a small ℞ marker, and only the progressed-to-natal aspects are drawn.

Secondary progressions bi-wheel: natal chart inside the sign ring, progressed planets, angles and house cusps outside

The request that produced it. The nested chart_config is a complete light-theme preset you can reuse as-is; everything progressed is enabled by the three top-level flags.

{
  "natal": {
    "name": "Example",
    "year": 1990,
    "month": 6,
    "day": 15,
    "hour": 14,
    "minute": 30,
    "time_known": true,
    "city": "Paris",
    "lat": 48.8566,
    "lng": 2.3522,
    "tz_str": "Europe/Paris",
    "house_system": "placidus",
    "zodiac_type": "tropical",
    "include_minor_aspects": true,
    "orb_settings": {
      "conjunction": 9,
      "opposition": 10,
      "trine": 7,
      "square": 8,
      "sextile": 6,
      "quincunx": 3
    },
    "format": "png",
    "size": 900,
    "theme_type": "light",
    "show_metadata": false,
    "lang": "en",
    "display_settings": {
      "lilith": false,
      "mean_lilith": false,
      "corrected_lilith": true,
      "true_lilith": true,
      "chiron": true,
      "north_node": true,
      "south_node": true,
      "part_of_fortune": true
    },
    "chart_config": {
      "chart_background": "#FFFFFF",
      "custom_planet_color": null,
      "planet_color_mode": "sign",
      "degree_label_color": "#00000000",
      "custom_sign_bg_color": "#00000000",
      "custom_house_bg_color": "#FFFFFF",
      "custom_sign_colors": [
        "#00000000",
        "#00000000",
        "#00000000",
        "#00000000",
        "#00000000",
        "#00000000",
        "#00000000",
        "#00000000",
        "#00000000",
        "#00000000",
        "#00000000",
        "#00000000"
      ],
      "sign_line_color": "#C0C0C0",
      "house_line_color": "#C0C0C0",
      "sign_ring_inner_color": "#444444",
      "sign_ring_outer_color": "#333333",
      "house_ring_inner_color": "#C0C0C0",
      "house_ring_outer_color": "#C0C0C0",
      "asc_line_color": "#606060",
      "dsc_line_color": "#606060",
      "mc_line_color": "#606060",
      "ic_line_color": "#606060",
      "angle_label_color": "#444444",
      "asc_label_color": "#606060",
      "dsc_label_color": "#606060",
      "mc_label_color": "#606060",
      "ic_label_color": "#606060",
      "sign_tick_color": "#929292",
      "long_tick_color": "#C0C0C0",
      "short_tick_color": "#C0C0C0",
      "planet_connector_color": "#232323",
      "sign_ring_thickness_fraction": 0.16,
      "house_ring_thickness_fraction": 0.072,
      "planet_symbol_scale": 0.47,
      "planet_spacing_scale": 1,
      "round_planet_glyphs": false,
      "sign_symbol_scale": 0.76,
      "round_sign_wheel_glyphs": false,
      "house_number_scale": 0.3,
      "degree_label_scale": 0.7,
      "degree_label_minute_scale": 1.13,
      "degree_label_sign_scale": 1.31,
      "degree_label_row_gap": 1.95,
      "angle_label_scale": 0.67,
      "asc_label_scale": 0.67,
      "sign_line_width": 0.75,
      "house_line_width": 1.4,
      "sign_ring_inner_width": 1.4,
      "asc_line_width": 3,
      "dsc_line_width": 3,
      "mc_line_width": 3,
      "ic_line_width": 3,
      "sign_tick_width": 0.6,
      "long_sign_tick_width": 1,
      "sign_background_opacity": 1,
      "house_background_opacity": 0.71,
      "show_planet_connectors": true,
      "planet_connector_opacity": 0.4,
      "show_aspect_lines": true,
      "show_house_ring": true,
      "show_house_numbers": true,
      "show_house_separators": true,
      "show_house_ring_circles": true,
      "show_sign_ticks": true,
      "show_retrograde_markers": true,
      "retrograde_marker_style": "rx",
      "show_degree_labels": false,
      "show_angle_labels": true,
      "angle_marker_style": "french_arrow",
      "degree_label_format": "decimal",
      "show_color_background": true,
      "sign_ring_outer_width": 2.2,
      "custom_house_color": "#929292",
      "data2_custom_house_color": "#929292",
      "data2_house_line_color": "#C0C0C0",
      "data2_house_line_width": 1.4,
      "data2_house_ring_inner_color": "#C0C0C0",
      "data2_house_ring_outer_color": "#C0C0C0",
      "data2_asc_line_color": "#606060",
      "data2_dsc_line_color": "#606060",
      "data2_mc_line_color": "#606060",
      "data2_ic_line_color": "#606060",
      "aspect_conjunction_width": 3.95,
      "aspect_opposition_width": 5.2,
      "aspect_trine_width": 4.45,
      "aspect_square_width": 4.7,
      "aspect_sextile_width": 4.7,
      "aspect_quincunx_width": 4.7,
      "element_color_scheme": "earth_yellow_air_green",
      "show_angle_aspects": false,
      "aspect_opacity_by_strength": false,
      "aspect_excluded_bodies": [
        "part_of_fortune",
        "chiron",
        "lilith",
        "corrected_lilith",
        "true_lilith",
        "north_node",
        "south_node"
      ],
      "retrograde_marker_scale": 0.6
    },
    "png_quality_scale": 2
  },
  "progression_date": "2026-10-22",
  "show_progressed_angles": true,
  "show_progressed_houses": true,
  "natal_planet_color": null,
  "progressed_planet_color": null
}

Response

A successful SVG request returns 200 image/svg+xml with an inline filename of secondary_progressions_chart.svg. Set natal.format to png for image/png. When natal.show_metadata is on, the chart's text block lists the birth data, then Secondary progressions: Mar 30, 2026 (age 35.87) followed by the progressed date, time and location.

Progression response headers

Field
X-Progression-System
Type
string
Required
Yes
Description
Always "secondary".
Field
X-Progression-Target-Date-UTC
Type
string
Required
Yes
Description
The resolved progression_date as a UTC instant, e.g. 2026-03-29T23:00:00Z for a London date-only input.
Field
X-Progressed-Datetime-UTC
Type
string
Required
Yes
Description
The ephemeris instant the outer wheel is cast for: the birth instant plus one day per tropical year elapsed.
Field
X-Progression-Age-Years
Type
string
Required
Yes
Description
Decimal age used for the progression arc, with four decimals.
Field
X-Progression-Aspect-Set
Type
string
Required
Yes
Description
The applied aspect set: "major" or "major_plus".
Field
X-Progression-Aspect-Orbs
Type
JSON string
Required
Yes
Description
The orb policy applied to progressed lines, e.g. {"conjunction":1.0,"opposition":1.0,"quincunx":0.0,"sextile":1.0,"square":1.0,"trine":1.0}.

Errors and calculation notes

  • 400 for unresolved birth or progression locations, or invalid timezone normalization.
  • 422 invalid_progression_date when progression_date is malformed or earlier than the birth datetime.
  • 422 for schema errors such as a missing year, a partial coordinate pair, or an orb_deg outside 0–5.
  • The progressed instant is birth instant + (days elapsed ÷ 365.242189) days, computed from the exact UTC birth moment the inner wheel is drawn with.
  • Progressed houses and angles use the progression location; natal houses use the birth location. With natal.time_known=false neither set of angles is drawn.
  • Natal-to-natal lines keep the natal orbs from natal.orb_settings; progressed lines use orb_deg, aspect_set and the top-level orb_settings.
  • Only the aspects the renderer can draw are affected by orb_settings: conjunction, opposition, trine, square, sextile and quincunx.

Related endpoints

Secondary Progressions JSON

Progressed positions, aspects, movements, lifecycle and timeline data as JSON.

SVG Transit Chart

The same bi-wheel renderer for a caller-supplied transit datetime.

SVG Solar Return Chart

Natal and solar-return bi-wheel for a target year and location.

SVG Natal Chart

Full reference for display_settings and chart_config.