Transit (gochar) API reference
Updated
The transit (gochar) endpoints of API for Astrology (apiforastrology.com) show where the planets are on any date. Most read those positions for a birth chart, counted from the birth Moon. Forecasts look ahead, up to a whole year. Two sky endpoints need no birth details at all. The group has 7 endpoints.
Call POST /v1/transits to read a chart on one date. Leave out as_of for today, or set it to get the same answer on every call. POST /v1/transits/forecast lists the periods coming up, and POST /v1/transits/ingresses/{graha} gives one planet's sign changes. For sade sati, Saturn's 7.5-year pass around the Moon sign, use POST /v1/sadesati in the yoga and dosha group. For the big dates ahead, see Jupiter, Saturn and Rahu Ketu transits.
Transits compare where the planets are now with where they were at birth (in Vedic astrology this is called gochara). The current-transit endpoint reads each planet from the birth Moon. It also applies vedha, a traditional rule by which one transiting planet blocks another's effect. The calendar endpoints give dates, and the /v1/sky endpoints describe the sky itself, with no chart. Every result names the rule it used.
7 endpoints. Paths are relative to https://apiforastrology.com/api/astrology. Send your API key in the Authorization: Bearer header (see authentication). No key yet? Get a key. To send test requests from the browser, open the interactive reference.
Overview: Transits and forecasts.
Which transit endpoint to call
| What you need | Endpoint | Cost |
|---|---|---|
| A year of sky events, each read for one chart | POST /v1/forecast/annual | 25 reading credits |
| Today's transits for a chart, counted from the birth Moon. Start here | POST /v1/transits | 1 call |
| The transit periods coming up for a chart, with dates | POST /v1/transits/forecast | 1 call |
| When one planet enters and leaves each sign | POST /v1/transits/ingresses/{graha} | 1 call |
| When a planet passes over a birth point, such as Saturn over the Moon | POST /v1/transits/over/{graha} | 1 call |
| Planet positions at one moment, with no chart | GET /v1/sky | 1 call |
| A calendar of sky events between two dates, with no chart | GET /v1/sky/events | 1 call |
Yearly forecast: a year of sky events read against a chart
POST /v1/forecast/annual
Returns every dated sky event in one calendar year, and what each one means for this chart. The events are ingresses (a planet entering a new sign) and retrograde periods (a planet appearing to move backward). They also include combustion periods (a planet too close to the Sun) and two tracked conjunctions: Venus with Jupiter, and the Sun with Mars. Readings are grouped into sections.
The result is personal to the chart. Most annual horoscopes base the whole year on the ascendant (the rising sign). So everyone with the same rising sign gets the same twelve months. Here each event also has the house it falls in for this chart and the house counted from the birth Moon. It also has the traditional transit (gochara) result for that planet there. Two people with the same ascendant born two weeks apart have the Moon in different places, so they get different results.
Facts and conventions are kept apart. Ingresses and stations (the moments a planet appears to stop before changing direction) are facts. A sign boundary is a definition, and a station is when the planet's apparent motion passes through zero. Both match an independently produced 2026 calendar to the day. Combustion and conjunction periods depend on an orb: how close two bodies must be to count as together. Sources differ on the orb, so each event states the orb it used.
The Moon is left out on purpose. It changes sign about every two days, so it would bury the year under about 150 ingresses. The topic:monthly-days reading section covers the Moon over a shorter window.
Dates are in the birth time zone. An event already running on January 1 did not start then, and started_before_the_year says so. See rulebook section AN (the API's rule reference).
Uses 25 reading credits. On live keys a successful response uses them from your monthly reading credits, and no calls. Test keys return this reading for the sample charts only, and it counts as 1 test call. The X-Reading-Credits-Counted header says what a response used. What reading credits buy.
Cost: Uses reading credits on live keys instead of monthly calls. On test keys it counts as 1 call.
Every annual forecast section on the Sections and IDs page
Required inputs
| Name | In | What it is |
|---|---|---|
| year | query | Calendar year to report, from 1850 to 2149. Dates are given in the birth time zone. |
| year | body | Year of birth, from 1850 to 2149 (the range the planetary data covers). |
| month | body | Month of birth, from 1 (January) to 12 (December). |
| day | body | Day of the month, from 1 to 31. |
| latitude | body | Latitude of the birth place in degrees, negative for south. Text in a local number format, such as "40,7128", is also accepted. |
| longitude | body | Longitude of the birth place in degrees east of Greenwich, negative for west, so places in the Americas are negative. Text in a local number format is also accepted. |
| timezone | body | Time zone of the birth place. Either an IANA time zone name, such as America/New_York, America/Chicago or Europe/London. Or a fixed offset from UTC in hours, such as -5 or 5.5. |
Optional inputs (8), with their defaults
| Name | In | What it does |
|---|---|---|
| lang | query | Language of the reading text, such as en (English, the default) or hi (Hindi). GET /v1/meta lists the languages available. If a passage is not written in that language yet, the English passage is returned instead and marked with fell_back_to_en. Names in the response, such as planets and signs, are translated too. |
| detail | query | Length of the reading text: standard (the default) or expanded, which is about 1.8 times longer. If a passage has no expanded version yet, the standard one is returned. Each text block reports the length it got in its detail field. |
| hour | body | Hour of birth on the local clock at the birth place, from 0 to 23 (24-hour clock). Default 0. |
| minute | body | Minute of birth, from 0 to 59. Default 0. |
| second | body | Second of birth, from 0 to 59. Default 0. |
| timezone_fold | body | Only needed for a local time that happens twice, on the night the clocks go back. In the US since 2007, that is 1:00 to 1:59 AM on the first Sunday in November. 0 picks the first occurrence (before the change) and 1 the second. Without it, such a time is rejected, not guessed. A wrong guess would quietly move the chart by an hour. A local time that never happens, because the clocks jumped forward over it, is also rejected; check the birth time, or send the UTC offset that was in force. |
| ayanamsa | body | The ayanamsa: the offset between the tropical zodiac (used in Western astrology) and the sidereal zodiac (used in Vedic astrology). lahiri (the default) is the Lahiri, or Chitrapaksha, ayanamsa used by the Government of India. kp is the Krishnamurti ayanamsa used in KP astrology, about 6 arcminutes less. raman is B. V. Raman's, about 1 degree 27 arcminutes less. Also: yukteshwar (Sri Yukteshwar's, about 1 degree 23 arcminutes less), jn_bhasin (J. N. Bhasin's, about 1 degree 6 arcminutes less), ushashashi (about 3 degrees 48 arcminutes less) and fagan_bradley (the Western sidereal zodiac, about 53 arcminutes more). true_chitra keeps the star Spica (Chitra) at exactly 180 degrees, so it follows the star itself; it is within about a minute of arc of Lahiri. The chosen ayanamsa is also used for the transits, sade sati and forecasts read against this chart. |
| node | body | How to calculate Rahu and Ketu, the lunar nodes (the two points where the Moon's orbit crosses the Sun's path). Use true for the actual position (the default) or mean for the averaged position. |
Main response fields
year(number)sections(array of objects): each item holds id, title, family, text, language, detail, events.events(array of objects): each item holds kind, graha, starts, ends, starts_at, ends_at, started_before_the_year, runs_past_the_year, orb_degrees, reading.counts(object): holds events.note(string)gaps(array)meta(object): holds ayanamsa, ayanamsa_value, julian_day, ephemeris, node, timezone.
# John Doe, born Aug 15, 1990, 10:30 AM, New York
curl -X POST "https://apiforastrology.com/api/astrology/v1/forecast/annual?year=2026" \
-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"}'{
"year": 2026,
"sections": [
{
"id": "annual:annual-career",
"title": "Annual Forecast: Career",
"family": "annual",
"text": [
"Your work year is shaped mostly by the two slow planets, Saturn and Jupiter. They set the broad climate for you. The Sun, Mercury and Mars move faster, so they add shorter pushes and pauses along the way.",
"Saturn and Jupiter change sign only once in 12 months or longer. So the houses they cross in your chart set your main career themes for the whole year: groundwork, promotions and bigger steps. A house is one of the 12 parts of your chart,…",
"Mercury is sometimes retrograde (it seems to move backward for a few weeks). In those weeks, take extra care with contracts, launches and anything that needs clear talk. When a planet crossing your work houses is marked favorable, that is…"
],
"language": "en",
"detail": "standard",
"events": [
{
"kind": "ingress",
"graha": "Jupiter",
"starts": "2026-01-01",
"ends": "2026-06-01",
"starts_at": "2026-01-01T00:00-05:00",
"ends_at": "2026-06-01T16:20-04:00",
"started_before_the_year": true,
"runs_past_the_year": false,
"sign": "Gemini",
"natal_house": 10,
"house_from_moon": 2,
"result": "favorable",
"why": [
"house"
],
"text": [
"Jupiter, the planet of growth, wisdom and good advice, stays in one sign for about 12 months. So one sign change can be the biggest dated event of your year. The house it enters, the area of life that sign covers in your chart, is where…",
"Because it moves slowly, it works as a background, not a single episode. That part of your life is easier for a year, though you often notice the ease more looking back. If Jupiter changes sign halfway through your year, the year really…"
],
"language": "en",
"detail": "standard"
},
{
"kind": "ingress",
"graha": "Rahu",
"starts": "2026-01-01",
"ends": "2026-11-25",
"starts_at": "2026-01-01T00:00-05:00",
"ends_at": "2026-11-25T07:15-05:00",
"started_before_the_year": true,
"runs_past_the_year": false,
"sign": "Aquarius",
"natal_house": 6,
"house_from_moon": 10,
"result": "favorable",
"why": [
"house"
],
"text": [
"Rahu is the Moon's north node, a point in the sky rather than a body. It stays in a sign for about 18 months. It moves backward, so it changes sign in the opposite direction to the other planets. The house it enters is the area of life…",
"Rahu adds nothing of its own. It magnifies what the house already holds. So the same Rahu transit can be an opportunity in one chart and overreach in another. The house matters more here than Rahu itself. Stay steady, and talk big moves…"
],
"language": "en",
"detail": "standard"
},
{
"kind": "ingress",
"graha": "Saturn",
"starts": "2026-01-01",
"ends": "2027-01-01",
"starts_at": "2026-01-01T00:00-05:00",
"ends_at": "2027-01-01T00:00-05:00",
"started_before_the_year": true,
"runs_past_the_year": true,
"sign": "Pisces",
"natal_house": 7,
"house_from_moon": 11,
"result": "favorable",
"why": [
"karaka"
],
"text": [
"Saturn, the planet of duty, patience and delay, stays in one sign for about two and a half years. So in most years it does not change sign at all. When it does, that is the most important date in your calendar. The house it enters is the…",
"Its transits are read as tasks to meet. What you build under Saturn tends to last, and what you skip usually comes back. So look after that area on purpose rather than dread it: pick one steady habit there and keep it."
],
"language": "en",
"detail": "standard"
}
]
},
{
"id": "annual:annual-love",
"title": "Annual Forecast: Love",
"family": "annual",
"text": [
"Your year in love is read mainly from Venus, the planet of attraction and affection. The reading also follows planets moving through the houses (parts of your chart) that matter most for love and family. Those are the seventh for your…",
"Venus moves quickly, so its mood shifts several times in your year. Each shift can open a short, pleasant window for romance, for growing closer to someone, and for enjoying good company.",
"When Jupiter moves through these houses, or aspects them (sends its influence from another house), it supports long-term commitment. Proposals, marriage and settling into something steady tend to come more easily then. What you can do:…"
],
"language": "en",
"detail": "standard",
"events": [
{
"kind": "ingress",
"graha": "Jupiter",
"starts": "2026-01-01",
"ends": "2026-06-01",
"starts_at": "2026-01-01T00:00-05:00",
"ends_at": "2026-06-01T16:20-04:00",
"started_before_the_year": true,
"runs_past_the_year": false,
"sign": "Gemini",
"natal_house": 10,
"house_from_moon": 2,
"result": "favorable",
"why": [
"karaka"
],
"text": [
"Jupiter, the planet of growth, wisdom and good advice, stays in one sign for about 12 months. So one sign change can be the biggest dated event of your year. The house it enters, the area of life that sign covers in your chart, is where…",
"Because it moves slowly, it works as a background, not a single episode. That part of your life is easier for a year, though you often notice the ease more looking back. If Jupiter changes sign halfway through your year, the year really…"
],
"language": "en",
"detail": "standard"
},
{
"kind": "ingress",
"graha": "Ketu",
"starts": "2026-01-01",
"ends": "2026-11-25",
"starts_at": "2026-01-01T00:00-05:00",
"ends_at": "2026-11-25T07:15-05:00",
"started_before_the_year": true,
"runs_past_the_year": false,
"sign": "Leo",
"natal_house": 12,
"house_from_moon": 4,
"result": "unfavorable",
"why": [
"house"
],
"text": [
"Ketu is the Moon's south node, the point exactly opposite Rahu. It stays in a sign for about 18 months and moves backward with Rahu. The house it enters is the area of life that sign covers in your chart. Detachment sets in there for you.…",
"At the time this can feel like loss. Later, it often turns out to have been needed. The classical view is that Ketu clears away what is finished, though it rarely asks first. The house shows where this may happen, and the dates are below.…"
],
"language": "en",
"detail": "standard"
},
{
"kind": "ingress",
"graha": "Saturn",
"starts": "2026-01-01",
"ends": "2027-01-01",
"starts_at": "2026-01-01T00:00-05:00",
"ends_at": "2027-01-01T00:00-05:00",
"started_before_the_year": true,
"runs_past_the_year": true,
"sign": "Pisces",
"natal_house": 7,
"house_from_moon": 11,
"result": "favorable",
"why": [
"house"
],
"text": [
"Saturn, the planet of duty, patience and delay, stays in one sign for about two and a half years. So in most years it does not change sign at all. When it does, that is the most important date in your calendar. The house it enters is the…",
"Its transits are read as tasks to meet. What you build under Saturn tends to last, and what you skip usually comes back. So look after that area on purpose rather than dread it: pick one steady habit there and keep it."
],
"language": "en",
"detail": "standard"
}
]
},
{
"id": "annual:annual-finance",
"title": "Annual Forecast: Finance",
"family": "annual",
"text": [
"Your money year is read mainly from two planets. Jupiter brings growth, and Venus rules comfort and the things you buy. The reading also follows the transits (planets moving through your chart). It looks at your money houses, the parts of…",
"Jupiter stays in one sign for about a year. So when it moves into a new sign, it sets the pace for your money chances in the year ahead.",
"The reading weighs what comes in against what goes out. Good transits through your eleventh house tend to bring gains. Transits through your twelfth house are a good time to spend on things that last. What you can do: plan big purchases…"
],
"language": "en",
"detail": "standard",
"events": [
{
"kind": "ingress",
"graha": "Jupiter",
"starts": "2026-01-01",
"ends": "2026-06-01",
"starts_at": "2026-01-01T00:00-05:00",
"ends_at": "2026-06-01T16:20-04:00",
"started_before_the_year": true,
"runs_past_the_year": false,
"sign": "Gemini",
"natal_house": 10,
"house_from_moon": 2,
"result": "favorable",
"why": [
"karaka"
],
"text": [
"Jupiter, the planet of growth, wisdom and good advice, stays in one sign for about 12 months. So one sign change can be the biggest dated event of your year. The house it enters, the area of life that sign covers in your chart, is where…",
"Because it moves slowly, it works as a background, not a single episode. That part of your life is easier for a year, though you often notice the ease more looking back. If Jupiter changes sign halfway through your year, the year really…"
],
"language": "en",
"detail": "standard"
},
{
"kind": "ingress",
"graha": "Ketu",
"starts": "2026-01-01",
"ends": "2026-11-25",
"starts_at": "2026-01-01T00:00-05:00",
"ends_at": "2026-11-25T07:15-05:00",
"started_before_the_year": true,
"runs_past_the_year": false,
"sign": "Leo",
"natal_house": 12,
"house_from_moon": 4,
"result": "unfavorable",
"why": [
"house"
],
"text": [
"Ketu is the Moon's south node, the point exactly opposite Rahu. It stays in a sign for about 18 months and moves backward with Rahu. The house it enters is the area of life that sign covers in your chart. Detachment sets in there for you.…",
"At the time this can feel like loss. Later, it often turns out to have been needed. The classical view is that Ketu clears away what is finished, though it rarely asks first. The house shows where this may happen, and the dates are below.…"
],
"language": "en",
"detail": "standard"
},
{
"kind": "ingress",
"graha": "Jupiter",
"starts": "2026-06-01",
"ends": "2026-10-31",
"starts_at": "2026-06-01T16:20-04:00",
"ends_at": "2026-10-31T02:32-04:00",
"started_before_the_year": false,
"runs_past_the_year": false,
"sign": "Cancer",
"natal_house": 11,
"house_from_moon": 3,
"result": "unfavorable",
"why": [
"karaka",
"house"
],
"text": [
"Jupiter, the planet of growth, wisdom and good advice, stays in one sign for about 12 months. So one sign change can be the biggest dated event of your year. The house it enters, the area of life that sign covers in your chart, is where…",
"Because it moves slowly, it works as a background, not a single episode. That part of your life is easier for a year, though you often notice the ease more looking back. If Jupiter changes sign halfway through your year, the year really…"
],
"language": "en",
"detail": "standard"
}
]
}
],
"events": [
{
"kind": "combust",
"graha": "Mars",
"starts": "2026-01-01",
"ends": "2026-03-26",
"starts_at": "2026-01-01T00:00-05:00",
"ends_at": "2026-03-26T04:37-04:00",
"started_before_the_year": true,
"runs_past_the_year": false,
"orb_degrees": {
"direct": 17,
"retrograde": 17
},
"reading": {
"text": [
"A planet is combust when it is close enough to the Sun to be lost in its glare. A combust Mars loses what it is most valued for. Courage, initiative and physical drive work through the Sun's authority rather than on their own. The…",
"The orb is wide, 17 degrees from the Sun, so this can last for months. Treat it as a time to save your effort rather than spend it. Finish what you have already started before you take on anything new."
],
"language": "en",
"detail": "standard"
}
},
{
"kind": "combust",
"graha": "Mercury",
"starts": "2026-01-01",
"ends": "2026-02-09",
"starts_at": "2026-01-01T00:00-05:00",
"ends_at": "2026-02-09T17:46-05:00",
"started_before_the_year": true,
"runs_past_the_year": false,
"orb_degrees": {
"direct": 14,
"retrograde": 12
},
"reading": {
"text": [
"A planet is combust when it sits so close to the Sun that it is lost in the Sun's glare. Tradition reads it as weakened. Mercury is never far from the Sun, so it is combust for several stretches every year. Combustion is the most common…",
"The orb used (how many degrees from the Sun count as too close) is given beside the dates. Sources differ, and two sound methods can disagree by weeks. In practice, put off anything that depends on clear wording during these stretches."
],
"language": "en",
"detail": "standard"
}
},
{
"kind": "combust",
"graha": "Venus",
"starts": "2026-01-01",
"ends": "2026-02-17",
"starts_at": "2026-01-01T00:00-05:00",
"ends_at": "2026-02-17T04:38-05:00",
"started_before_the_year": true,
"runs_past_the_year": false,
"orb_degrees": {
"direct": 10,
"retrograde": 8
},
"reading": {
"text": [
"Venus is combust when it is close enough to the Sun to lose its own light in the Sun's glare. That happens for a stretch or two in most years. For that time, what Venus rules (comfort, relationships, the taste for pleasure) is read as…",
"The orb (how close to the Sun counts as combust) is given with the dates. For a retrograde Venus (one that seems to move backward), the orb is tighter than for a direct one. So the limit itself changes during the window. The classical…"
],
"language": "en",
"detail": "standard"
}
}
],
"counts": {
"events": 79
},
"note": "Ingresses and stations are facts and carry no convention. Combustion and conjunction windows depend on an ORB, sources differ, and each event states the orb it was judged by. The Moon is deliberately absent: it changes sign every two days…",
"gaps": [],
"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"
}
}
}Example from a real call for John Doe, born Aug 15, 1990, 10:30 AM, New York. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Transits and forecasts.
Current transits read against a chart
POST /v1/transits
Returns where each planet is on as_of and how it affects this chart. For each planet you get its sign and which house that sign is, counted from the birth Moon. You also see whether the traditional result for that house is favorable. And you see whether another transiting planet in the vedha house is blocking it. Vedha is a traditional rule: a planet's transit effect is blocked when another planet occupies a paired house.
Both results are returned. result is the plain transit result; net is what remains after vedha. A blocked transit is cancelled, not reversed: it gives neither its good nor its bad effect.
A transit report that ignores vedha overstates the favorable transits. At any moment, a good share of them are blocked. See rulebook section TR (the API's rule reference) for the tables.
Transits (gochara) are counted from the birth Moon, because the traditional result tables are based on it. The house counted from the ascendant is also given, since many astrologers read it too. But no result is based on it here.
Dates allow for retrograde motion. A planet near a sign boundary often crosses it three times. So each re-entry is marked instead of being smoothed away.
Cost: Each successful request counts as 1 call toward your monthly calls.
Required inputs
| Name | In | What it is |
|---|---|---|
| year | body | Year of birth, from 1850 to 2149 (the range the planetary data covers). |
| month | body | Month of birth, from 1 (January) to 12 (December). |
| day | body | Day of the month, from 1 to 31. |
| latitude | body | Latitude of the birth place in degrees, negative for south. Text in a local number format, such as "40,7128", is also accepted. |
| longitude | body | Longitude of the birth place in degrees east of Greenwich, negative for west, so places in the Americas are negative. Text in a local number format is also accepted. |
| timezone | body | Time zone of the birth place. Either an IANA time zone name, such as America/New_York, America/Chicago or Europe/London. Or a fixed offset from UTC in hours, such as -5 or 5.5. |
Optional inputs (8), with their defaults
| Name | In | What it does |
|---|---|---|
| as_of | query | Date to read the transits on, YYYY-MM-DD. Defaults to today; set it if you need the same response on every call. |
| lang | query | Language for the names in the response, such as planets, signs, nakshatras (lunar mansions), tithis (lunar days), months and festivals. The default is en (English); GET /v1/meta lists the others. Each translated value comes with its English original in a matching <field>_en field; use the English value as a key in your code. Codes (such as result or kaal) and object keys always stay in English. Any name not yet translated stays in English and is listed in localization.untranslated. |
| hour | body | Hour of birth on the local clock at the birth place, from 0 to 23 (24-hour clock). Default 0. |
| minute | body | Minute of birth, from 0 to 59. Default 0. |
| second | body | Second of birth, from 0 to 59. Default 0. |
| timezone_fold | body | Only needed for a local time that happens twice, on the night the clocks go back. In the US since 2007, that is 1:00 to 1:59 AM on the first Sunday in November. 0 picks the first occurrence (before the change) and 1 the second. Without it, such a time is rejected, not guessed. A wrong guess would quietly move the chart by an hour. A local time that never happens, because the clocks jumped forward over it, is also rejected; check the birth time, or send the UTC offset that was in force. |
| ayanamsa | body | The ayanamsa: the offset between the tropical zodiac (used in Western astrology) and the sidereal zodiac (used in Vedic astrology). lahiri (the default) is the Lahiri, or Chitrapaksha, ayanamsa used by the Government of India. kp is the Krishnamurti ayanamsa used in KP astrology, about 6 arcminutes less. raman is B. V. Raman's, about 1 degree 27 arcminutes less. Also: yukteshwar (Sri Yukteshwar's, about 1 degree 23 arcminutes less), jn_bhasin (J. N. Bhasin's, about 1 degree 6 arcminutes less), ushashashi (about 3 degrees 48 arcminutes less) and fagan_bradley (the Western sidereal zodiac, about 53 arcminutes more). true_chitra keeps the star Spica (Chitra) at exactly 180 degrees, so it follows the star itself; it is within about a minute of arc of Lahiri. The chosen ayanamsa is also used for the transits, sade sati and forecasts read against this chart. |
| node | body | How to calculate Rahu and Ketu, the lunar nodes (the two points where the Moon's orbit crosses the Sun's path). Use true for the actual position (the default) or mean for the averaged position. |
Main response fields
meta(object): holds ayanamsa, ayanamsa_value, julian_day, ephemeris, node, timezone.as_of(string)natal_moon_sign(string)ascendant_sign(string)transits(array of objects): each item holds graha, sign, sign_number, house_from_moon, house_from_ascendant, result, vedha_house, obstructed_by, obstructed, net, speed, retrograde.summary(object): holds favorable, unfavorable, obstructed.rule(string)
# 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"
}Example from a real call for John Doe, born Aug 15, 1990, 10:30 AM, New York. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Transits and forecasts.
Upcoming transit periods for a chart
POST /v1/transits/forecast
The forward-looking version of /v1/transits. That endpoint says where Saturn is now; this one says how long it stays and what comes next.
Each period is one planet in one house (counted from the birth Moon). It has its dates and the traditional result, and periods come in date order.
Vedha is not applied to future periods, on purpose. Vedha (one planet blocking another's effect) depends on where every other planet is. That changes many times during a period that can last years. So a single verdict would be wrong for most of it. result here is the result without vedha. For one specific day, call /v1/transits with that as_of.
A planet that changes house too often to be worth listing is left out. It is named in omitted, with a count. Over a year the Moon changes house about 160 times. In a window of 31 days or less the Moon is always listed.
Each period carries a reading: stay says what a stay of that planet's length means for your month or year, and about what the house brings. A stay running past to also carries leaves, the day it really ends. Takes ?lang and ?detail.
Transits (gochara) are counted from the birth Moon, because the traditional result tables are based on it. The house counted from the ascendant is also given, since many astrologers read it too. But no result is based on it here.
Dates allow for retrograde motion. A planet near a sign boundary often crosses it three times. So each re-entry is marked instead of being smoothed away.
Cost: Each successful request counts as 1 call toward your monthly calls.
Required inputs
| Name | In | What it is |
|---|---|---|
| year | body | Year of birth, from 1850 to 2149 (the range the planetary data covers). |
| month | body | Month of birth, from 1 (January) to 12 (December). |
| day | body | Day of the month, from 1 to 31. |
| latitude | body | Latitude of the birth place in degrees, negative for south. Text in a local number format, such as "40,7128", is also accepted. |
| longitude | body | Longitude of the birth place in degrees east of Greenwich, negative for west, so places in the Americas are negative. Text in a local number format is also accepted. |
| timezone | body | Time zone of the birth place. Either an IANA time zone name, such as America/New_York, America/Chicago or Europe/London. Or a fixed offset from UTC in hours, such as -5 or 5.5. |
Optional inputs (10), with their defaults
| Name | In | What it does |
|---|---|---|
| from | query | Start date, YYYY-MM-DD. Defaults to today. |
| to | query | End date, YYYY-MM-DD. Defaults to one year after the start. |
| lang | query | Language of the reading text, such as en (English, the default) or hi (Hindi). GET /v1/meta lists the languages available. If a passage is not written in that language yet, the English passage is returned instead and marked with fell_back_to_en. Names in the response, such as planets and signs, are translated too. |
| detail | query | Length of the reading text: standard (the default) or expanded, which is about 1.8 times longer. If a passage has no expanded version yet, the standard one is returned. Each text block reports the length it got in its detail field. |
| hour | body | Hour of birth on the local clock at the birth place, from 0 to 23 (24-hour clock). Default 0. |
| minute | body | Minute of birth, from 0 to 59. Default 0. |
| second | body | Second of birth, from 0 to 59. Default 0. |
| timezone_fold | body | Only needed for a local time that happens twice, on the night the clocks go back. In the US since 2007, that is 1:00 to 1:59 AM on the first Sunday in November. 0 picks the first occurrence (before the change) and 1 the second. Without it, such a time is rejected, not guessed. A wrong guess would quietly move the chart by an hour. A local time that never happens, because the clocks jumped forward over it, is also rejected; check the birth time, or send the UTC offset that was in force. |
| ayanamsa | body | The ayanamsa: the offset between the tropical zodiac (used in Western astrology) and the sidereal zodiac (used in Vedic astrology). lahiri (the default) is the Lahiri, or Chitrapaksha, ayanamsa used by the Government of India. kp is the Krishnamurti ayanamsa used in KP astrology, about 6 arcminutes less. raman is B. V. Raman's, about 1 degree 27 arcminutes less. Also: yukteshwar (Sri Yukteshwar's, about 1 degree 23 arcminutes less), jn_bhasin (J. N. Bhasin's, about 1 degree 6 arcminutes less), ushashashi (about 3 degrees 48 arcminutes less) and fagan_bradley (the Western sidereal zodiac, about 53 arcminutes more). true_chitra keeps the star Spica (Chitra) at exactly 180 degrees, so it follows the star itself; it is within about a minute of arc of Lahiri. The chosen ayanamsa is also used for the transits, sade sati and forecasts read against this chart. |
| node | body | How to calculate Rahu and Ketu, the lunar nodes (the two points where the Moon's orbit crosses the Sun's path). Use true for the actual position (the default) or mean for the averaged position. |
Main response fields
meta(object): holds ayanamsa, ayanamsa_value, julian_day, ephemeris, node, timezone.from(string)to(string)natal_moon_sign(string)periods(array of objects): each item holds graha, house_from_moon, sign, starts, ends, entry_known, exit_known, resumes_visit, result, vedha_house, bindus, strength.omitted(array of objects): each item holds graha, reason.vedha_applied(boolean)rule(string)
# John Doe, born Aug 15, 1990, 10:30 AM, New York
curl -X POST "https://apiforastrology.com/api/astrology/v1/transits/forecast?from=2026-10-01&to=2026-12-31" \
-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"
}
},
"from": "2026-10-01T00:00:00",
"to": "2026-12-31T00:00:00",
"natal_moon_sign": "Taurus",
"periods": [
{
"graha": "Sun",
"house_from_moon": 5,
"sign": "Virgo",
"starts": "2026-10-01T00:00:00",
"ends": "2026-10-17T10:21:43",
"entry_known": false,
"exit_known": true,
"resumes_visit": false,
"result": "unfavorable",
"vedha_house": null,
"bindus": 1,
"strength": "weak",
"reading": {
"stay": [
"The Sun stays in one sign for about a month, so this asks for care through most of your month. Until October 17, things around children, learning and whatever you make may need more patience, and pride can get in the way. What you can do:…"
],
"about": [
"Counted from your Moon sign, the fifth house covers children, learning, judgment and the things you create. The Sun brings confidence, and during its month here that is exactly the risk. **From the inside, confidence and good judgment feel…",
"What you can do: keep your money out of speculation this month, because your confidence makes a risk look smaller than it is. If someone criticizes your idea, listen before you defend it. Creative work and teaching can still go well when…"
],
"language": "en",
"detail": "standard"
}
},
{
"graha": "Mars",
"house_from_moon": 3,
"sign": "Cancer",
"starts": "2026-10-01T00:00:00",
"ends": "2026-11-12T09:48:38",
"entry_known": false,
"exit_known": true,
"resumes_visit": false,
"result": "favorable",
"vedha_house": 12,
"bindus": 4,
"strength": "moderate",
"reading": {
"stay": [
"Mars usually stays about six weeks in one sign, and much longer when it turns back. Until November 12, it gives drive and courage for your own effort, your nerve, and brothers and sisters. What you can do: pick one hard task here and…"
],
"about": [
"Transits are counted from your Moon sign. The third house from it covers effort, courage, short trips and your brothers and sisters. Mars is the planet of drive and nerve, exactly what this house needs. **Its stay of about six weeks here…",
"What you can do: this is your window for the hard push. That could be the confrontation, the deadline or the job that needs force more than skill. What you get done now often lasts after the transit ends. Leave delicate work for another…"
],
"language": "en",
"detail": "standard"
}
},
{
"graha": "Mercury",
"house_from_moon": 6,
"sign": "Libra",
"starts": "2026-10-01T00:00:00",
"ends": "2026-12-02T06:57:31",
"entry_known": false,
"exit_known": true,
"resumes_visit": false,
"result": "favorable",
"vedha_house": 9,
"bindus": 6,
"strength": "strong",
"reading": {
"stay": [
"Mercury usually stays in one sign for three to four weeks, and longer when it turns back. Until December 2, it helps talks, paperwork and clear thinking about daily work, health, competition and debt. What you can do: write down what you…"
],
"about": [
"The sixth house, counted from your Moon sign, covers disputes, debts, daily work and health. Mercury handles all of these through detail, and right now you have the detail. **So its three to four weeks here are one of its strong transits…",
"What you can do: bring the dispute, the debt and the health question to these weeks. Watch your tone, though, because being precise can sound like criticism. A colleague you correct now, even rightly, may remember it later."
],
"language": "en",
"detail": "standard"
}
}
],
"omitted": [
{
"graha": "Moon",
"reason": "changes house 41 times in this window, more than the 14 a timeline lists. Narrow the window, or read it from /v1/transits/ingresses/Moon."
}
],
"vedha_applied": false,
"rule": "house counted from the natal Moon; result from the classical gochara table. Vedha is not applied to a future period -- see /v1/transits for a given day."
}Example from a real call for John Doe, born Aug 15, 1990, 10:30 AM, New York. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Transits and forecasts.
When a planet enters and leaves each sign
POST /v1/transits/ingresses/{graha}
Returns the sign-by-sign calendar for one planet over a date range, in date order. An ingress is a planet entering a new sign.
Retrograde motion can take a planet back into a sign it just left. The return is then a separate row with resumes_visit: true. This matches what actually happens and how printed planetary tables show it. For example, Jupiter moves from Gemini into Cancer, goes back into Gemini for a while, then enters Cancer again. Merging those rows would hide a real event.
entry_known and exit_known are false when the start or end of the date range cuts a row off. They are true when an actual ingress starts or ends it.
Fast planets cannot be scanned over long ranges (the Moon changes sign about every two and a quarter days). A range that is too wide is rejected with a 422 error (window_too_wide) instead of being served slowly.
Transits (gochara) are counted from the birth Moon, because the traditional result tables are based on it. The house counted from the ascendant is also given, since many astrologers read it too. But no result is based on it here.
Dates allow for retrograde motion. A planet near a sign boundary often crosses it three times. So each re-entry is marked instead of being smoothed away.
Cost: Each successful request counts as 1 call toward your monthly calls.
Required inputs
| Name | In | What it is |
|---|---|---|
| graha | path | The transiting planet (graha), such as Saturn. |
| year | body | Year of birth, from 1850 to 2149 (the range the planetary data covers). |
| month | body | Month of birth, from 1 (January) to 12 (December). |
| day | body | Day of the month, from 1 to 31. |
| latitude | body | Latitude of the birth place in degrees, negative for south. Text in a local number format, such as "40,7128", is also accepted. |
| longitude | body | Longitude of the birth place in degrees east of Greenwich, negative for west, so places in the Americas are negative. Text in a local number format is also accepted. |
| timezone | body | Time zone of the birth place. Either an IANA time zone name, such as America/New_York, America/Chicago or Europe/London. Or a fixed offset from UTC in hours, such as -5 or 5.5. |
Optional inputs (9), with their defaults
| Name | In | What it does |
|---|---|---|
| from | query | Start date, YYYY-MM-DD. Defaults to today. |
| to | query | End date, YYYY-MM-DD. Defaults to five years after the start. |
| lang | query | Language for the names in the response, such as planets, signs, nakshatras (lunar mansions), tithis (lunar days), months and festivals. The default is en (English); GET /v1/meta lists the others. Each translated value comes with its English original in a matching <field>_en field; use the English value as a key in your code. Codes (such as result or kaal) and object keys always stay in English. Any name not yet translated stays in English and is listed in localization.untranslated. |
| hour | body | Hour of birth on the local clock at the birth place, from 0 to 23 (24-hour clock). Default 0. |
| minute | body | Minute of birth, from 0 to 59. Default 0. |
| second | body | Second of birth, from 0 to 59. Default 0. |
| timezone_fold | body | Only needed for a local time that happens twice, on the night the clocks go back. In the US since 2007, that is 1:00 to 1:59 AM on the first Sunday in November. 0 picks the first occurrence (before the change) and 1 the second. Without it, such a time is rejected, not guessed. A wrong guess would quietly move the chart by an hour. A local time that never happens, because the clocks jumped forward over it, is also rejected; check the birth time, or send the UTC offset that was in force. |
| ayanamsa | body | The ayanamsa: the offset between the tropical zodiac (used in Western astrology) and the sidereal zodiac (used in Vedic astrology). lahiri (the default) is the Lahiri, or Chitrapaksha, ayanamsa used by the Government of India. kp is the Krishnamurti ayanamsa used in KP astrology, about 6 arcminutes less. raman is B. V. Raman's, about 1 degree 27 arcminutes less. Also: yukteshwar (Sri Yukteshwar's, about 1 degree 23 arcminutes less), jn_bhasin (J. N. Bhasin's, about 1 degree 6 arcminutes less), ushashashi (about 3 degrees 48 arcminutes less) and fagan_bradley (the Western sidereal zodiac, about 53 arcminutes more). true_chitra keeps the star Spica (Chitra) at exactly 180 degrees, so it follows the star itself; it is within about a minute of arc of Lahiri. The chosen ayanamsa is also used for the transits, sade sati and forecasts read against this chart. |
| node | body | How to calculate Rahu and Ketu, the lunar nodes (the two points where the Moon's orbit crosses the Sun's path). Use true for the actual position (the default) or mean for the averaged position. |
Main response fields
meta(object): holds ayanamsa, ayanamsa_value, julian_day, ephemeris, node, timezone.graha(string)from(string)to(string)ingresses(array of objects): each item holds sign, sign_number, enters, leaves, entry_known, exit_known, resumes_visit, retrograde_re_entry.
# John Doe, born Aug 15, 1990, 10:30 AM, New York
curl -X POST "https://apiforastrology.com/api/astrology/v1/transits/ingresses/Saturn?from=2026-10-01&to=2026-12-31" \
-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"
}
},
"graha": "Saturn",
"from": "2026-10-01T00:00:00",
"to": "2026-12-31T00:00:00",
"ingresses": [
{
"sign": "Pisces",
"sign_number": 12,
"enters": "2026-10-01T00:00:00",
"leaves": "2026-12-31T00:00:00",
"entry_known": false,
"exit_known": false,
"resumes_visit": false,
"retrograde_re_entry": false
}
]
}Example from a real call for John Doe, born Aug 15, 1990, 10:30 AM, New York. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Transits and forecasts.
When a transiting planet passes over a birth-chart point
POST /v1/transits/over/{graha}
Returns the periods when the transiting planet (graha) moves through the sign of a point in the birth chart. Use target=Moon for the traditional "Saturn over the Moon", target=ascendant for the rising sign, or any planet name.
The birth-chart point is reduced to its sign, because this API uses whole-sign houses throughout. So this means Saturn anywhere in the Moon's sign, not Saturn within a few degrees of the Moon. A degree-based conjunction would make a distinction the whole-sign house model cannot express.
Retrograde motion can take the planet briefly out of the sign. The result is then one period with a break in it, not two periods.
Transits (gochara) are counted from the birth Moon, because the traditional result tables are based on it. The house counted from the ascendant is also given, since many astrologers read it too. But no result is based on it here.
Dates allow for retrograde motion. A planet near a sign boundary often crosses it three times. So each re-entry is marked instead of being smoothed away.
Cost: Each successful request counts as 1 call toward your monthly calls.
Required inputs
| Name | In | What it is |
|---|---|---|
| graha | path | The transiting planet (graha), such as Saturn. |
| year | body | Year of birth, from 1850 to 2149 (the range the planetary data covers). |
| month | body | Month of birth, from 1 (January) to 12 (December). |
| day | body | Day of the month, from 1 to 31. |
| latitude | body | Latitude of the birth place in degrees, negative for south. Text in a local number format, such as "40,7128", is also accepted. |
| longitude | body | Longitude of the birth place in degrees east of Greenwich, negative for west, so places in the Americas are negative. Text in a local number format is also accepted. |
| timezone | body | Time zone of the birth place. Either an IANA time zone name, such as America/New_York, America/Chicago or Europe/London. Or a fixed offset from UTC in hours, such as -5 or 5.5. |
Optional inputs (10), with their defaults
| Name | In | What it does |
|---|---|---|
| target | query | The birth-chart point to watch: a planet name, or ascendant. Default Moon. |
| from | query | Start date, YYYY-MM-DD. Defaults to today. |
| to | query | End date, YYYY-MM-DD. Defaults to 20 years after the start. |
| lang | query | Language for the names in the response, such as planets, signs, nakshatras (lunar mansions), tithis (lunar days), months and festivals. The default is en (English); GET /v1/meta lists the others. Each translated value comes with its English original in a matching <field>_en field; use the English value as a key in your code. Codes (such as result or kaal) and object keys always stay in English. Any name not yet translated stays in English and is listed in localization.untranslated. |
| hour | body | Hour of birth on the local clock at the birth place, from 0 to 23 (24-hour clock). Default 0. |
| minute | body | Minute of birth, from 0 to 59. Default 0. |
| second | body | Second of birth, from 0 to 59. Default 0. |
| timezone_fold | body | Only needed for a local time that happens twice, on the night the clocks go back. In the US since 2007, that is 1:00 to 1:59 AM on the first Sunday in November. 0 picks the first occurrence (before the change) and 1 the second. Without it, such a time is rejected, not guessed. A wrong guess would quietly move the chart by an hour. A local time that never happens, because the clocks jumped forward over it, is also rejected; check the birth time, or send the UTC offset that was in force. |
| ayanamsa | body | The ayanamsa: the offset between the tropical zodiac (used in Western astrology) and the sidereal zodiac (used in Vedic astrology). lahiri (the default) is the Lahiri, or Chitrapaksha, ayanamsa used by the Government of India. kp is the Krishnamurti ayanamsa used in KP astrology, about 6 arcminutes less. raman is B. V. Raman's, about 1 degree 27 arcminutes less. Also: yukteshwar (Sri Yukteshwar's, about 1 degree 23 arcminutes less), jn_bhasin (J. N. Bhasin's, about 1 degree 6 arcminutes less), ushashashi (about 3 degrees 48 arcminutes less) and fagan_bradley (the Western sidereal zodiac, about 53 arcminutes more). true_chitra keeps the star Spica (Chitra) at exactly 180 degrees, so it follows the star itself; it is within about a minute of arc of Lahiri. The chosen ayanamsa is also used for the transits, sade sati and forecasts read against this chart. |
| node | body | How to calculate Rahu and Ketu, the lunar nodes (the two points where the Moon's orbit crosses the Sun's path). Use true for the actual position (the default) or mean for the averaged position. |
Main response fields
meta(object): holds ayanamsa, ayanamsa_value, julian_day, ephemeris, node, timezone.graha(string)target(string)natal_sign(string)from(string)to(string)windows(array)
# John Doe, born Aug 15, 1990, 10:30 AM, New York
curl -X POST "https://apiforastrology.com/api/astrology/v1/transits/over/Saturn?from=2026-10-01&to=2026-12-31" \
-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"
}
},
"graha": "Saturn",
"target": "Moon",
"natal_sign": "Taurus",
"from": "2026-10-01T00:00:00",
"to": "2026-12-31T00:00:00",
"windows": []
}Example from a real call for John Doe, born Aug 15, 1990, 10:30 AM, New York. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Transits and forecasts.
Planet positions at a moment, no chart
GET /v1/sky
Returns every planet's position at one moment: sign, degree, nakshatra (lunar mansion) and pada (quarter of a nakshatra). It also says whether each planet is retrograde (appears to move backward) or combust (too close to the Sun). This is the sky for everyone, so it needs no birth data and has no houses.
The positions and the combustion rule are the same ones the transit and birth chart endpoints use. So this endpoint always agrees with them. Rahu and Ketu are always reported as retrograde, as everywhere in this API, because tradition treats them that way; speed still gives their actual motion.
Cost: Each successful request counts as 1 call toward your monthly calls.
Required inputs
None.
Optional inputs (4), with their defaults
| Name | In | What it does |
|---|---|---|
| at | query | Local date, or date and time, in timezone, such as 2026-09-24 or 2026-09-24T11:05. Defaults to now. |
| timezone | query | IANA time zone name such as America/New_York, or a fixed offset from UTC in hours such as -5. Defaults to 5.5 (India time). |
| node | query | How to calculate Rahu and Ketu, the lunar nodes: true (the actual position, the default) or mean (the averaged position). It works as on every endpoint that takes birth data. |
| lang | query | Language for the names in the response, such as planets, signs, nakshatras (lunar mansions), tithis (lunar days), months and festivals. The default is en (English); GET /v1/meta lists the others. Each translated value comes with its English original in a matching <field>_en field; use the English value as a key in your code. Codes (such as result or kaal) and object keys always stay in English. Any name not yet translated stays in English and is listed in localization.untranslated. |
Main response fields
at(string)timezone(number)timezone_info(object): holds source, offset_hours, zone, abbreviation, dst, note.grahas(array of objects): each item holds graha, longitude, sign, sign_number, degree_in_sign, nakshatra, nakshatra_lord, pada, speed, retrograde, combust.meta(object): holds ayanamsa, ayanamsa_value, node, ephemeris.
curl "https://apiforastrology.com/api/astrology/v1/sky?at=2026-10-01T12%3A00" \
-H "Authorization: Bearer $ASTROLOGY_API_KEY"{
"at": "2026-10-01T12:00:00",
"timezone": 5.5,
"timezone_info": {
"source": "offset",
"offset_hours": 5.5,
"zone": null,
"abbreviation": null,
"dst": null,
"note": "supplied as a fixed offset; no zone history consulted"
},
"grahas": [
{
"graha": "Sun",
"longitude": 163.8718583,
"sign": "Virgo",
"sign_number": 6,
"degree_in_sign": 13.8718583,
"nakshatra": "Hast",
"nakshatra_lord": "Moon",
"pada": 2,
"speed": 0.982819,
"retrograde": false,
"combust": false
},
{
"graha": "Moon",
"longitude": 43.5419146,
"sign": "Taurus",
"sign_number": 2,
"degree_in_sign": 13.5419146,
"nakshatra": "Rohini",
"nakshatra_lord": "Moon",
"pada": 2,
"speed": 14.283441,
"retrograde": false,
"combust": false
},
{
"graha": "Mars",
"longitude": 97.6130163,
"sign": "Cancer",
"sign_number": 4,
"degree_in_sign": 7.6130163,
"nakshatra": "Pushya",
"nakshatra_lord": "Saturn",
"pada": 2,
"speed": 0.582319,
"retrograde": false,
"combust": false
}
],
"meta": {
"ayanamsa": "lahiri",
"ayanamsa_value": 24.2307564,
"node": "true",
"ephemeris": "JPL DE440s"
}
}Example from a real call. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Transits and forecasts.
Calendar of sky events, no chart
GET /v1/sky/events
Returns the sky events between two dates. They are ingresses (a planet entering a new sign), and retrograde periods with their stations (when a planet appears to stop and turn). They also include combustion periods (a planet too close to the Sun). The last are the tracked conjunctions: Venus with Jupiter, and the Sun with Mars. These are the same events /v1/forecast/annual places in a chart, before any chart is involved.
Events are calculated one calendar year at a time. An event that runs across New Year is joined into one. So Jupiter entering Leo on October 31 reads as one stay, not two. The calculation starts a year before from, so an event already running has its real start date. If it started even earlier, starts_known is false, instead of a date that only marks where the calculation began. started_before_the_window and runs_past_the_window say how each event sits against the dates you asked for.
Each calendar year is calculated once and then cached; the first request for a year takes about 2.5 seconds.
Dates are in timezone. With a zone name such as America/Los_Angeles, each date uses the offset in force on that date. So daylight saving time is followed. timezone and timezone_info in the response describe the from date.
Stations are facts. Combustion and conjunctions depend on an orb (how close two bodies must be to count as together). Each event states the orb it used. The Moon is left out, because it changes sign about every two days.
Cost: Each successful request counts as 1 call toward your monthly calls.
Required inputs
None.
Optional inputs (6), with their defaults
| Name | In | What it does |
|---|---|---|
| from | query | Start date, YYYY-MM-DD. Defaults to today. |
| to | query | End date, YYYY-MM-DD. Defaults to one year after from, and can be at most two years after it. |
| timezone | query | IANA time zone name such as America/New_York, or a fixed offset from UTC in hours such as -5. Defaults to 5.5 (India time). |
| kind | query | Which kinds of event to return, as a comma-separated list of ingress, retrograde, combust and conjunction. Default: all. |
| node | query | How to calculate Rahu and Ketu, the lunar nodes: true (the actual position, the default) or mean (the averaged position). It works as on every endpoint that takes birth data. |
| lang | query | Language for the names in the response, such as planets, signs, nakshatras (lunar mansions), tithis (lunar days), months and festivals. The default is en (English); GET /v1/meta lists the others. Each translated value comes with its English original in a matching <field>_en field; use the English value as a key in your code. Codes (such as result or kaal) and object keys always stay in English. Any name not yet translated stays in English and is listed in localization.untranslated. |
Main response fields
from(string)to(string)timezone(number)timezone_info(object): holds source, offset_hours, zone, abbreviation, dst, note.events(array of objects): each item holds kind, graha, starts, ends, starts_at, ends_at, sign, starts_known, ends_known, started_before_the_window, runs_past_the_window.counts(object): holds ingress, retrograde, combust, conjunction.note(string)
curl "https://apiforastrology.com/api/astrology/v1/sky/events?from=2026-10-01&to=2026-12-31" \
-H "Authorization: Bearer $ASTROLOGY_API_KEY"{
"from": "2026-10-01",
"to": "2026-12-31",
"timezone": 5.5,
"timezone_info": {
"source": "offset",
"offset_hours": 5.5,
"zone": null,
"abbreviation": null,
"dst": null,
"note": "supplied as a fixed offset; no zone history consulted"
},
"events": [
{
"kind": "ingress",
"graha": "Saturn",
"starts": "2025-03-29",
"ends": "2027-01-01",
"starts_at": "2025-03-29T21:45+05:30",
"ends_at": "2027-01-01T00:00+05:30",
"sign": "Pisces",
"starts_known": true,
"ends_known": false,
"started_before_the_window": true,
"runs_past_the_window": true
},
{
"kind": "ingress",
"graha": "Ketu",
"starts": "2025-05-30",
"ends": "2026-11-25",
"starts_at": "2025-05-30T00:17+05:30",
"ends_at": "2026-11-25T17:45+05:30",
"sign": "Leo",
"starts_known": true,
"ends_known": true,
"started_before_the_window": true,
"runs_past_the_window": false
},
{
"kind": "ingress",
"graha": "Rahu",
"starts": "2025-05-30",
"ends": "2026-11-25",
"starts_at": "2025-05-30T00:17+05:30",
"ends_at": "2026-11-25T17:45+05:30",
"sign": "Aquarius",
"starts_known": true,
"ends_known": true,
"started_before_the_window": true,
"runs_past_the_window": false
}
],
"counts": {
"ingress": 19,
"retrograde": 4,
"combust": 3,
"conjunction": 0
},
"note": "Ingresses and stations are facts. Combustion and conjunction windows depend on an orb; each event states it. The Moon is left out."
}Example from a real call. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Transits and forecasts.
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 arc seconds. An arc second is 1/3,600 of a degree. A practicing astrologer reviews the rules behind these answers. See how we test accuracy.
Related pages
- Features: Transits and forecasts.
- Used for: Astrology apps, Publishers and media, Astrologer consultation platforms.
- Rules: Transits (gochar), Annual forecast.
- Guides: Quickstart, Conventions, Errors, Changelog.
