KP Astrology

KP Astrology API

POST/api/v2/vedic/kpJSON calculation

POST/api/v2/vedic/kp/renderSVG or PNG

Calculate a complete Krishnamurti Paddhati foundation with twelve Placidus cusps, planetary and cuspal lord chains through sub-sub-lord, four-level significators, ruling planets, and KP-compatible Vimshottari dasha context. Use the companion render route for chart, table, or combined image output.

Authentication: send x-api-key on both routes.

Full URLs

https://api.freeastroapi.com/api/v2/vedic/kphttps://api.freeastroapi.com/api/v2/vedic/kp/render

Safe retries with Idempotency-Key

Authenticated, billable astrology POST requests accept the optional header Idempotency-Key: <client-generated unique operation key>. Reuse the same key only when retrying the exact same method, path, query string, and JSON body after a timeout or network failure.

A completed replay returns the first response with Idempotency-Replayed: true, does not rerun the calculation, and does not consume extra quota. Keys are retained for about 24 hours.

Reusing a key with a changed request returns 409 idempotency_key_reused. A duplicate while the first request is still running returns 409 request_in_progress with Retry-After.

KP Calculation Invariants

ayanamsha=kp

Swiss Ephemeris Krishnamurti ayanamsha.

house_system=placidus

Twelve sidereal Placidus house cusps.

node_type=mean

Use mean or true nodes; mean is the default.

dasha_levels=3

Mahadasha through Pratyantardasha by default.

The dedicated route does not silently switch to Lahiri or whole-sign houses. Values other than kp and placidus fail request validation.

Coordinates and `tz_str: "AUTO"`

Provide either city or the complete lat/lng pair. For a city-only request, the API resolves coordinates first. With tz_str: "AUTO", it then resolves the timezone from those final coordinates before converting the local birth time.

Store the returned birth.lat, birth.lng, and birth.timezone_used if later requests must reproduce the same location decision.

{
  "year": 1990,
  "month": 5,
  "day": 17,
  "hour": 14,
  "minute": 35,
  "city": "Mumbai",
  "tz_str": "AUTO",
  "ayanamsha": "kp",
  "house_system": "placidus"
}

JSON Request Examples

curl -X POST "https://api.freeastroapi.com/api/v2/vedic/kp" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
  "year": 1990,
  "month": 5,
  "day": 17,
  "hour": 14,
  "minute": 35,
  "second": 0,
  "city": "Mumbai",
  "lat": 19.076,
  "lng": 72.8777,
  "tz_str": "AUTO",
  "ayanamsha": "kp",
  "house_system": "placidus",
  "node_type": "mean",
  "reference_date": "2026-08-10",
  "dasha_levels": 3,
  "ruling_datetime": "2026-08-10T12:00:00+05:30"
}'

JSON Request Parameters

Birth time is local to tz_str. If ruling_datetime includes an offset, it is converted to the resolved birth-place timezone; if it has no offset, it is interpreted directly in that timezone.

Parameter	Type	Req	Default	Description
year	integer	Yes	—	Astronomical birth year, 0-2399. Year 0 represents 1 BCE.
month	integer	Yes	—	Birth month, 1-12.
day	integer	Yes	—	Birth day, validated against the supplied month and year.
hour	integer	Yes	—	Local birth hour, 0-23.
minute	integer	Yes	—	Local birth minute, 0-59.
second	integer	No	0	Local birth second, 0-59. Useful near a KP subdivision boundary.
city	string	No	""	Birth city used for coordinate lookup when lat and lng are omitted.
lat	float	No	—	Birth latitude. Supply together with lng, or provide city for automatic resolution.
lng	float	No	—	Birth longitude. Supply together with lat, or provide city for automatic resolution.
tz_str	string	No	"AUTO"	AUTO resolves the timezone from the final coordinates. Also accepts an IANA timezone or LMT.
ayanamsha	literal "kp"	No	"kp"	KP invariant. Other ayanamsha values are rejected for this endpoint.
house_system	literal "placidus"	No	"placidus"	KP invariant. Returns twelve sidereal Placidus cusps.
node_type	string	No	"mean"	Lunar node calculation: mean or true.
reference_date	string	No	today	Local YYYY-MM-DD date used to select active KP-compatible Vimshottari periods.
dasha_levels	integer	No	3	Timeline depth: 1 Mahadasha, 2 adds Antardasha, and 3 adds Pratyantardasha.
ruling_datetime	string	No	current moment	Optional ISO 8601 moment for ruling planets. Include an offset for reproducible cross-timezone requests.

Response Shape

Field	Type	Description
system	object	KP system id, name, and ruleset version.
birth	object	Resolved local birth datetime, timezone, latitude, and longitude.
ayanamsha	object	Krishnamurti ayanamsha id, name, and value in degrees.
angles	object	Sidereal ascendant, midheaven, ARMC, and vertex longitudes.
ascendant	object	Ascendant sign, Nakshatra, sign lord, star lord, sub-lord, sub-sub-lord, and subdivision trace.
planets	array	Graha and node rows with exact longitude, Placidus house, motion, Nakshatra, and the complete KP lord chain.
planets[].subdivision	object	Sub and sub-sub segment boundaries, span, sequence index, offset, progress, and boundary policy.
cusps	array[12]	Twelve Placidus cusps with cusp span, occupants, Nakshatra, and sign/star/sub/sub-sub lords.
cuspal_sub_lord_table	array[12]	Compact cusp table containing house, cusp degree, sign, sign lord, star lord, sub-lord, and sub-sub-lord.
planet_significators	array	Four-level house significators for each planet, plus separately reported node sign-lord proxy data for Rahu and Ketu.
house_significators	array[12]	Inverse house-by-house index of planets at each foundation level and the ordered unique significator list.
ruling_planets	object	Ruling moment, ascendant and Moon lord chains, day lord, source roles, ordered unique list, and repetition ranking.
dasha	object	KP-compatible Vimshottari birth balance, active periods, nested timeline, metadata, and KP significator context.
dasha.kp_context	object	Active dasha lords enriched with four-level significator houses and the KP Moon-longitude calculation basis.
metadata	object	Engine, ruleset, true-position policy, ayanamsha, house code, node type, timezone, subdivision policy, significator policy, and node policy.

Sign, Star, Sub and Sub-Sub Lords

Every returned planet, cusp, and ascendant contains sign_lord, star_lord, sub_lord, and sub_sub_lord. The nested subdivision object exposes the exact weighted Vimshottari segment boundaries used to select the sub and sub-sub lords.

Segments use a left-closed, right-open boundary policy. This makes exact cusp and subdivision-boundary behavior deterministic and inspectable through start_degree, end_degree, and boundary_policy.

Four-Level Significator Foundation

planet_significators[].levels follows this documented foundation order. The flattened significator_houses list preserves the level order and removes duplicates after the four rows are evaluated.

Level 1 — star-lord occupancy
House occupied by the planet's star lord.
Level 2 — planet occupancy
House occupied by the planet itself.
Level 3 — star-lord ownership
Houses whose cusp signs are ruled by the planet's star lord.
Level 4 — planet ownership
Houses whose cusp signs are ruled by the planet itself.

Rahu and Ketu policy

Nodes receive foundation levels from their own house and star lord. Their sign-lord proxy is returned separately in node_proxy, including the sign lord's occupied and owned houses. It is deliberately not merged into the four-level canonical order, so clients can apply a preferred KP node doctrine without losing the base evidence.

Ruling Planets and Dasha Context

ruling_planets evaluates the ascendant sub/star/sign lords, Moon sub/star/sign lords, and local day lord for the ruling moment. It returns the raw role list, first-seen unique order, and a repetition-ranked list instead of collapsing those distinct views into one opaque score.

dasha uses the exact KP-ayanamsha Moon longitude with no Lahiri substitution. Active Mahadasha, Antardasha, and Pratyantardasha rows are enriched under dasha.kp_context.active_periods with each lord's foundation significator houses and levels.

Planetary longitudes use the same Swiss Ephemeris true-position flags as the V2 chart endpoint. This keeps signs, Nakshatras, and longitudes directly comparable when both endpoints use ayanamsha: "kp" and the same birth inputs.

Use reference_date for active dasha selection and ruling_datetime for ruling planets. They are independent controls.

Representative Trimmed Response

JSON

This sample preserves the production response field names and representative values. Long planet, cusp, house-significator, and dasha timeline arrays are shortened for readability; the real response includes all planets, all twelve cusps, all twelve house rows, and the requested dasha depth.

{
  "system": {
    "id": "krishnamurti_paddhati",
    "name": "Krishnamurti Paddhati (KP)",
    "ruleset_version": "kp_foundation_v1"
  },
  "birth": {
    "local_datetime": "1990-05-17T14:35:00+05:30",
    "timezone_used": "Asia/Kolkata",
    "lat": 19.076,
    "lng": 72.8777
  },
  "ayanamsha": {
    "id": "kp",
    "name": "Krishnamurti",
    "value_degrees": 23.62576983
  },
  "angles": {
    "ascendant": 150.62472949,
    "midheaven": 60.80364323,
    "armc": 83.93541333,
    "vertex": 0.30085394
  },
  "ascendant": {
    "absolute_degree": 150.62472949,
    "sign": "Virgo",
    "sign_id": 6,
    "degree_in_sign": 0.62472949,
    "sign_lord": "Mercury",
    "nakshatra": {
      "id": 12,
      "name": "Uttara Phalguni",
      "pada": 2,
      "lord": "Sun",
      "start_degree": 146.66666667,
      "end_degree": 160,
      "progress": 0.29685471
    },
    "star_lord": "Sun",
    "sub_lord": "Rahu",
    "sub_sub_lord": "Venus",
    "subdivision": {
      "sub": {
        "lord": "Rahu",
        "sequence_index": 3,
        "start_degree": 149.22222222,
        "end_degree": 151.22222222,
        "span_degrees": 2,
        "progress": 0.70125363,
        "offset_degrees": 1.40250726
      },
      "sub_sub": {
        "lord": "Venus",
        "sequence_index": 5,
        "start_degree": 150.50555556,
        "end_degree": 150.83888889,
        "span_degrees": 0.33333333,
        "progress": 0.35752179,
        "offset_degrees": 0.11917393
      },
      "boundary_policy": "left_closed_right_open"
    },
    "house": 1
  },
  "planets": [
    {
      "name": "Moon",
      "absolute_degree": 297.22878499,
      "sign": "Capricorn",
      "sign_id": 10,
      "degree_in_sign": 27.22878499,
      "sign_lord": "Saturn",
      "nakshatra": {
        "id": 23,
        "name": "Dhanishta",
        "pada": 2,
        "lord": "Mars",
        "start_degree": 293.33333333,
        "end_degree": 306.66666667,
        "progress": 0.29215887
      },
      "star_lord": "Mars",
      "sub_lord": "Jupiter",
      "sub_sub_lord": "Venus",
      "subdivision": {
        "sub": {
          "lord": "Jupiter",
          "sequence_index": 2,
          "start_degree": 296.11111111,
          "end_degree": 297.88888889,
          "span_degrees": 1.77777778,
          "progress": 0.62869156,
          "offset_degrees": 1.11767388
        },
        "sub_sub": {
          "lord": "Venus",
          "sequence_index": 4,
          "start_degree": 296.98518519,
          "end_degree": 297.28148148,
          "span_degrees": 0.2962963,
          "progress": 0.82214934,
          "offset_degrees": 0.2435998
        },
        "boundary_policy": "left_closed_right_open"
      },
      "house": 5,
      "is_retrograde": false,
      "speed_longitude": 12.91710641
    },
    {
      "name": "Rahu",
      "absolute_degree": 287.61064721,
      "sign": "Capricorn",
      "sign_id": 10,
      "degree_in_sign": 17.61064721,
      "sign_lord": "Saturn",
      "nakshatra": {
        "id": 22,
        "name": "Shravana",
        "pada": 3,
        "lord": "Moon",
        "start_degree": 280,
        "end_degree": 293.33333333,
        "progress": 0.57079854
      },
      "star_lord": "Moon",
      "sub_lord": "Saturn",
      "sub_sub_lord": "Jupiter",
      "subdivision": {
        "sub": {
          "lord": "Saturn",
          "sequence_index": 4,
          "start_degree": 285.66666667,
          "end_degree": 287.77777778,
          "span_degrees": 2.11111111,
          "progress": 0.92083289,
          "offset_degrees": 1.94398055
        },
        "sub_sub": {
          "lord": "Jupiter",
          "sequence_index": 8,
          "start_degree": 287.4962963,
          "end_degree": 287.77777778,
          "span_degrees": 0.28148148,
          "progress": 0.40624668,
          "offset_degrees": 0.11435092
        },
        "boundary_policy": "left_closed_right_open"
      },
      "house": 5,
      "is_retrograde": true,
      "speed_longitude": -0.05299203
    }
  ],
  "cusps": [
    {
      "house": 1,
      "cusp_degree": 150.62472949,
      "absolute_degree": 150.62472949,
      "sign": "Virgo",
      "sign_id": 6,
      "degree_in_sign": 0.62472949,
      "sign_lord": "Mercury",
      "nakshatra": {
        "id": 12,
        "name": "Uttara Phalguni",
        "pada": 2,
        "lord": "Sun",
        "start_degree": 146.66666667,
        "end_degree": 160,
        "progress": 0.29685471
      },
      "star_lord": "Sun",
      "sub_lord": "Rahu",
      "sub_sub_lord": "Venus",
      "subdivision": {
        "sub": {
          "lord": "Rahu",
          "sequence_index": 3,
          "start_degree": 149.22222222,
          "end_degree": 151.22222222,
          "span_degrees": 2,
          "progress": 0.70125363,
          "offset_degrees": 1.40250726
        },
        "sub_sub": {
          "lord": "Venus",
          "sequence_index": 5,
          "start_degree": 150.50555556,
          "end_degree": 150.83888889,
          "span_degrees": 0.33333333,
          "progress": 0.35752179,
          "offset_degrees": 0.11917393
        },
        "boundary_policy": "left_closed_right_open"
      },
      "next_cusp_degree": 179.93301306,
      "span_degrees": 29.30828358,
      "occupants": []
    },
    {
      "house": 10,
      "cusp_degree": 60.80364323,
      "absolute_degree": 60.80364323,
      "sign": "Gemini",
      "sign_id": 3,
      "degree_in_sign": 0.80364323,
      "sign_lord": "Mercury",
      "nakshatra": {
        "id": 5,
        "name": "Mrigashira",
        "pada": 3,
        "lord": "Mars",
        "start_degree": 53.33333333,
        "end_degree": 66.66666667,
        "progress": 0.56027324
      },
      "star_lord": "Mars",
      "sub_lord": "Mercury",
      "sub_sub_lord": "Moon",
      "subdivision": {
        "sub": {
          "lord": "Mercury",
          "sequence_index": 4,
          "start_degree": 60,
          "end_degree": 61.88888889,
          "span_degrees": 1.88888889,
          "progress": 0.42545818,
          "offset_degrees": 0.80364323
        },
        "sub_sub": {
          "lord": "Moon",
          "sequence_index": 4,
          "start_degree": 60.78703704,
          "end_degree": 60.94444444,
          "span_degrees": 0.15740741,
          "progress": 0.10549814,
          "offset_degrees": 0.01660619
        },
        "boundary_policy": "left_closed_right_open"
      },
      "next_cusp_degree": 90.95735905,
      "span_degrees": 30.15371583,
      "occupants": [
        "Jupiter"
      ]
    }
  ],
  "cuspal_sub_lord_table": [
    {
      "house": 1,
      "cusp_degree": 150.62472949,
      "sign": "Virgo",
      "sign_lord": "Mercury",
      "star_lord": "Sun",
      "sub_lord": "Rahu",
      "sub_sub_lord": "Venus"
    },
    {
      "house": 10,
      "cusp_degree": 60.80364323,
      "sign": "Gemini",
      "sign_lord": "Mercury",
      "star_lord": "Mars",
      "sub_lord": "Mercury",
      "sub_sub_lord": "Moon"
    }
  ],
  "planet_significators": [
    {
      "planet": "Moon",
      "star_lord": "Mars",
      "sub_lord": "Jupiter",
      "levels": {
        "level_1_star_lord_occupancy": [
          6
        ],
        "level_2_planet_occupancy": [
          5
        ],
        "level_3_star_lord_ownership": [
          3
        ],
        "level_4_planet_ownership": [
          11
        ]
      },
      "significator_houses": [
        6,
        5,
        3,
        11
      ]
    },
    {
      "planet": "Rahu",
      "star_lord": "Moon",
      "sub_lord": "Saturn",
      "levels": {
        "level_1_star_lord_occupancy": [
          5
        ],
        "level_2_planet_occupancy": [
          5
        ],
        "level_3_star_lord_ownership": [
          11
        ],
        "level_4_planet_ownership": []
      },
      "significator_houses": [
        5,
        11
      ],
      "node_proxy": {
        "sign_lord": "Saturn",
        "sign_lord_occupied_house": 5,
        "sign_lord_owned_houses": [
          5,
          6
        ],
        "policy": "reported_separately_not_merged_into_four_level_order"
      }
    }
  ],
  "house_significators": [
    {
      "house": 10,
      "levels": {
        "level_1_star_lord_occupancy": [
          "Mars"
        ],
        "level_2_planet_occupancy": [
          "Jupiter"
        ],
        "level_3_star_lord_ownership": [
          "Venus",
          "Ketu"
        ],
        "level_4_planet_ownership": [
          "Mercury"
        ]
      },
      "significators": [
        "Mars",
        "Jupiter",
        "Venus",
        "Ketu",
        "Mercury"
      ]
    }
  ],
  "ruling_planets": {
    "moment": "2026-08-10T12:00:00+05:30",
    "moment_basis": "explicit_aware_datetime",
    "timezone_used": "Asia/Kolkata",
    "day_lord": "Moon",
    "ascendant": {
      "absolute_degree": 192.4867672,
      "sign_lord": "Venus",
      "star_lord": "Rahu",
      "sub_lord": "Saturn",
      "sub_sub_lord": "Jupiter"
    },
    "moon": {
      "absolute_degree": 79.81960422,
      "sign_lord": "Mercury",
      "star_lord": "Rahu",
      "sub_lord": "Mars",
      "sub_sub_lord": "Venus"
    },
    "components": [
      {
        "role": "ascendant_sub_lord",
        "planet": "Saturn"
      },
      {
        "role": "ascendant_star_lord",
        "planet": "Rahu"
      },
      {
        "role": "ascendant_sign_lord",
        "planet": "Venus"
      },
      {
        "role": "moon_sub_lord",
        "planet": "Mars"
      },
      {
        "role": "moon_star_lord",
        "planet": "Rahu"
      },
      {
        "role": "moon_sign_lord",
        "planet": "Mercury"
      },
      {
        "role": "day_lord",
        "planet": "Moon"
      }
    ],
    "ordered_unique": [
      "Saturn",
      "Rahu",
      "Venus",
      "Mars",
      "Mercury",
      "Moon"
    ],
    "ranked_by_repetition": [
      {
        "planet": "Rahu",
        "occurrences": 2,
        "roles": [
          "ascendant_star_lord",
          "moon_star_lord"
        ]
      }
    ],
    "selection_order": [
      "ascendant_sub_lord",
      "ascendant_star_lord",
      "ascendant_sign_lord",
      "moon_sub_lord",
      "moon_star_lord",
      "moon_sign_lord",
      "day_lord"
    ],
    "day_lord_policy": "civil_weekday_in_resolved_timezone"
  },
  "dasha": {
    "moon_nakshatra": {
      "id": 23,
      "name": "Dhanishta",
      "pada": 2,
      "lord": "Mars"
    },
    "birth_balance": {
      "lord": "Mars",
      "actual_start": "1988-04-30",
      "birth_date": "1990-05-17",
      "end": "1995-05-01",
      "full_duration_years": 7,
      "elapsed_years": 2.0445,
      "remaining_years": 4.9555,
      "elapsed_fraction": 0.292071,
      "remaining_fraction": 0.707929
    },
    "active_periods": [
      {
        "level": "Mahadasha",
        "lord": "Jupiter",
        "start": "2013-04-30",
        "end": "2029-04-30",
        "duration_years": 16,
        "path": [
          "Jupiter"
        ]
      },
      {
        "level": "Antardasha",
        "lord": "Mars",
        "start": "2025-12-30",
        "end": "2026-12-06",
        "duration_years": 0.93,
        "path": [
          "Jupiter",
          "Mars"
        ]
      },
      {
        "level": "Pratyantardasha",
        "lord": "Ketu",
        "start": "2026-08-06",
        "end": "2026-08-26",
        "duration_years": 0.0548,
        "path": [
          "Jupiter",
          "Mars",
          "Ketu"
        ]
      }
    ],
    "timeline": [
      {
        "level": "Mahadasha",
        "lord": "Jupiter",
        "start": "2013-04-30",
        "end": "2029-04-30",
        "duration_years": 16
      }
    ],
    "kp_context": {
      "active_periods": [
        {
          "level": "Mahadasha",
          "lord": "Jupiter",
          "start": "2013-04-30",
          "end": "2029-04-30",
          "path": [
            "Jupiter"
          ],
          "significator_houses": [
            5,
            10,
            4,
            7,
            8
          ],
          "significator_levels": {
            "level_1_star_lord_occupancy": [
              5
            ],
            "level_2_planet_occupancy": [
              10
            ],
            "level_3_star_lord_ownership": [],
            "level_4_planet_ownership": [
              4,
              7,
              8
            ]
          }
        }
      ],
      "lord_significators": {
        "Jupiter": {
          "houses": [
            5,
            10,
            4,
            7,
            8
          ],
          "levels": {
            "level_1_star_lord_occupancy": [
              5
            ],
            "level_2_planet_occupancy": [
              10
            ],
            "level_3_star_lord_ownership": [],
            "level_4_planet_ownership": [
              4,
              7,
              8
            ]
          }
        }
      },
      "calculation_basis": "vimshottari_periods_from_kp_ayanamsha_moon_longitude"
    },
    "metadata": {
      "endpoint_version": "v2",
      "ruleset_version": "kp_vimshottari_v1",
      "system": "vimshottari",
      "levels_requested": 3,
      "reference_date": "2026-08-10",
      "ayanamsha": "kp",
      "house_system": "placidus",
      "node_type": "mean",
      "timezone_used": "Asia/Kolkata",
      "moon_degree_policy": "exact_kp_sidereal_longitude"
    }
  },
  "metadata": {
    "endpoint_version": "v2",
    "ruleset_version": "kp_foundation_v1",
    "calculation_engine": "swiss_ephemeris",
    "planet_position_policy": "swiss_ephemeris_true_position",
    "ayanamsha": "kp",
    "house_system": "placidus",
    "house_code": "P",
    "node_type": "mean",
    "timezone_used": "Asia/Kolkata",
    "julian_day_ut": 2448028.87847222,
    "subdivision_basis": "vimshottari_120_year_proportions",
    "subdivision_boundary_policy": "left_closed_right_open",
    "significator_policy": "four_level_star_occupancy_ownership_v1",
    "node_policy": "nodes_have_occupation_and_star_levels;_sign_lord_proxy_reported_separately"
  }
}

KP Chart and Table Rendering

The render route accepts the same birth, KP, dasha, and ruling-moment fields, then adds format, view, width, theme, and PNG scale controls. The body is raw SVG or PNG image data, so save or stream the bytes instead of calling response.json().

curl -X POST "https://api.freeastroapi.com/api/v2/vedic/kp/render" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
  "year": 1990,
  "month": 5,
  "day": 17,
  "hour": 14,
  "minute": 35,
  "second": 0,
  "city": "Mumbai",
  "lat": 19.076,
  "lng": 72.8777,
  "tz_str": "AUTO",
  "ayanamsha": "kp",
  "house_system": "placidus",
  "node_type": "mean",
  "reference_date": "2026-08-10",
  "dasha_levels": 3,
  "ruling_datetime": "2026-08-10T12:00:00+05:30",
  "format": "svg",
  "view": "combined",
  "width": 1400,
  "theme": "light"
}' \
 --output kp-chart.svg

Render Request Parameters

All JSON calculation fields remain available. The fields at the end of this table control only the rendered representation.

Parameter	Type	Req	Default	Description
year	integer	Yes	—	Astronomical birth year, 0-2399. Year 0 represents 1 BCE.
month	integer	Yes	—	Birth month, 1-12.
day	integer	Yes	—	Birth day, validated against the supplied month and year.
hour	integer	Yes	—	Local birth hour, 0-23.
minute	integer	Yes	—	Local birth minute, 0-59.
second	integer	No	0	Local birth second, 0-59. Useful near a KP subdivision boundary.
city	string	No	""	Birth city used for coordinate lookup when lat and lng are omitted.
lat	float	No	—	Birth latitude. Supply together with lng, or provide city for automatic resolution.
lng	float	No	—	Birth longitude. Supply together with lat, or provide city for automatic resolution.
tz_str	string	No	"AUTO"	AUTO resolves the timezone from the final coordinates. Also accepts an IANA timezone or LMT.
ayanamsha	literal "kp"	No	"kp"	KP invariant. Other ayanamsha values are rejected for this endpoint.
house_system	literal "placidus"	No	"placidus"	KP invariant. Returns twelve sidereal Placidus cusps.
node_type	string	No	"mean"	Lunar node calculation: mean or true.
reference_date	string	No	today	Local YYYY-MM-DD date used to select active KP-compatible Vimshottari periods.
dasha_levels	integer	No	3	Timeline depth: 1 Mahadasha, 2 adds Antardasha, and 3 adds Pratyantardasha.
ruling_datetime	string	No	current moment	Optional ISO 8601 moment for ruling planets. Include an offset for reproducible cross-timezone requests.
format	string	No	"svg"	Rendered output format: svg or png.
view	string	No	"combined"	Content selection: combined, chart, or tables.
width	integer	No	1400	Output width in pixels, from 720 to 2400. Larger table views are easier to read at desktop widths.
theme	string	No	"light"	Built-in render theme: light or dark.
png_quality_scale	float	No	2.0	PNG raster scale from 0.5 to 4.0. Ignored when format is svg.

Render Response

Field	Type	Description
Content-Type	header	image/svg+xml for format=svg or image/png for format=png.
body	image bytes	Raw rendered image bytes. Do not parse the render response as JSON.
view=combined	render mode	KP chart and the principal KP tables in one output.
view=chart	render mode	Chart-focused output without the full table composition.
view=tables	render mode	Table-focused output for cusp, planet, and significator review.

Caveats and Errors

Birth-time sensitivity

KP cusp sub-lords and sub-sub-lords can change with small birth-time differences. Preserve seconds when known and avoid presenting uncertain birth times as exact.

400 Bad Request

Returned when a city cannot be resolved, coordinates are incomplete, the local datetime is invalid, or an astronomical calculation cannot be completed for the supplied input.

401 / 403

The API key is missing, invalid, or does not have access to the route.

422 Validation Error

A field has the wrong type or range, dasha_levels is outside 1-3, node_type is not mean/true, or a non-KP ayanamsha/house system is supplied.

429 Too Many Requests

The request exceeded the applicable API rate limit. Respect Retry-After when it is returned.

501 PNG Unavailable

The server is missing a native Cairo rendering dependency. SVG output remains available; production FreeAstroAPI images include the PNG dependencies.

Reproducibility

Omitting ruling_datetime intentionally uses the current moment. Send an offset-aware ISO 8601 value when snapshots, tests, or stored reports must be stable.

Historical chart comparison

For a narrow pre-1919 Saturn-in-Cancer corpus, the general V2 chart endpoint applies a documented AstroSage display correction. KP intentionally preserves the unadjusted Swiss Ephemeris true position because sub-lord boundaries must remain astronomically traceable.

Interpretation scope

The response exposes deterministic KP calculation evidence. It does not claim to resolve every school-specific node, aspect, or event-judgment convention.

Related Endpoints

Basic Vedic chart Vimshottari dasha Vedic visual chart Full Vedic calculate City search Timezone system

FAQ

Is this a complete KP chart endpoint?

It returns the KP calculation foundation needed by most chart and research interfaces: Placidus cusps, sign/star/sub/sub-sub lords, cuspal sub-lords, four-level significators, ruling planets, and KP-compatible Vimshottari context. School-specific event judgment rules remain application logic.

Can I send only a city and use automatic timezone resolution?

Yes. Omit lat and lng, provide city, and set tz_str to AUTO. The service resolves coordinates first and then resolves the timezone from those coordinates. For repeatable production results, store and resend the resolved birth latitude, longitude, and timezone returned by the API.

Why are kp and placidus fixed values?

The route is intentionally system-specific. It uses Swiss Ephemeris Krishnamurti ayanamsha and sidereal Placidus cusps so that KP subdivisions, cusp lords, significators, and dasha context share one coherent calculation basis.

How are Rahu and Ketu handled in the significator table?

Nodes receive the same four-level occupancy and ownership foundation rows as other returned points. Their sign-lord occupied and owned houses are also returned in node_proxy, but are not merged into the canonical four-level order.

What is the difference between reference_date and ruling_datetime?

reference_date selects the active Vimshottari periods. ruling_datetime calculates the ruling-planet set for a specific moment. If ruling_datetime is omitted, the current moment is used, so specify it whenever the response must be reproducible.

Can the endpoint render KP charts and tables?

Yes. POST the same birth and KP fields to /api/v2/vedic/kp/render, then choose SVG or PNG, a combined/chart/tables view, an output width, and a light or dark theme.