Planetary Positions API
Ephemeris calculator for all planets
Calculate accurate tropical zodiac positions for all 14 celestial bodies (the 10 classical planets Sun through Pluto, the lunar nodes, Chiron, and Black Moon Lilith) for any date, time, and location. Returns longitude, latitude, zodiac sign, degree within sign, daily motion speed, and retrograde status. Perfect for transit tracking, ephemeris tables, astrology apps, and planetary position widgets. Verified against NASA JPL Horizons.
Location first, chart second
The Planetary Positions 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
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 Planetary Positions endpoint
# feed latitude, longitude and timezone from step 1
POST https://roxyapi.com/api/v2/astrology/planetsRequest
POST /api/v2/astrology/planets
Parameters
| Parameter | Type | Description |
|---|---|---|
| langquery | string enum | Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default en. |
Request body
| Field | Type | Description |
|---|---|---|
| date* | string (date) | Target date for planetary positions in YYYY-MM-DD format. Use current date for transit positions, or any historical/future date for research. Planets move daily, so this date determines their zodiac positions. |
| time* | string (time) | Time in 24-hour HH:MM:SS format for precise calculations. Moon moves ~13° per day, so time matters for accurate lunar position. Use 12:00:00 (noon) as default if exact time not needed. |
| 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 the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass "mean" to match one. 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". |
| latitude* | number | Observer latitude in decimal degrees (-90 to 90). While planetary longitudes are geocentric (same worldwide), this is needed for house calculations if extending functionality. For basic ephemeris, use 0 as default. |
| longitude* | number | Observer longitude in decimal degrees (-180 to 180). Used for precise local time conversion. For basic planetary positions, this has minimal impact but ensures accuracy. |
| timezone* | number or string | Decimal hours from UTC (e.g. -5 for EST, 5.5 for IST, 9 for JST, 5.75 for NPT) OR IANA name (e.g. "America/New_York"). IANA resolved to the DST-correct offset for the chart date. |
Example request
{
"date": "2025-12-18",
"time": "12:00:00",
"latitude": 40.7128,
"longitude": -74.006,
"timezone": -5
}Response
Structured JSON with documented fields, covered by 9,557 automated tests per deploy, 2,121 of them gold-standard tests verified against NASA JPL Horizons. Not hallucinated text.
{
"planets": [
{
"name": "Sun",
"longitude": 267.45,
"latitude": 0.01,
"sign": "Sagittarius",
"degree": 27.45,
"speed": 0.9571,
"isRetrograde": false
}
]
}Response fields
| Field | Type | Description |
|---|---|---|
| planets* | array of object | All 14 celestial bodies (10 classical planets, lunar nodes, Chiron, Black Moon Lilith) with zodiac signs, speeds, retrograde status, meanings, and interpretations. |
| planets[].name* | string | Planet 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[].speed* | number | Daily motion in degrees per day. Negative values indicate retrograde. |
| planets[].isRetrograde* | boolean | Whether the planet is in apparent retrograde motion. |
| planets[].symbol | string | Unicode astronomical symbol for this planet. |
| planets[].tagline | string | Short tagline summarizing what this planet governs. |
| planets[].description | string | Brief description of this planet in astrological context. |
| planets[].keywords | array of string | Key themes and traits associated with this planet. |
| planets[].interpretation | object | Planet-in-sign interpretation. How this planet expresses through the zodiac sign it currently occupies. |
| planets[].interpretation.summary* | string | Interpretation of this planet in its current zodiac sign. |
Show all fieldsShow fewer fields
| Field | Type | Description |
|---|---|---|
| planets[].interpretation.planetMeaning* | string | General meaning of this planet in astrology. |
| planets[].interpretation.signExpression* | string | How this planet expresses through the current sign. |
| planets[].interpretation.keywords* | array of string | Keywords for this specific planet-in-sign combination. |
Supported options
lang
nodeType
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.
import { createRoxy } from '@roxyapi/sdk'
const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.astrology.getPlanetaryPositions({ body: { date: '2025-12-18', time: '12:00:00', latitude: 40.7128, longitude: -74.006, timezone: -5 } })from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.astrology.get_planetary_positions(date='2025-12-18', time='12:00:00', latitude=40.7128, longitude=-74.006, timezone='America/New_York')use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->astrology->getPlanetaryPositions(date: '2025-12-18', time: '12:00:00', latitude: 40.7128, longitude: -74.006, timezone: -5);using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Astrology.Planets.PostAsync(new() { /* request fields above */ });import roxyapi "github.com/RoxyAPI/sdk-go"
roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Astrology.GetPlanetaryPositions(ctx, nil, roxyapi.GetPlanetaryPositionsJSONRequestBody{ /* request fields above */ })curl -X POST "https://roxyapi.com/api/v2/astrology/planets" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"date":"2025-12-18","time":"12:00: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.
More Planetary Positions endpoints
The Planetary Positions API bundles these related endpoints under one key.
Monthly Ephemeris - Daily tropical planetary positions for a month
Get daily tropical ecliptic positions for all 14 Western bodies (the 10 classical planets Sun through Pluto, the lunar nodes, Chiron, and Black Moon Lilith) for an entire month. Returns longitude, zodiac sign, degree within sign, and retrograde status for each body on each day, calculated at noon UTC. Omit year and month to get the month in progress, so a published ephemeris page stays current without a redeploy. Essential for ephemeris tables, transit tracking, retrograde calendars, and planetary movement charts. Monthly ephemeris API, tropical position table, daily planet transit positions, ecliptic longitude calculator. Verified against NASA JPL Horizons.
Try it liveCalculate planetary aspects - Aspect finder for any date and time
Calculate all major and minor aspects between planets for any date and time. Finds conjunctions (0°), oppositions (180°), trines (120°), squares (90°), sextiles (60°), and minor aspects. Returns aspect type, exact angle, orb, applying/separating status, and strength (0-100). Filter by specific planets or aspect types. Perfect for aspect tables, transit analysis, and aspect pattern detection. Uses standard Western astrology orbs.
Try it liveMonthly Aspects - Tropical aspect calendar for an entire month
Get every planetary aspect that perfects during a given month, across the 13 non-lunar Western bodies: the Sun and Mercury through Pluto, both lunar nodes, Chiron and Black Moon Lilith. Detects nine aspects, five major (conjunction, sextile, square, trine, opposition) and four minor (semi-sextile, semi-square, sesquiquadrate, quincunx), each with its own traditional orb, and returns the exact date and time of closest approach in your timezone along with the nature of the aspect. Calculated on tropical longitudes. The Moon is excluded because it forms hundreds of aspects a month and belongs in a daily view rather than a monthly one. Omit year and month to get the month in progress, so a published calendar stays current without a redeploy. Essential for monthly forecast copy, transit calendars, electional timing, and newsletter automation. Monthly aspect calendar API, exact aspect times, planetary aspect ephemeris, transit timing. Verified against NASA JPL Horizons.
Try it liveCalculate house cusps - House system calculator with comparison
Calculate astrological house cusps using Placidus, Whole Sign, Equal, or Koch house systems. Returns all 12 house cusps with zodiac signs, degrees, Ascendant, and Midheaven. Use "all" parameter to compare all 4 house systems side-by-side. Perfect for astrology charts, house cusp tables, and educational tools showing house system differences. Includes accurate Ascendant and MC calculations.
Try it liveRemote 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 mcp add --transport http \
roxy-astrology https://roxyapi.com/mcp/astrology \
--header "X-API-Key: YOUR_KEY"Tool name for POST /astrology/planets: post_astrology_planets. 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: editorial daily, weekly, monthly, and yearly columns with unique content per sign, the dated events each one rests on returned beside the prose for fact-checking, active transit metadata, Moon phase data, and any past or future period on request 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 year-ahead pages built from every eclipse and every retrograde and direct station of the year with the house each one falls in for that sign
Drop-in UI components & widgets
Render Planetary Positions 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 Planetary Positions API calculations, the interface that renders them, and the Remote MCP your agent calls, all behind one key, end to end.
Show all Planetary Positions UI componentsShow fewer Planetary Positions UI components
| Element | Renders |
|---|---|
| <roxy-aspects-table> | Aspect rows coloured by nature with orb and strength, plus detected chart patterns |
| <roxy-ephemeris-table> | Per-body sign changes and retrograde windows for the month, over the full daily position grid |
Related capabilities
Planetary Positions API FAQ
What does the Planetary Positions API return?
Calculate accurate tropical zodiac positions for all 14 celestial bodies (the 10 classical planets Sun through Pluto, the lunar nodes, Chiron, and Black Moon Lilith) for any date, time, and location. 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 Planetary Positions 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 Planetary Positions 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 Planetary Positions 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 Planetary Positions 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 Planetary Positions 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 14 domains, so the Planetary Positions API is included at no extra cost.
What lang values does the Planetary Positions API accept?
The lang parameter accepts en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Case-insensitive where it is a path value.
Start using Planetary Positions API today.
Ship your astrology app this weekend. Not this quarter.
All 14 domains included with every plan. Every endpoint, MCP server, SDK, and starters.
Plans from $39/mo, starting at $2.32 per domain on annual billing. No credit card required for testing.
View Pricing & Get API Key