KP astrology API guide

Ship a KP (Krishnamurti Paddhati) chart, a ruling-planets horary oracle, an event-timing scanner, or a multi-ayanamsa research tool. The KP differentiator built into the RoxyAPI catalog.

KP astrology is the practitioner differentiator. Generic Vedic APIs return sign, house, and nakshatra. KP returns sub-lord, sub-sub-lord, ruling planets, and significators, all required by serious KP practitioners. Nine endpoints in the RoxyAPI catalog cover chart, planets, cusps, ruling planets, the four interval scanners (planets-interval, ruling-planets-interval, rasi-changes, sublord-changes), and ayanamsa lookup. Built on the Roxy Ephemeris, verified against NASA JPL Horizons.

What you can build

• Full KP charts with Placidus cusps, sub-lord, sub-sub-lord, significators
• KP horary apps ("will event X happen?", ruling planets at the moment of question)
• Cuspal sub-lord analysis tools (the KP house-prediction core)
• Event-timing scanners (when does Moon transit a sub-lord boundary, when does a ruling-planet set change)
• Multi-ayanamsa research (KP Newcomb, KP Old, Lahiri, custom)
• Practitioner dashboards with significator tables for any house question
• Stellar-hierarchy displays (sign lord, star lord, sub lord, sub-sub lord per planet)

Prerequisites

1. A RoxyAPI key. Get your API key.
2. Birth date (YYYY-MM-DD), time (HH:MM:SS), latitude, longitude, and timezone. KP is location-sensitive (Placidus cusps depend on latitude).
3. For city -> lat/lng/timezone use GET /location/search.

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require roxyapi/sdk

dotnet add package RoxyApi.Sdk

Call the endpoint

The #1 KP call is the chart. One POST, returns ascendant, 12 cusps with sub-lords, planets with full stellar hierarchy, nodes, and significators. Verified operationId: generateKpChart.

# 1. geocode the city
curl "https://roxyapi.com/api/v2/location/search?q=Toronto" \
  -H "X-API-Key: $ROXY_API_KEY"

# 2. post the KP chart request
curl -X POST https://roxyapi.com/api/v2/vedic-astrology/kp/chart \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-07-15",
    "time": "14:30:00",
    "latitude": 43.6532,
    "longitude": -79.3832,
    "timezone": "America/Toronto"
  }'

import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data: loc } = await roxy.location.searchCities({ query: { q: 'Toronto' } });
const { latitude, longitude, timezone } = loc.cities[0];

const { data: chart } = await roxy.vedicAstrology.generateKpChart({
  body: {
    date: '1990-07-15',
    time: '14:30:00',
    latitude, longitude, timezone,
  },
});

console.log(chart.ascendant);     // ascendant with stellar hierarchy
console.log(chart.cusps.length);  // 12 Placidus cusps with sub-lord per cusp
console.log(chart.planets.length); // 7 visible planets with star/sub/sub-sub lord
console.log(chart.nodes);          // Rahu, Ketu
console.log(chart.significators);  // per-house significators (planets ruling each house)
console.log(chart.meta);           // ayanamsa, node type used

import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ['ROXY_API_KEY'])

loc = roxy.location.search_cities(q='Toronto')
city = loc['cities'][0]

chart = roxy.vedic_astrology.generate_kp_chart(
    date='1990-07-15', time='14:30:00',
    latitude=city['latitude'], longitude=city['longitude'],
    timezone=city['timezone'],
)
for cusp in chart['cusps']:
    print(cusp['house'], cusp['sign'], cusp['signLord'], cusp.get('subLord'))

<?php

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));

$loc = $roxy->location->searchCities(q: 'Toronto');
$city = $loc['cities'][0];

$chart = $roxy->vedicAstrology->generateKpChart(
    date: '1990-07-15',
    time: '14:30:00',
    latitude: $city['latitude'],
    longitude: $city['longitude'],
    timezone: $city['timezone'],
);
foreach ($chart['cusps'] as $cusp) {
    echo $cusp['house'], ' ', $cusp['sign'], ' ', $cusp['signLord'], "\n";
}

using RoxyApi;
using Microsoft.Kiota.Abstractions; // for the Date and Time types

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);

var loc = await roxy.Location.Search.GetAsync(c => c.QueryParameters.Q = "Toronto");
var city = loc!.Cities![0];

var chart = await roxy.VedicAstrology.Kp.Chart.PostAsync(new()
{
    Date = new Date(1990, 7, 15),
    Time = new Time(14, 30, 0),
    Latitude = city.Latitude,
    Longitude = city.Longitude,
    Timezone = new() { String = city.Timezone },
});

foreach (var cusp in chart!.Cusps!)
    Console.WriteLine($"{cusp.House} {cusp.Sign} {cusp.SignLord} {cusp.SubLord}");
// chart.Ascendant, chart.Planets, and chart.Significators carry the rest of the KP detail

claude mcp add-json --scope user roxy-vedic '{"type":"http","url":"https://roxyapi.com/mcp/vedic-astrology","headers":{"X-API-Key":"YOUR_KEY"}}'

Response top-level: ascendant, cusps[], planets[], nodes, significators, meta. The ascendant, each of the 12 cusps, each of the 7 planets and both nodes carry the same four-lord hierarchy: signLord, starLord, subLord, subSubLord, with sign, nakshatra, pada and the kpNumber (1-249) beside them. meta echoes the inputs with the resolved ayanamsa value in degrees and the ayanamsaType you asked for.

Render the result

Option A: drop-in web components

Three KP components from @roxyapi/ui:

• <roxy-kp-chart> for the full chart with ascendant, cusps, planets in tabbed stellar-hierarchy tables.
• <roxy-kp-planets-table> for a planets-only table (call getKpPlanets for the lighter payload).
• <roxy-kp-ruling-planets> for the horary ruling-planets table.

<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@0/dist/cdn/roxy-ui.js" defer></script>

<roxy-kp-chart id="chart"></roxy-kp-chart>
<roxy-kp-ruling-planets id="rp"></roxy-kp-ruling-planets>

<script type="module">
  document.getElementById('chart').data = kpChartResponse;
  document.getElementById('rp').data    = rulingPlanetsResponse;
</script>

Option B: build your own cusp table

chart.cusps.map(c =>
  `${c.house}  ${c.sign.padEnd(12)} signLord:${c.signLord}  subLord:${c.subLord}`
);

Ship the rest

Planets only (lighter than chart)

POST /vedic-astrology/kp/planets (getKpPlanets) returns planets with the full stellar hierarchy and ayanamsa value. Use it when you do not need cusps. Pair with <roxy-kp-planets-table>.

Cusps only (cuspal sub-lord prediction)

POST /vedic-astrology/kp/cusps (getKpCusps) returns the 12 Placidus cusps with stellar hierarchy. The KP cuspal sub-lord method is the headline prediction technique: the sub-lord of a house cusp tells you whether the matters of that house will manifest.

Daily finance score (four sub lord layers, weighed)

POST /vedic-astrology/kp/daily-finance (getKpDailyFinance) scores one day for money the way a KP practitioner works it: the cusp sub lords of the gain and loss houses, the four running dasha lords at the reading moment, the ruling planets of that moment, and every sub lord window the Moon passes through across the day. Each layer prints its rows with inGain, inLoss, verdict and score, then score is the weight-sum of the four layer scores and band is one of strong, favourable, mixed, caution or unfavourable. bestWindow and worstWindows name the stretches of the day to act in or avoid. Pass date and time for a prepared day or an intraday read, and gainHouses, lossHouses and weights to run your own school; the defaults are a stated practitioner convention, printed in the field descriptions, and the score is what the method outputs, never a probability.

Ruling planets (horary core)

POST /vedic-astrology/kp/ruling-planets (getKpRulingPlanets) answers KP horary questions. Pass the moment of question (datetime) plus latitude, longitude, timezone. Optionally pass birthDate and birthTime to overlay the native chart for praśna analysis. Returns dayLord, lagnaSignLord, lagnaStarLord, lagnaSublord, lagnaSubSublord, moonSignLord, moonStarLord, moonSublord, moonSubSublord, rulingPlanets[] (deduplicated and ordered by strength), and per-house significators.

Ruling-planets interval (event scanner)

POST /vedic-astrology/kp/ruling-planets-interval (getKpRulingInterval) scans a startDatetime to endDatetime window at intervalMinutes resolution and returns the ruling planets at each sample. Use it to find moments when the ruling-planet set matches a target (electional KP).

Planets interval (transit scanner)

POST /vedic-astrology/kp/planets-interval (getKpPlanetsInterval) returns planet positions sampled across an interval, useful for tracking sub-lord transit changes.

Rasi changes (sign ingresses)

POST /vedic-astrology/kp/rasi-changes (getKpRasiChanges) returns precise instants of planetary sign changes within a window.

Sub-lord changes (deeper resolution)

POST /vedic-astrology/kp/sublord-changes (getKpSublordChanges) returns precise instants of sub-lord boundary crossings. KP timing uses sub-lord changes as the smallest meaningful unit; this endpoint is the engine for KP timing apps.

Ayanamsa lookup

GET /vedic-astrology/kp/ayanamsa (getKpAyanamsa) returns the applied ayanamsa value in degrees for a given date. Useful when comparing against a printed reference that uses a specific ayanamsa.

See the full KP catalog at the API Reference.

Ready-made template

There is no KP-only template yet. The vedic-astrology-starter-app covers KP horary alongside kundli, dasha, and Gun Milan. Browse the catalog at /templates/vedic-astrology-starter-app. For the conversational variant, astrology-ai-chatbot handles KP queries via Remote MCP.

Gotchas

• rasi-changes and sublord-changes read startDate and endDate as calendar days in the timezone you pass, so one date with timezone: 5.5 is one whole Indian day. One offset is taken from startDate, so a window crossing a daylight-saving change is read on the earlier offset throughout; pass a fixed offset like +05:30 if you need that explicit.
• Default ayanamsa is kp-newcomb. KP practitioners typically demand KP Newcomb, not Lahiri. Other accepted values: kp-old, lahiri, custom (pair with ayanamsaValue in degrees). Pick consciously if you compare against a specific printed reference.
• Node type defaults to mean. Set nodeType: 'true' if your practitioner reference uses true nodes. Affects Rahu and Ketu positions.
• The dasha routes default to lahiri, not KP Newcomb. Pass ayanamsa: 'kp-newcomb' on /vedic-astrology/dasha/current and its siblings so the running lords sit on the same frame as your KP chart; three of five levels can differ between the two.
• Cusps are Placidus, not equal house. KP uses Placidus by convention. House numbers are 1-12.
• Sub-lord and sub-sub-lord are KP-specific concepts. Generic Vedic endpoints (/vedic-astrology/birth-chart) do not return them. If your app needs sub-lord, you need the KP endpoints, not the standard kundli.
• rulingPlanets[] is deduplicated and ordered. Strongest planet first. Do not assume length 4 or 5; cosmic doubles can shorten the list.
• The interval endpoints can be heavy. A 1-minute interval over 24 hours is 1,440 samples. Pick intervalMinutes carefully for cost and latency.
• /kp/ruling-planets accepts either datetime or (birthDate + birthTime). Use datetime for current-moment horary, the birth pair when overlaying a native chart.
• Positions read directly from the NASA JPL DE440 ephemeris, verified against NASA JPL Horizons. Roxy Ephemeris is the same engine that powers Western, Vedic, and Human Design.

What to build next

• The vedic guide covers kundli, dasha, Gun Milan, and panchang for the broader Vedic surface.
• The AI chatbot tutorial shows how to register KP tools so users can ask "what is the ruling planet right now?"
• The Next.js integration guide is the fastest path to a deployed KP horary app.