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 (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) | 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. |
| 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, verified against NASA JPL Horizons across 828 gold-standard tests. 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
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.
Calculate 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 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: 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 Planetary Positions 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.
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 12 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. Case-insensitive where it is a path value.
Start using Planetary Positions 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