Timing
Transit (Gochar) API for charts and the sky
Updated
How the transit API works
- 1The birth chart stays fixed for life, while the planets go on through the signs.
- 2When a slow planet like Jupiter moves into a new house of the chart, astrologers read a new period in that part of life.
- 3The API returns where each planet is on a date, and the dates it moves from house to house, with a traditional result for each.
POST /v1/transits?as_of=2026-10-01200 OK{
"as_of": "2026-10-01T00:00:00",
"natal_moon_sign": "Taurus",
"transits": [
{
"graha": "Sun",
"sign": "Virgo",
"house_from_moon": 5,
"result": "unfavorable",
"obstructed_by": [],
"net": "unfavorable"
},
{
"graha": "Moon",
"sign": "Taurus",
"house_from_moon": 1,
"result": "favorable",
"obstructed_by": [
"Sun"
],
"net": "obstructed"
}
]
}Call the transit API from your code
Send the details as JSON with your API key in the Authorization header. Copy the code, set ASTROLOGY_API_KEY to your key, and run it.
POST /v1/transits
# John Doe, born Aug 15, 1990, 10:30 AM, New York
curl -X POST "https://apiforastrology.com/api/astrology/v1/transits?as_of=2026-10-01" \
-H "Authorization: Bearer $ASTROLOGY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"year":1990,"month":8,"day":15,"hour":10,"minute":30,"second":0,"latitude":40.7128,"longitude":-74.006,"timezone":"America/New_York"}'{
"meta": {
"ayanamsa": "lahiri",
"ayanamsa_value": 23.7260727,
"julian_day": 2448119.10483,
"ephemeris": "JPL DE440s",
"node": "true",
"timezone": {
"source": "zone",
"offset_hours": -4,
"zone": "America/New_York",
"abbreviation": "EDT",
"dst": true,
"dst_hours": 1,
"ambiguous_resolved_by_fold": null,
"note": "read from the IANA tz database at this instant, so daylight saving and historical offset changes are included"
}
},
"as_of": "2026-10-01T00:00:00",
"natal_moon_sign": "Taurus",
"ascendant_sign": "Virgo",
"transits": [
{
"graha": "Sun",
"sign": "Virgo",
"sign_number": 6,
"house_from_moon": 5,
"house_from_ascendant": 1,
"result": "unfavorable",
"vedha_house": null,
"obstructed_by": [],
"obstructed": false,
"net": "unfavorable",
"speed": 0.9827528302048448,
"retrograde": false
},
{
"graha": "Moon",
"sign": "Taurus",
"sign_number": 2,
"house_from_moon": 1,
"house_from_ascendant": 9,
"result": "favorable",
"vedha_house": 5,
"obstructed_by": [
"Sun"
],
"obstructed": true,
"net": "obstructed",
"speed": 14.283114921087416,
"retrograde": false
},
{
"graha": "Mars",
"sign": "Cancer",
"sign_number": 4,
"house_from_moon": 3,
"house_from_ascendant": 11,
"result": "favorable",
"vedha_house": 12,
"obstructed_by": [],
"obstructed": false,
"net": "favorable",
"speed": 0.5825257867134042,
"retrograde": false
}
],
"summary": {
"favorable": 4,
"unfavorable": 4,
"obstructed": 1
},
"rule": "house counted from the natal Moon; favorable houses per graha from the classical gochara table, obstructed where another transiting graha occupies the vedha house"
}What the transit API returns
- Where each planet is on any date, and the house it falls in, counted from the birth Moon. Also whether that is favorable by the traditional tables.
- Vedha, the traditional block: when another planet cancels a transit, the response shows the result before and after it.
- What comes next: each planet's stay in each house, with dates, for any range you ask for.
- Sign changes (ingresses) for one planet, with a separate row when retrograde motion takes it back into a sign.
- When a planet passes over a point in the birth chart, such as Saturn over the Moon.
- A yearly forecast, read against the chart. It covers every sign change, retrograde, combustion (a planet too close to the Sun) and tracked conjunction (two planets meeting) in the year.
- The sky with no chart: where every planet is at a moment (GET /v1/sky), and a calendar of sign changes, retrogrades and conjunctions (GET /v1/sky/events).
- The annual chart, or varshaphal (POST /v1/varshaphal): the Tajik chart for one year of life. Tajik is the Indian method for yearly charts. It is cast for the moment the Sun returns to its birth position. It comes with the muntha (a point that moves one sign a year) and a dasha squeezed into one year.
- The daily returns of that year (POST /v1/varshaphal/dina), for up to 31 days. Each one is the moment the Sun moves one more whole degree past its birth position, with the rising sign at that moment.
Transits are counted from the birth Moon, as the traditional tables are. The house from the rising sign is given too, but no result rests on it. Dates allow for retrograde motion, so a planet that crosses a sign boundary three times shows up three times.
Transit API endpoints
POST /v1/transitsCurrent transits read against a chartPOST /v1/transits/forecastUpcoming transit periods for a chartPOST /v1/transits/ingresses/{graha}When a planet enters and leaves each signPOST /v1/transits/over/{graha}When a transiting planet passes over a birth-chart pointPOST /v1/forecast/annualYearly forecast: a year of sky events read against a chartGET /v1/skyPlanet positions at a moment, no chartGET /v1/sky/eventsCalendar of sky events, no chartPOST /v1/varshaphalThe Tajik annual chart (varshaphal) for one yearPOST /v1/varshaphal/dinaTajik daily return (dina pravesh) for a day or a short window
What it uses from your plan
Calculations use 1 call each. Written readings use reading credits instead:
- Varshaphal (annual chart)3 credits
- Annual forecast25 credits
The rules behind the transit API
Gochar is counted from the birth Moon (TR-01), and each planet is favorable only in certain houses from it (TR-02). Vedha, a planet in a paired house, can block a transit (TR-03). It is not applied to future periods, because the other planets keep moving (TR-07). Transit dates come from the ephemeris (the planet position data), not a printed table (TR-06). A year is dated from what moves in the sky, not from the rising sign (AN-01). Combustion states the orb (how close counts) it used (AN-04). The annual chart is cast at the Sun's exact return in the sidereal zodiac, which is never assumed to fall on the birthday (VP-01). The muntha moves on one sign a year from the birth rising sign (VP-03).
How we check the numbers
Every answer here starts from planet positions worked out from NASA JPL planet data (DE440). We test them against NASA JPL Horizons, NASA's planet position service. On 25,571 positions from 1850 to 2149, the Sun and planets agree within 0.001 arc seconds. The Moon agrees within 0.011. On 2,000 random birth charts, the rising sign agrees with Swiss Ephemeris within 0.004. An arc second is 1/3,600 of a degree. Our tests fail if a result drifts past these figures.
A practicing astrologer reviews the rules behind these answers. Each rule has an ID you can look up in the public rulebook.
See how we test accuracyTerms used here
Who uses it
- Astrology appsCharts, dashas, daily readings and a printable report from one API. A small team can ship a full astrology app with it.
- Publishers and mediaDaily panchang, Moon-sign horoscopes, festival dates and sky events for any city, ready to publish every day.
- Astrologer consultation platformsCharts, dashas and yogas for every client, with the rule behind each answer. Send a printable report after the session.
From the blog
· 10 min read
Transit Alerts: Tell Each User When a Planet Changes Sign
Gochar alerts for apps.
Read
· 7 min read
How Sade Sati Is Calculated, and Why Apps Disagree on Dates
Sade sati is Saturn's pass through the three signs around your Moon sign.
Read
· 6 min read
Mercury Retrograde 2026 and 2027: Exact Dates and Signs
Mercury retrograde 2026 and 2027 dates, computed from NASA JPL data, with the Vedic sign at each turn…
Read
Transit API questions
All questionsAre transits counted from the Moon or the rising sign?
From the birth Moon, because the traditional result tables are based on it. Each planet's house from the rising sign comes back too, for astrologers who read it, but no result is based on it.
What gochar isCan I get transit data with no birth chart?
Yes. GET /v1/sky gives every planet's sign, degree, nakshatra (star group) and retrograde status at a moment. GET /v1/sky/events lists sign changes, retrogrades with their stations (the days a planet seems to stop), combustion and two tracked conjunctions between two dates. Neither needs birth details, so both suit news pages and sky calendars.
Why does a planet enter the same sign twice?
Retrograde motion can carry a planet back over a sign boundary, so it may cross it three times. The API dates every crossing instead of merging them into one, and marks a return to a sign the planet just left with resumes_visit.
What retrograde meansHow far ahead can I look?
Any date from 1850 to 2149. The default range is one year for the transit forecast and five years for one planet's sign changes. For a planet passing over a birth point, it is 20 years. Sky events allow up to two years in one call, and a very wide range for a fast planet such as the Moon is refused.
See the transit endpointsDoes the sky calendar include eclipses?
No. GET /v1/sky/events lists sign changes, retrogrades, combustion and two tracked conjunctions. Eclipses have their own endpoint, GET /v1/eclipses, in the Hindu calendar API. It lists every solar and lunar eclipse between two dates, worked out from the planet positions. For a place that can see one, it adds the local contact times and sutak.
About the Hindu calendar APIIs the annual chart (varshaphal) cast on the birthday?
No. POST /v1/varshaphal casts it for the moment the Sun returns to its exact birth position, found to the second. That moment falls within a day or so of the birthday and drifts later over a lifetime, so it is never assumed. The response gives it in UTC and local time, with the year's chart, the muntha and a one-year dasha.
Read rule VP-01Is the yearly forecast the same for everyone with one rising sign?
No. POST /v1/forecast/annual reads every sign change, retrograde, combustion and tracked conjunction of the year against one chart. It counts from the birth Moon as well as the rising sign. Two people with the same rising sign but different Moons get different results.
Astrology API
Call it with a free test key
Create an account and a test key, then call any endpoint on this page. Or try a request in the API reference first.
Your first answer
John Doe, New York
- RisingVirgoHast
- SunCancerAshlesha
- MoonTaurusMrigashira
- MarsAriesKrittika
Real API output. A free test key gets the same answer.
01
Test key: 1,000 test calls a month to build with
02
Free plan: 2,000 live calls a month, no card needed
03
Open rules: every rule is published, so you can check any answer