Astrology Transits API
Current transits with natal chart comparison
Calculate current or future planetary transits (positions of all bodies now). Optionally compare transits to natal chart to find transit-to-natal aspects. Returns all 14 celestial bodies (the 10 classical planets, the lunar nodes, Chiron, and Black Moon Lilith) with signs, degrees, and speeds. When natal chart provided, includes transit aspects (transiting Sun conjunct natal Mars, etc.) with orbs and applying/separating status. Perfect for daily transit forecasts, aspect alerts, and personalized transit reports.
Location first, chart second
The Astrology Transits 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 Astrology Transits endpoint
# feed latitude, longitude and timezone from step 1
POST https://roxyapi.com/api/v2/astrology/transitsRequest
POST /api/v2/astrology/transits
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) | Transit date in YYYY-MM-DD format (defaults to current date) |
| time | string (time) | Transit time in HH:MM:SS format (defaults to current time) |
| timezone | number or string | Transit timezone: decimal hours from UTC OR IANA name (e.g. "America/New_York"). IANA resolved to the DST-correct offset for the transit date. Defaults to 0 (UTC). |
| natalChart | object | Optional natal chart data to compare transits against |
| natalChart.date* | string (date) | Date in YYYY-MM-DD format. A single-digit month or day is accepted and zero-padded (2026-3-5 becomes 2026-03-05). Impossible calendar dates are rejected. |
| natalChart.time* | string (time) | Time in 24-hour format. Seconds are optional and default to 00 (14:30 becomes 14:30:00); a single-digit hour is zero-padded. Out-of-range values are rejected. |
| natalChart.latitude* | number | |
| natalChart.longitude* | number | |
| natalChart.timezone* | number or string | Natal timezone: decimal hours OR IANA name (e.g. "America/New_York"). IANA resolved to the DST-correct offset for the natal date. |
Example request
{
"date": "2025-12-19",
"time": "12:00:00",
"timezone": 0,
"natalChart": {
"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.
{
"transitDate": "2025-12-19",
"transitTime": "12:00:00",
"timezone": 0,
"transitPlanets": [
{
"name": "Sun",
"longitude": 267.45,
"latitude": 0.01,
"sign": "Sagittarius",
"degree": 27.45,
"speed": 0.9571,
"isRetrograde": false
}
]
}Response fields
| Field | Type | Description |
|---|---|---|
| transitDate* | string | Date of the transit calculation (YYYY-MM-DD). |
| transitTime* | string | Time of the transit calculation (HH:MM:SS, 24-hour). |
| timezone* | number | Timezone offset from UTC in hours used for this calculation. |
| transitPlanets* | array of object | Current positions of all 14 celestial bodies (10 classical planets, lunar nodes, Chiron, Black Moon Lilith) in the tropical zodiac. Use for daily transit tracking, horoscope generation, and aspect monitoring. |
| transitPlanets[].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. |
| transitPlanets[].longitude* | number | Tropical ecliptic longitude in degrees (0-360). Primary coordinate for sign and aspect calculation. |
| transitPlanets[].latitude* | number | Ecliptic latitude in degrees. Near zero for most planets except Moon and Pluto. |
| transitPlanets[].sign* | string | Tropical zodiac sign the planet currently occupies. Changes when longitude crosses a 30-degree boundary. |
| transitPlanets[].degree* | number | Degree within the current zodiac sign (0-29.999). Indicates how far into the sign the planet has progressed. |
| transitPlanets[].speed* | number | Daily motion in degrees per day. Negative values indicate retrograde motion. |
| transitPlanets[].isRetrograde* | boolean | Whether the planet is currently in apparent retrograde motion. Retrograde transits are considered more introspective and revisionary. |
| transitAspects | array of object | Transit-to-natal aspects (only included when natalChart is provided in the request). Shows which transiting planets are aspecting natal planets. |
| transitAspects[].transitPlanet* | string | Transiting planet forming the aspect. |
| transitAspects[].natalPlanet* | string | Natal planet being aspected. |
Show all fieldsShow fewer fields
| Field | Type | Description |
|---|---|---|
| transitAspects[].type* | string | Aspect type (CONJUNCTION, OPPOSITION, TRINE, SQUARE, SEXTILE, etc.). |
| transitAspects[].angle* | number | Exact angle of this aspect type in degrees. |
| transitAspects[].orb* | number | Distance from exact aspect in degrees. Tighter orb = stronger influence. |
| transitAspects[].isApplying* | boolean | Whether the transiting planet is moving toward exactitude (applying) or away from it (separating). Applying aspects grow stronger. |
| transitAspects[].strength* | number | Aspect strength percentage (0-100) based on orb tightness, where 100 is exact. |
| transitAspects[].nature* | string | Aspect nature: harmonious (trine, sextile), challenging (square, opposition), or neutral (conjunction). |
| transitAspects[].interpretation* | object | Rich interpretation of the transit aspect including narrative summary, timing, impact assessment, practical guidance, and keywords. |
| transitAspects[].interpretation.summary* | string | Narrative interpretation of what this transit aspect means and how it manifests. |
| transitAspects[].interpretation.timing* | string | How long this transit influence lasts based on the transiting planet speed. |
| transitAspects[].interpretation.impact* | string | Strength and nature of the transit impact on your natal chart. |
| transitAspects[].interpretation.guidance* | string | Practical advice for working with or navigating this transit energy. |
| transitAspects[].interpretation.keywords* | array of string | Key themes activated by this transit aspect. |
| summary | object | Transit aspect summary counts (only included when natalChart is provided). Quick overview of the current transit weather. |
| summary.totalAspects* | number | Total transit-to-natal aspects found. |
| summary.harmonious* | number | Count of harmonious aspects (trine, sextile). |
| summary.challenging* | number | Count of challenging aspects (square, opposition). |
| summary.neutral* | number | Count of neutral aspects (conjunction). |
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.calculateTransits({ body: { date: '2025-12-19', time: '12:00:00', timezone: 0, natalChart: { date: '1990-07-15', time: '14:30:00', latitude: 40.7128, longitude: -74.006, timezone: -5 } } })from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.astrology.calculate_transits(date='2025-12-19', time='12:00:00', timezone='America/New_York', natal_chart={'date': '1990-07-15', 'time': '14:30:00', 'latitude': 40.7128, 'longitude': -74.006, 'timezone': -5})use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->astrology->calculateTransits(date: '2025-12-19', time: '12:00:00', timezone: 0, natalChart: ['date' => '1990-07-15', 'time' => '14:30: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.Transits.PostAsync(new() { /* request fields above */ });import roxyapi "github.com/RoxyAPI/sdk-go"
roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Astrology.CalculateTransits(ctx, nil, roxyapi.CalculateTransitsJSONRequestBody{ /* request fields above */ })curl -X POST "https://roxyapi.com/api/v2/astrology/transits" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"date":"2025-12-19","time":"12:00:00","timezone":0,"natalChart":{"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 mcp add --transport http \
roxy-astrology https://roxyapi.com/mcp/astrology \
--header "X-API-Key: YOUR_KEY"Tool name for POST /astrology/transits: post_astrology_transits. 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 Astrology Transits 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
Astrology Transits API FAQ
What does the Astrology Transits API return?
Calculate current or future planetary transits (positions of all bodies now). 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 Astrology Transits 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 Astrology Transits 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 Astrology Transits 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 Astrology Transits 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 Astrology Transits 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 Astrology Transits API is included at no extra cost.
What lang values does the Astrology Transits API accept?
The lang parameter accepts en, tr, de, es, hi, pt, fr, ru. Case-insensitive where it is a path value.
Start using Astrology Transits 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