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

Get API Key Try it live

Remote MCP server OpenAPI schema

Rated 4.5 by 127 developers

Includedwith every plan(at no extra cost)

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

828 gold-standard tests, NASA JPL verified

12 domains, 1 API key

llms.txt for AI agents

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.
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, verified against NASA JPL Horizons across 828 gold-standard tests. 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"
    }
  ],
  "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,
    "sect": "night"
  },
  "vertex": {
    "sign": "Virgo",
    "degree": 12.9,
    "longitude": 162.9
  },
  "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). The lunar nodes are the mean node; software using the true node may show node positions up to 1.75 degrees different.
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.
planets[].degree*	number	Degree within the zodiac sign (0-29.999).
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.

Show all fields

Field	Type	Description
planets[].isRetrograde*	boolean	Whether the planet is in retrograde motion.
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.
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.
aspects[].planet2*	string	Second planet in the aspect pair.
aspects[].type*	string	Aspect type (CONJUNCTION, OPPOSITION, TRINE, SQUARE, SEXTILE, etc.).
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.
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).
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).
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.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.
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.
vertex.sign*	string	Zodiac sign holding the Vertex.
vertex.degree*	number	Degree within the Vertex sign (0-29.999).
vertex.longitude*	number	Absolute ecliptic longitude of the Vertex (0-360).
summary*	object	Chart summary with dominant element, modality, retrograde planets, and distribution analysis.
summary.dominantElement*	string	Most represented element in the chart (Fire, Earth, Air, Water).
summary.dominantModality*	string	Most represented modality in the chart (Cardinal, Fixed, Mutable).
summary.retrogradePlanets*	array of string	Planets in retrograde motion at the time of birth.
summary.elementDistribution*	object	Count of planets in each element. Shows elemental emphasis in the personality.
summary.modalityDistribution*	object	Count of planets in each modality. Shows the dominant operating mode.

Supported options

lang

entrdeeshiptfrru

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

Render Natal Chart API responses without building charts yourself. These open source, framework-agnostic web components take the typed response and draw it, in React, Vue, Svelte, Angular, plain HTML, and WordPress.

<roxy-natal-chart><roxy-western-planets-table>

See them live on Roxy UI

Related capabilities

Horoscope API

Synastry API

Composite Chart API

Astrology Transits API

Moon Phase API

All of Western 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