Quick Start Playground SDK MCP Setup Free Templates AGENTS.md

Natal Chart API

Birth chart calculator API with houses and aspects

POST/astrology/natal-chart

Includedwith every plan(at no extra cost)

Vedic Forecast Human Design Numerology Tarot Biorhythm I-Ching Crystals Dreams Angel Numbers Location

6,991 tests per deploy, 1527 NASA JPL verified 12 domains, 1 API key llms.txt for AI agents 12 Remote MCP servers, no local setup TypeScript, Python, PHP, C#, and Go SDKs with AGENTS.md

Calculate complete Western astrology natal chart (birth chart) with tropical zodiac. Returns all 14 celestial bodies (the 10 classical planets Sun through Pluto, the lunar nodes, Chiron, and Black Moon Lilith), 12 house cusps with customizable house systems (Placidus, Whole Sign, Equal, Koch), major and minor aspects, Ascendant, Midheaven, dominant elements and modalities. Perfect for astrology apps, birth chart generators, horoscope websites, and astrological consultation tools. Verified against NASA JPL Horizons.

Location first, chart second

The Natal Chart API needs latitude, longitude, and timezone. Never ask users to type coordinates. Resolve a city with the Location endpoint first, then feed the result into the request. Timezone accepts a decimal offset or an IANA name.

1 Resolve the location

GET

curl "https://roxyapi.com/api/v2/location/search?q=New York" \
  -H "X-API-Key: YOUR_KEY"
# -> cities[0]: { latitude, longitude, timezone: "America/New_York" }

2 Call the Natal Chart endpoint

POST /astrology/natal-chart

# feed latitude, longitude and timezone from step 1
POST https://roxyapi.com/api/v2/astrology/natal-chart

Request

POST /api/v2/astrology/natal-chart

Parameters

Parameter	Type	Description
langquery	string enum	Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English. Default `en`.

Request body

Field	Type	Description
date*	string (date)	Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day.
time*	string (time)	Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown.
latitude*	number	Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South.
longitude*	number	Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West.
timezone*	number or string	Timezone: IANA name (e.g. "America/New_York", "Europe/London") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.
nodeType	string enum	Lunar node convention. "mean" is the smoothed average node, which always moves retrograde; "true" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is what most Western software reports (Astrolabe, Cafe Astrology, TimePassages), which is why it is the default here; astro-seek and the Steven Forrest evolutionary school use mean, so pass "mean" to match those. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to "true".
houseSystem	string enum	House system for dividing the chart into 12 houses. Placidus (default) is most popular in Western astrology and time-sensitive. Whole Sign assigns one sign per house (simpler, ancient). Equal houses divide chart into 30° segments from Ascendant. Koch emphasizes houses in high latitudes.

Example request

POST /astrology/natal-chart

{
  "date": "1990-07-15",
  "time": "14:30:00",
  "latitude": 40.7128,
  "longitude": -74.006,
  "timezone": -5
}

Response

Structured JSON with documented fields, covered by 6,991 automated tests per deploy, 1,527 of them gold-standard tests verified against NASA JPL Horizons. Not hallucinated text.

200 OK

{
  "birthDetails": {
    "date": "1990-07-15",
    "time": "14:30:00",
    "latitude": 40.7128,
    "longitude": -74.006,
    "timezone": -5
  },
  "planets": [
    {
      "name": "Sun",
      "longitude": 112.45,
      "latitude": 0.01,
      "sign": "Cancer",
      "degree": 22.45,
      "house": 7,
      "speed": 0.9571,
      "isRetrograde": false
    }
  ],
  "houses": [
    {
      "number": 1,
      "longitude": 45.32,
      "sign": "Taurus",
      "degree": 15.32
    }
  ],
  "houseSystem": "placidus",
  "aspects": [
    {
      "planet1": "Sun",
      "planet2": "Moon",
      "type": "TRINE",
      "angle": 120,
      "orb": 2.5,
      "isApplying": true,
      "strength": 75,
      "interpretation": "harmonious",
      "aspectInterpretation": {
        "summary": "Your Sun forms a very strong conjunction (0) with Jupiter, currently separating (weakening). This neutral aspect creates Planets and points that form a conjunction are energies that are united. They are blended; therefore...",
        "keywords": [
          "blend",
          "difficult",
          "unite",
          "united"
        ]
      }
    }
  ],
  "aspectsInterpretation": {
    "summary": "Your chart contains 15 aspects: 8 harmonious, 5 challenging, and 2 neutral. This creates a harmonious overall pattern.",
    "dominant": "harmonious",
    "harmonious": 8,
    "challenging": 5,
    "neutral": 2
  },
  "ascendant": {
    "sign": "Taurus",
    "degree": 15.32,
    "longitude": 45.32
  },
  "midheaven": {
    "sign": "Aquarius",
    "degree": 8.76,
    "longitude": 308.76
  },
  "partOfFortune": {
    "sign": "Aries",
    "degree": 27.24,
    "longitude": 27.24,
    "house": 8,
    "sect": "night"
  },
  "vertex": {
    "sign": "Virgo",
    "degree": 12.9,
    "longitude": 162.9,
    "house": 6
  },
  "summary": {
    "dominantElement": "Water",
    "dominantModality": "Cardinal",
    "retrogradePlanets": [
      "Mercury",
      "Saturn"
    ],
    "elementDistribution": {
      "Fire": 2,
      "Earth": 3,
      "Air": 1,
      "Water": 4
    },
    "modalityDistribution": {
      "Cardinal": 4,
      "Fixed": 3,
      "Mutable": 3
    }
  }
}

Response fields

Field	Type	Description
birthDetails*	object	Birth details echoed back from the request. Confirms the input used for this chart calculation.
birthDetails.date*	string	Birth date used for this chart (YYYY-MM-DD).
birthDetails.time*	string	Birth time used for this chart (HH:MM:SS, 24-hour).
birthDetails.latitude*	number	Birth latitude in decimal degrees.
birthDetails.longitude*	number	Birth longitude in decimal degrees.
birthDetails.timezone*	number	Timezone offset from UTC in decimal hours.
planets*	array of object	All 14 celestial bodies (10 classical planets, lunar nodes, Chiron, Black Moon Lilith) with zodiac signs, house placements, and interpretations.
planets[].name*	string	Planet or point name (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, South Node, Chiron, Black Moon Lilith). Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees. The lunar nodes are the mean node; software using the true node may show node positions up to 1.75 degrees different.
planets[].nameLocalized	string	Planet or point name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
planets[].longitude*	number	Tropical ecliptic longitude in degrees (0-360).
planets[].latitude*	number	Ecliptic latitude in degrees.
planets[].sign*	string	Tropical zodiac sign this planet occupies. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use signLocalized for anything a reader sees.
planets[].signLocalized	string	Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
planets[].degree*	number	Degree within the zodiac sign (0-29.999).

Show all fields

Field	Type	Description
planets[].house*	number	House placement (1-12) based on the selected house system.
planets[].speed*	number	Daily motion in degrees per day. Negative values indicate retrograde.
planets[].isRetrograde*	boolean	Whether the planet is in retrograde motion.
planets[].dignity	string enum	Essential dignity of this body in the sign it occupies: domicile (the sign it rules, its strongest placement), exaltation (honoured and amplified), detriment (opposite its rulership, where it struggles), fall (opposite its exaltation, where it is weakened), or peregrine (in none of its own dignity signs). Absent for the lunar nodes, Chiron and Black Moon Lilith, which rule no sign and therefore hold no dignity at all, so an absent field and peregrine are different answers. Derived by sign only, so triplicity, bounds and face are not considered. Always English, whatever the lang parameter says, so it stays safe to compare against in code. The four dignity signs behind it are published per body by GET /planet-meanings/{id}.
planets[].interpretation	object	Planet-in-sign-in-house interpretation. Narrative analysis of what this placement means in the natal chart.
planets[].interpretation.summary*	string	One-sentence interpretation of this planet in its sign and house placement.
planets[].interpretation.detailed*	string	Multi-sentence detailed interpretation with personality insights.
planets[].interpretation.keywords*	array of string	Key personality traits and themes for this placement.
houses*	array of object	All 12 house cusps with zodiac positions. House cusps divide the chart into life areas.
houses[].number*	number	House number (1-12).
houses[].longitude*	number	Ecliptic longitude of this house cusp (0-360).
houses[].sign*	string	Zodiac sign on this house cusp. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees.
houses[].signLocalized	string	Zodiac sign name on this cusp in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
houses[].degree*	number	Degree within the zodiac sign (0-29.999).
houseSystem*	string	House system used for this chart (placidus, whole-sign, equal, or koch).
aspects*	array of object	All planetary aspects found in this chart with orbs, strength, and interpretation.
aspects[].planet1*	string	First planet in the aspect pair. Always English, whatever the lang parameter says. Use planet1Localized for anything a reader sees.
aspects[].planet1Localized	string	First planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
aspects[].planet2*	string	Second planet in the aspect pair. Always English, whatever the lang parameter says. Use planet2Localized for anything a reader sees.
aspects[].planet2Localized	string	Second planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
aspects[].type*	string	Aspect type (CONJUNCTION, OPPOSITION, TRINE, SQUARE, SEXTILE, etc.). Always English, whatever the lang parameter says. Use typeLocalized for anything a reader sees.
aspects[].typeLocalized	string	Aspect type name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
aspects[].angle*	number	Exact angle of this aspect type in degrees.
aspects[].orb*	number	Distance from exact aspect in degrees. Tighter orb means stronger influence.
aspects[].isApplying*	boolean	Whether the aspect is applying (growing stronger) or separating (fading).
aspects[].strength*	number	Aspect strength percentage (0-100) based on orb tightness.
aspects[].interpretation*	string	Aspect nature: harmonious, challenging, or neutral. Always English, whatever the lang parameter says, because it is an identifier to compare and style on. Read aspectInterpretation for the sentence a reader sees.
aspects[].aspectInterpretation*	object	Narrative interpretation of this aspect for this chart. The reference description of the aspect TYPE is not repeated per row, use GET or POST /astrology/aspects for that card.
aspects[].aspectInterpretation.summary*	string	One-sentence read of THIS pair: which two bodies, how tight the aspect is, whether it is applying or separating, and how it is classified. Translated in place, so it arrives in the requested language.
aspects[].aspectInterpretation.keywords*	array of string	Themes this aspect activates between the two bodies. Translated in place, so they arrive in the requested language.
patterns	array of object	Detected multi-planet aspect configurations (Grand Trine, Kite, T-Square, Grand Cross, Yod, Mystic Rectangle, Stellium). Grand Cross suppresses contained T-Squares, Kite suppresses underlying Grand Trine.
patterns[].kind*	string enum	Pattern kind identifier. GRAND_TRINE (3 trines, harmonious flow), KITE (Grand Trine with a focal outlet planet), T_SQUARE (opposition with squared apex, growth engine), GRAND_CROSS (4 planets in 2 oppositions and 4 squares, peak tension), YOD (Finger of Fate, fated adjustment), MYSTIC_RECTANGLE (oppositions softened by trines and sextiles), STELLIUM (3+ planets clustered in a sign or 10-degree arc).
patterns[].name*	string	Human-readable name of the configuration as used in astrological literature.
patterns[].planets*	array of string	Participating bodies in canonical order. For Kite, T-Square, and Yod the apex planet appears first.
patterns[].apex	string	Focal planet for Kite, T-Square, and Yod patterns. Receives the released energy of the configuration and is the recommended integration point.
patterns[].element	string enum	Dominant element when the pattern is element-coherent (Grand Trine, Kite). Reported lowercase. Absent for patterns whose meaning does not pivot on element.
patterns[].modality	string enum	Dominant modality for tension-based patterns (T-Square, Grand Cross). Cardinal initiates, Fixed sustains, Mutable adapts.
patterns[].dissociate	boolean	True if the pattern is out-of-sign (one or more planets in a neighboring element or modality). Dissociate patterns are still valid but operate with weakened thematic coherence.
patterns[].tightness*	number	Tightness score (0-100) derived from the average orb tightness across all defining aspects. Higher means closer to exact and stronger thematic expression.
patterns[].interpretation*	string	Concise one-line interpretation naming the participating planets and theme. Localized to the requested language via the lang query parameter (defaults to English).
patterns[].interpretationKey*	string	Stable template identifier used to render the interpretation. Useful for clients that wish to swap in a custom narrative template while preserving the structured variables.
patterns[].interpretationVars*	object	Variables that were interpolated into the interpretation template. Names already resolved to the requested language where appropriate.
aspectsInterpretation*	object	Aspect pattern analysis showing the balance of harmonious vs challenging energies in the chart.
aspectsInterpretation.summary*	string	Narrative summary of the overall aspect pattern in this chart.
aspectsInterpretation.dominant*	string	Whether the chart is predominantly harmonious, challenging, or balanced.
aspectsInterpretation.harmonious*	number	Count of harmonious aspects (trine, sextile).
aspectsInterpretation.challenging*	number	Count of challenging aspects (square, opposition).
aspectsInterpretation.neutral*	number	Count of neutral aspects (conjunction).
ascendant*	object	Ascendant (rising sign). The eastern horizon at birth, defining outward personality and physical appearance.
ascendant.sign*	string	Zodiac sign on the Ascendant (rising sign). Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees.
ascendant.signLocalized	string	Ascendant sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
ascendant.degree*	number	Degree within the Ascendant sign (0-29.999).
ascendant.longitude*	number	Absolute ecliptic longitude of the Ascendant (0-360).
midheaven*	object	Midheaven (MC). The highest point of the ecliptic at birth, representing career direction and public image.
midheaven.sign*	string	Zodiac sign on the Midheaven (MC). Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees.
midheaven.signLocalized	string	Midheaven sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
midheaven.degree*	number	Degree within the Midheaven sign (0-29.999).
midheaven.longitude*	number	Absolute ecliptic longitude of the Midheaven (0-360).
partOfFortune*	object	Part of Fortune (Lot of Fortune). A point derived from the Ascendant and the two luminaries that marks an area of ease, vitality, and material wellbeing in the chart.
partOfFortune.sign*	string	Zodiac sign holding the Part of Fortune.
partOfFortune.degree*	number	Degree within the Part of Fortune sign (0-29.999).
partOfFortune.longitude*	number	Absolute ecliptic longitude of the Part of Fortune (0-360).
partOfFortune.house*	integer	House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign.
partOfFortune.sect*	string enum	Chart sect used for the calculation. Day (diurnal) when the Sun is above the horizon, night (nocturnal) when below. Day charts use Ascendant plus Moon minus Sun, night charts use Ascendant plus Sun minus Moon.
partOfFortune.signLocalized	string	Part of Fortune sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
vertex*	object	Vertex. The western intersection of the prime vertical with the ecliptic, often read as a point of fated encounters and turning-point relationships. The opposite point is the Anti-Vertex.

Supported options

lang

entrdeeshiptfrru

nodeType

meantrue

houseSystem

placiduswhole-signequalkoch

Call it in your language in seconds.

Every snippet is generated from the live OpenAPI spec, so method names, parameters, and fields always match production.

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.astrology.generateNatalChart({ body: { date: '1990-07-15', time: '14:30:00', latitude: 40.7128, longitude: -74.006, timezone: -5 } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.astrology.generate_natal_chart(date='1990-07-15', time='14:30:00', latitude=40.7128, longitude=-74.006, timezone='America/New_York')

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->astrology->generateNatalChart(date: '1990-07-15', time: '14:30:00', latitude: 40.7128, longitude: -74.006, timezone: -5);

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Astrology.NatalChart.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Astrology.GenerateNatalChart(ctx, nil, roxyapi.GenerateNatalChartJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

cURL

curl -X POST "https://roxyapi.com/api/v2/astrology/natal-chart" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-07-15","time":"14:30:00","latitude":40.7128,"longitude":-74.006,"timezone":-5}'

Prefer to try before you write code? Run this Western Astrology endpoint live in the API playground and inspect a real production response.

Remote MCP for AI agents

Every Western Astrology endpoint is a callable tool on the Remote MCP server over Streamable HTTP. No local setup, no Docker. Claude, ChatGPT, Cursor, and any MCP client auto-discover the tools and ground their answers in verified data.

Claude Code / Cursor

claude mcp add --transport http \
  roxy-astrology https://roxyapi.com/mcp/astrology \
  --header "X-API-Key: YOUR_KEY"

Tool name for POST /astrology/natal-chart: post_astrology_natal_chart. Full MCP setup guide

What you can build

Launch natal chart apps with professional-grade accuracy: birth charts, planet positions, house placements, aspects, and element analysis ready for your UI in days

Add zodiac compatibility scoring to dating apps: synastry analysis, composite charts, and compatibility scores with detailed relationship dynamics

Ship personalized horoscope platforms: publisher-grade daily, weekly, and monthly forecasts with unique content per sign, active transit metadata, Moon phase data, and date scheduling for editorial pre-publishing

Build AI astrology chatbots with MCP: your OpenAI, Claude, or Gemini agent auto-discovers and calls every astrology endpoint with zero integration code

Power wellness and lifestyle apps with real-time transits, moon phase calendars, solar returns, and planetary movement alerts for self-discovery features

Create astrology content engines: automated zodiac content with house-based uniqueness per sign, horoscope newsletters with real lunar event dates, transit alerts, and seasonal forecasts at scale

Drop-in UI components & widgets

Render Natal Chart API responses without building charts yourself. Install the npm package and drop these into Next.js, React, Vue, Svelte, Angular, or plain HTML, or embed the very same component on Squarespace, Wix, or WordPress by pasting one snippet, with no backend and no build step. They belong to one library that covers the entire spiritual stack rather than astrology alone, MIT licensed and included in every plan at no extra cost, never a separate product and never an upsell. The Natal Chart API calculations, the interface that renders them, and the Remote MCP your agent calls, all behind one key, end to end.

MIT licensedFramework agnosticThemeable via CSS variablesnpm or CDN

Natal chart: Natal chart wheel with planet glyphs and aspect lines

Western planets table: Sign, degree, house, motion columns plus ASC, MC, PoF, Vertex

The complete UI libraryExplore Roxy UI

Show all Natal Chart UI components

Element	Renders
<roxy-natal-chart>	Natal chart wheel with planet glyphs and aspect lines
<roxy-western-planets-table>	Sign, degree, house, motion columns plus ASC, MC, PoF, Vertex

See them live on Roxy UI Copy-paste widgets Setup guide

Related capabilities

Horoscope API

Synastry API

Composite Chart API

Astrology Transits API

Moon Phase API

All of Astrology API

Natal Chart API FAQ

What does the Natal Chart API return?

Calculate complete Western astrology natal chart (birth chart) with tropical zodiac. Every response is structured JSON with documented fields, not free text, so you map it straight into your product.

How do I authenticate with the Natal Chart API?

Pass your key in the X-API-Key header on every request. Keys are delivered instantly at checkout with no approval queue. Use a secret sk key server side, or mint a publishable pk key locked to your origins for browser and no-code use.

Does the Natal Chart API support multiple languages?

Yes. Append the lang query parameter to any endpoint for responses in English, German, Spanish, French, Hindi, Portuguese, Russian and Turkish. The translated payload includes the full interpretation text, not just field labels.

Do I need coordinates to call the Natal Chart API?

No. Call GET /location/search with a city name first, then pass latitude, longitude, and timezone from the first result into the request. Never ask users to type coordinates. Timezone accepts a decimal offset or an IANA name.

Is the Natal Chart API available over Remote MCP for AI agents?

Yes. Every endpoint is exposed as a callable tool on the Remote MCP server at https://roxyapi.com/mcp/astrology over Streamable HTTP, so Claude, ChatGPT, Cursor, and any MCP client auto-discover it with no local setup or Docker.

How is the Natal Chart API billed?

Flat pricing: 1 request equals 1 quota unit, REST and MCP identical, with no credit weighting or per-token markup. Every plan includes all 12 domains, so the Natal Chart API is included at no extra cost.

What lang values does the Natal Chart API accept?

The lang parameter accepts en, tr, de, es, hi, pt, fr, ru. Case-insensitive where it is a path value.

Start using Natal Chart API today.

Ship your astrology app this weekend. Not this quarter.

All 12 domains included with every plan. Every endpoint, MCP server, SDK, and starters.

Plans from $39/mo, starting at $2.70 per domain on annual billing. No credit card required for testing.

View Pricing & Get API Key