KP Astrology API, what to build and how to call it

Ship a KP (Krishnamurti Paddhati) chart, a ruling-planets horary oracle, an event-timing scanner, or a multi-ayanamsa research tool in under 30 minutes. The KP differentiator built into the Roxy 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 Roxy 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

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

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require 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=Chennai" \
  -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": 13.0827,
    "longitude": 80.2707,
    "timezone": "Asia/Kolkata"
  }'

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

const { data: loc } = await roxy.location.searchCities({ query: { q: 'Chennai' } });
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='Chennai')
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: 'Chennai');
$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";
}

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

Then ask any MCP client: "generate the KP chart for someone born July 15 1990 2:30 PM in Chennai. What is the sub-lord of the 7th cusp?"

Response top-level: ascendant, cusps[], planets[], nodes, significators, meta. Each cusp has house, longitude, sign, signLord, nakshatra, nakshatraLord, pada, subLord, subSubLord. Each planet has the full stellar hierarchy (signLord, nakshatra, nakshatraLord, pada, subLord, subSubLord, kpNumber).

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.

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 starter

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

Gotchas

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-node. Set nodeType: 'true-node' if your practitioner reference uses true nodes. Affects Rahu and Ketu positions.
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.
Calculations 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.