Developer API · beta

Vedic astrology, as an API

Sidereal charts, life periods (daśā), plain-language guidance, domain readings, compatibility and muhūrta, computed by a deterministic Jyotish engine in classical Vedic methodology. JSON in, JSON out, one key.

Ephemeris built in. Raw planet positions, cusps, ayanamsa and sunrise from our own engine, built on NASA JPL’s DE440 ephemeris, on the same key: no Swiss Ephemeris licence or second ephemeris API needed.

Sandbox keys are free with no time limit and return fixed sample responses. Every account also gets 100 free live credits once (not monthly), valid for 60 days from your first live key and spent before paid credits. When they are used up or expire, live calls return 402 credits_exhausted until you buy a pack; sandbox keys keep working. Free terms

100
free live credits, once (60 days)
Free
sandbox keys, no time limit
120/min
rate limit
2xx only
charged

Why AstroNest

What you get here and not elsewhere

Each of these is something you can check yourself with a free sandbox key.

Compatibility beyond the guna score

The 36-point Aṣṭakūṭa is one input. The verdict weighs each chart's marital promise and doṣas, names the governing factor, and says when it overrides the score.

/v1/compatibility

Manglik from the lagna, the Moon and Venus

All three classical reckonings, with mutual cancellation. A chart clean from the lagna can carry the doṣa from the Moon or Venus, and the response shows which.

/v1/guna-milan, /v1/compatibility

Joint marriage timing

Compatibility finds when both charts' periods open together, not only whether the two match.

/v1/compatibility

Deterministic interpretation

Interpret, guidance, compatibility and guna milan call no language model: the same chart always gets the same reading. Only forecast and timing are voiced by a model, and they are marked as such.

/v1/interpret, /v1/guidance, /v1/compatibility, /v1/guna-milan

Readings grounded in classical Vedic methodology

Interpretation applies classical rules, and each reading names the classical texts it is grounded in.

/v1/interpret

Nothing silently missing

Every reading declares each of its layers as present, computed_empty, not_covered or failed, so an absent field is never left to guesswork.

/v1/interpret and the other readings

Birth-time sensitivity, stated

Where an uncertain birth time would change the reading, the compatibility response says so.

/v1/compatibility

Muhūrta at the event's place

The pañcāṅga for a muhūrta is computed where the event happens, never defaulted to the birthplace.

/v1/muhurta

Guidance for the running periods

What the current daśā chapter, period and stretch ask of the person: conduct to keep, with the classical reason for each.

/v1/guidance

Jyotiṣa, Western and relocation in one call

One chart call returns the sidereal chart with yogas and daśā, tropical positions and aspects, astrocartography lines, and the house frame relocated to any place.

/v1/chart

Our own engine, on NASA JPL's DE440 ephemeris

Positions come from AstroNest's own engine, which reads NASA JPL's DE440 ephemeris directly, not a wrapper around Swiss Ephemeris, and raw positions, cusps, ayanamsa and sunrise are sold on the same key.

/v1/ephemeris/*

Built for AI agents

A Model Context Protocol server with typed inputs and outputs, listed in the official MCP Registry and on Smithery.

/api/developer/mcp

A sandbox that returns real responses

Sandbox keys are free with no time limit and return captured production responses, never mock data, so you build against the real shape.

every endpoint

Ephemeris built in

No second provider for raw positions

The 5 Ephemeris operations — positions, ascendant and house cusps, ayanamsa values, sunrise and sunset, and position series — run on AstroNest's own engine, built on NASA JPL's DE440 ephemeris, on the same key and the same credits as the readings. You do not need a Swiss Ephemeris licence or a separate ephemeris API.

Ephemeris reference
12 bodies
Sun to Pluto, mean and true Rāhu (Ketu = node + 180°)
3 house systems
whole sign, equal, Placidus
4 ayanamsas
Lahiri, Raman, Krishnamurti, Fagan–Bradley, or tropical
1800–2149
UTC coverage, about a millisecond per position

0.1 credit per call: 1 credit per started block of 10 calls (series: 1 per started 100 points). Not covered: asteroids, fixed stars, and dates outside 1800–2149.

Quickstart

Your first call in three steps

  1. Sign in at /developer and create a sandbox key. Sandbox calls are free, with no time limit, and return fixed sample responses.
  2. Call any endpoint. A sandbox key validates your request exactly as live does, then returns a fixed sample response.
  3. When your integration works, create a live key for real readings. Your account gets 100 free live credits once, valid for 60 days from your first live key; after that, buy a credit pack. See the free terms.
curl -X POST https://www.astronest.ai/api/developer/v1/chart \
  -H "Authorization: Bearer astro_sandbox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209}}'

Call the API from your server. Keys are secret, and the API sends no CORS headers, so browser calls fail by design.

Keys

Live and sandbox

KeyWhat it returnsCost
astro_sandbox_…Validates your request with the same error codes as live, then returns a fixed sample (the example on each endpoint below), marked sandbox: true and with an X-AstroNest-Sandbox: true header. Your inputs are checked, not used.Free, no time limit
astro_live_…A real computation for the birth data you send.Credits per call

Send the key as Authorization: Bearer <key>. Each key is scoped to the endpoints you choose; all keys on an account share one credit balance. The secret is shown once; if you lose it, rotate the key in the portal.

Credits and pricing

Free to start, pay as you go

Every account gets 100 free live credits once, spent first. They do not renew and are valid for 60 days from your first live key; any left after that expire. Beyond that, buy a pack in the portal. Paid credits are one-time purchases and do not expire. Only successful (2xx) calls are charged; a failed call costs nothing. When credits run out the API answers 402 credits_exhausted.

Free terms

Free to start: sandbox keys, plus 100 free live credits once

Sandbox key — free, no time limit

  • Every endpoint and MCP tool answers with a fixed sample response; your input is validated exactly as live, never used.
  • Never charged and never expires. Limits: 120 requests a minute, 2 at a time.
  • It does not compute real readings: for that you need a live key.

100 free live credits — once, valid 60 days

  • Granted once per account, for live keys. A live key needs the beta terms accepted and a verified email.
  • Valid for 60 days from when you create your first live key; any left after that expire. They do not renew.
  • Spent before any paid credits, on successful calls only (a chart costs 1, a domain reading 5).

When the free credits are used up or expire

  • After 100 credits or 60 days, whichever comes first, live calls return 402 credits_exhausted. Nothing is charged automatically: sandbox keys keep working, and your keys and settings stay.

What to do next

  • Buy a credit pack in the portal: Starter $49 for 1,000 credits, Builder $199 for 5,000, Growth $499 for 15,000. One-time purchases, no subscription; paid credits never expire.
  • High volume or a platform? Talk to us about Platform (custom pricing).

starter

$49

1,000 credits · 4.9¢ each

builder

$199

5,000 credits · 4.0¢ each

growth

$499

15,000 credits · 3.3¢ each

Platform

Custom pricing

Volume pricing · Higher concurrency · Dedicated support · Commercial SLA

Talk to us →

For astrology platforms, practitioner networks, matchmaking services and high-volume applications. Volume pricing · Higher concurrency · Dedicated support · Commercial SLA · Custom integration · Consolidated billing. Talk to us.

Ephemeris calls are fractional. Positions, angles, ayanamsa and sunrise cost 0.1 credit each: the call that opens each block of 10 is charged 1 credit and the next nine are free, counted across the four per account. Failed calls do not count. A series costs 1 credit per started 100 points.

Free accounts may run 2 requests at once; buying any pack raises that to 5.

Endpoints

Reference

Base URL https://www.astronest.ai/api/developer. Every endpoint is POST with a JSON body. Full request and response schemas are in the OpenAPI spec; the OpenAPI guide shows how to import it into Postman, generate a client, or connect an AI app over MCP. The MCP server is listed on Smithery and in the official MCP Registry, and every endpoint is ready to send in our public Postman workspace.

EndpointWhat it doesCredits
/v1/chartNatal chart (kundli) Calculation1
/v1/dashaLife-period timeline (planetary periods) Calculation1
/v1/techniquesClassical techniques for a chart Calculation3
/v1/guna-milanGuna Milan (36-point Aṣṭakūṭa) and Manglik Calculation2
/v1/guidanceGuidance for the running daśā periods Interpretation3
/v1/prashnaPraśna (horary): a question, a deal, or a horary number Interpretation3
/v1/interpretReading of one life area Interpretation5
/v1/life-readingWhole-life reading Interpretation10
/v1/domain-timelineLife-area timeline Interpretation3
/v1/relationshipRelationship reading (non-marital) Interpretation8
/v1/venture-timingVenture timing: when to commit, which business Interpretation10
/v1/gem-assessmentGemstone assessment Interpretation5
/v1/compatibilityMarriage compatibility: the full reading Interpretation12
/v1/muhurtaAuspicious windows (muhūrta) in a date range Interpretation10
/v1/forecastWritten answer about what lies ahead Narrated8
/v1/timing/resolveIs this a good time? (decision timing) Narrated7
/v1/ephemeris/positionsPositions at a moment Ephemeris0.1
/v1/ephemeris/anglesAscendant, MC and house cusps Ephemeris0.1
/v1/ephemeris/ayanamsaAyanamsa values Ephemeris0.1
/v1/ephemeris/sunriseSunrise and sunset Ephemeris0.1
/v1/ephemeris/seriesPositions over a range Ephemeris1

Calculation

Deterministic computation. No language model is called.

POST/v1/chart

1 credit

Natal chart (kundli).

Use it when someone wants their birth chart (kundli): ascendant, planets in signs and houses, yogas, the current planetary periods, or one of the classical sub-charts.

Sidereal chart: ascendant, the nine grahas, twelve houses, yogas and the life-period (daśā) timeline. A modern Western block is added unless `western` is false. With `location`, also astrocartography lines at that place and the chart's own frame relocated there. Includes two classical sub-charts by default; ask for any of the others with `divisionals`.

Required: birthData

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  }
}

POST/v1/dasha

1 credit

Life-period timeline (planetary periods).

Use it when someone asks which planetary period (daśā) they are in, when it ends, or which periods are coming.

The current periods include the running pratyantardaśā; send depth 'pratyantardasha' for the full timeline at that level.

Required: birthData

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  }
}

POST/v1/techniques

3 credits

Classical techniques for a chart.

Use it when someone or an astrologer asks for a specific classical computation — planetary strength, transit point tables, another life-period timeline, the annual chart, house cusps, a named yoga, the birth pañcāṅga, Manglik, house lords and aspects — rather than for a reading. Pass `sections` to fetch only what is needed.

The computed classical working for a chart, no model: strength scores for each planet and house, point tables for transit support, further life-period timelines with the periods running at `referenceDate`, the full planetary-period ladder, the annual chart for the year running at `referenceDate`, house-cusp and ruling-planet tables, classical yogas, special ascendants and aspects, the natal pañcāṅga, house lords with planetary aspects, Manglik (Kuja doṣa) with its exceptions, and what would change under another ayanāṁśa. Each section is `{computed: true, data}` or `{computed: false, reason}` — a technique that cannot be computed for this chart (for example without a birth time) says why and the rest still return. No verdicts, scores or lifespan figures.

Required: birthData

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  },
  "sections": [
    "shadbala",
    "dashas",
    "panchanga"
  ],
  "referenceDate": "2026-10-14T00:00:00Z"
}

POST/v1/guna-milan

2 credits

Guna Milan (36-point Aṣṭakūṭa) and Manglik.

Use it when someone asks for the guna milan / kundli matching score (out of 36), or whether either person is Manglik.

The classical Aṣṭakūṭa match for a pair (all eight kūṭas, with the Bhakoot and Nāḍī doṣas) and Manglik for both charts reckoned from the lagna, the Moon and Venus, with mutual cancellation. The same engine as /v1/compatibility, without the full reading: the score is one input, and /v1/compatibility reads each chart's marital promise, timing and doṣas on top of it. Deterministic, no language model.

Required: a, b

{
  "a": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209,
    "name": "A"
  },
  "b": {
    "date": "1991-11-03",
    "time": "06:10",
    "timezone": "Asia/Kolkata",
    "latitude": 19.076,
    "longitude": 72.8777,
    "name": "B"
  }
}

Interpretation

Deterministic readings in classical Vedic methodology. No language model is called.

POST/v1/guidance

3 credits

Guidance for the running daśā periods.

Use it when someone asks how to conduct themselves in the period they are in: what to do and what to take care with, each with its classical reason. Guidance, not prediction.

Plain-language guidance cards for each running daśā level (mahādaśā, antardaśā, …) at `referenceDate` (default: now).

Required: birthData

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  }
}

POST/v1/prashna

3 credits

Praśna (horary): a question, a deal, or a horary number.

Use it when someone asks a specific question and wants it answered from the moment of asking rather than from a birth chart — "will this deal close?", "will I recover?", "will I find what I lost?" — or when an astrologer gives a horary number 1–249. Send where the user is as `place`; it is never defaulted.

The chart of the moment and place a question is asked, read on classical praśna rules, no model. Always: the praśna lagna and its lord, the Moon, the house of the matter asked about, the classical rules that apply (recovery from illness for a health question; recovery of a lost article when the question names one), and the further classical rules that held on this chart, each with its reference and the chart facts that made it hold. With `deal`: the deal praśna — significators (lagna lord = you, 7th = the other side, 10th = the undertaking, 11th = gain), their planetary contacts, the grounds for and against, and an ordered verdict (perfects, perfects after obstacles, contested, delayed, delayed and contested, not perfected); add `birthData` for the natal commitment calendar beside it, never blended with it. With `horaryNumber` (1–249): the horary table — house cusps for the moment that number rises, planets at the moment of judgment, their ruling lords, and the ruling planets; no judgment is asserted from it. Rules about caste, prenatal sex or death timing are withheld and counted.

Required: place

{
  "place": {
    "latitude": 28.6139,
    "longitude": 77.209,
    "timezone": "Asia/Kolkata",
    "label": "New Delhi"
  },
  "askedAt": "2026-10-14T10:30:00+05:30",
  "question": "Will the supply contract with Northwind be signed?",
  "deal": {
    "label": "Northwind supply contract",
    "kind": "contract",
    "signingDate": "2026-11-02"
  },
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  },
  "horaryNumber": 108
}

POST/v1/interpret

5 credits

Reading of one life area.

Use it when someone asks what their chart says about one area of life (career, marriage, finance, health, property, children, education, travel, legal and others) and a reproducible verdict with its reasons and sources is wanted. Prefer it to get_forecast when no written narrative is needed.

Deterministic reading of one life area: the verdict, the factors for and against it, timing windows, a cross-check of the verdict, and the classical texts it is grounded in. Every layer is declared as present, computed_empty, not_covered or failed, so nothing is silently missing. No language model is called: the same chart always gets the same reading.

Required: birthData, domain

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  },
  "domain": "career"
}

POST/v1/life-reading

10 credits

Whole-life reading.

Use it when someone wants their life as a whole: which life areas (marriage, children, career, business, money, property, family, travel, education, spirituality, health) are in focus when, across past and future, and where life stands now.

The life's chapters (each mahādaśā in plain words, with dates and ages) and eleven life areas, each with the planets that govern it on this chart, every governing period past and future with why that planet governs it — each marked `primary` (the area is in focus) or `also` (the period only touches it) — and what is in focus now and next. Past periods are included, so the reading can be tested against a life already lived; send `recorded` events to place them on the timeline. Health is read only as periods to give extra care, never as illness or lifespan. Deterministic: no language model is called. The birth time is required. The full reading is large; pass `areas` to return only the life areas you need.

Required: birthData

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  },
  "areas": [
    "career",
    "relationship"
  ],
  "recorded": [
    {
      "type": "job_start",
      "date": "2012-07-01",
      "certainty": "exact"
    },
    {
      "type": "marriage",
      "date": "2018-11-25",
      "certainty": "exact"
    }
  ]
}

POST/v1/domain-timeline

3 credits

Life-area timeline.

Use it when someone asks about one area of life — when marriage, children, career, money, property or another area is in focus, or what a given stretch of years holds for it.

One life area across the whole life: the planets that govern it on this chart, every period that bears on it (past and future, with dates, ages and why that planet governs it), each marked `primary` when the area is in focus or `also` when the period only touches it, and what is in focus now and next, in plain words. Pass `window` to get only the periods that overlap a date range. It is the same reading as the whole-life reading, cut to one area, so the two never disagree. Health is read only as periods to give extra care, never as illness or lifespan. Deterministic: no language model is called. The birth time is required.

Required: birthData, area

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  },
  "area": "relationship",
  "window": {
    "from": "2026-01-01",
    "to": "2031-12-31"
  }
}

POST/v1/relationship

8 credits

Relationship reading (non-marital).

Use it when someone asks how two people get on in a bond other than marriage — business partners, siblings, a parent and child, or friends.

Reads the bond the way the classical method reads it: the houses that govern this kind of bond and their lords in each chart, the natural significators, whose planets fall in whose governing houses, and whether that reach runs both ways, plus the running periods in each chart that engage the bond. A bond meter (strong tie, workable or strained) is computed by a stated convention and returned with every point it is built from; it is not a classical score, since the texts give no arithmetic for a business or sibling match. Deterministic: no language model is called. Both birth times are required. For marriage, use the compatibility tool.

Required: type, a, b

{
  "type": "business",
  "a": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209,
    "name": "A"
  },
  "b": {
    "date": "1991-11-03",
    "time": "06:10",
    "timezone": "Asia/Kolkata",
    "latitude": 19.076,
    "longitude": 72.8777,
    "name": "B"
  }
}

POST/v1/venture-timing

10 credits

Venture timing: when to commit, which business.

Use it when someone asks when to start, launch, sign, borrow or expand a business, or which line of business their chart supports.

A calendar of the coming months in four labels — commit (sign, open, launch), build (keep building; commit only what can be undone), guarded (low fixed cost; no lease, no borrowing) and hold (no new fixed commitments) — each window with the daśā period running and the slow transits of Saturn and Jupiter over it, and the reasons. Describe the businesses being weighed in `ventures` and each is ranked on how strongly the chart supports it and whether the coming periods carry it, with the grounds, its best coming period, and a caution when it needs premises during a hold; name none and the full catalogue of business types is ranked. A ranking of chart support, never a probability of success. Deterministic: no language model is called. The birth time is required.

Required: birthData

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  },
  "ventures": [
    "software and data platform for businesses",
    "a restaurant in a leased storefront",
    "OneDot"
  ],
  "months": 36
}

POST/v1/gem-assessment

5 credits

Gemstone assessment.

Use it when someone asks whether they should wear a particular gemstone (blue sapphire, emerald, pukhraj, a crystal), or whether a stone they wear suits their chart.

Answers the prescription, not the future: which planet the stone strengthens, what that planet owns from this ascendant, whether a classical rule (a dusthāna or kendrādhipati lordship, a māraka) argues against strengthening it, and whether the reason is permanent or lasts only as long as the running period. Returns a verdict — well_founded, period_bound, no_ground, contraindicated or unrecognised — with every ground for and against, the planet's capacity at its degree, when the chart puts the planet in scope, the stones the sources hold apart from it (checked against `alsoWearing`), and wearing detail (finger, metal, day, weight, with the book it comes from) only when the chart gives a reason to wear it. When the source states a caution about the stone, the response says so and names the book. A word that covers several stones ("sapphire") is answered with the candidates. Nothing here predicts what a stone does. Deterministic: no language model is called. The birth time is required.

Required: birthData, gem

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  },
  "gem": "blue sapphire",
  "alsoWearing": [
    "ruby"
  ]
}

POST/v1/compatibility

12 credits

Marriage compatibility: the full reading.

Use it when someone asks whether two people are a good match for marriage and wants the full reading, not only a score. For the fast 36-point score with Manglik alone, use get_guna_milan.

Both charts read together for marriage. The 36-point Aṣṭakūṭa (guna milan) is one input: the verdict names the governing factor and says when it outweighs the score. Also returned: each chart's marital promise, sustainability and happiness, progeny, Manglik reckoned from the lagna, the Moon and Venus with mutual cancellation, a joint marriage-timing window, synastry, and caveats where an uncertain birth time would change the reading. Deterministic: no language model is called. Each partner is a BirthData object plus optional `name` and `gender`.

Required: a, b

{
  "a": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209,
    "name": "A"
  },
  "b": {
    "date": "1991-11-03",
    "time": "06:10",
    "timezone": "Asia/Kolkata",
    "latitude": 19.076,
    "longitude": 72.8777,
    "name": "B"
  }
}

POST/v1/muhurta

10 credits

Auspicious windows (muhūrta) in a date range.

Use it when someone asks for an auspicious date or time (muhūrta) to do something, such as a wedding, launch, move or purchase, within a date range at a given place.

Scans each day in the range and ranks windows for the subject. The pañcāṅga is computed for `eventPlace`, never defaulted to the birthplace.

Required: subject, eventPlace, rangeStart, rangeEnd

{
  "subject": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  },
  "eventPlace": {
    "latitude": 19.076,
    "longitude": 72.8777,
    "timezone": "Asia/Kolkata",
    "label": "Mumbai"
  },
  "freeText": "signing a lease",
  "rangeStart": "2026-11-01",
  "rangeEnd": "2026-11-15"
}

Narrated

Readings voiced by a language model, grounded in the deterministic verdict. Slower (tens of seconds).

POST/v1/forecast

8 credits

Written answer about what lies ahead.

Use it when someone asks an open question about what lies ahead in one area of life and wants a written answer. It takes tens of seconds; for a fast, structured verdict use interpret_domain.

The interpret verdict for `domain`, voiced as a narrative answer to `question` by a language model grounded in the classical statements for the domain. Expect tens of seconds; set a client timeout of at least 90 s.

Required: birthData, domain, question

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  },
  "domain": "career",
  "question": "How will the next year unfold for my work?"
}

POST/v1/timing/resolve

7 credits

Is this a good time? (decision timing).

Use it when someone asks whether now, or a particular date or range, is a good time for a decision such as changing jobs, marrying or investing. It takes tens of seconds.

The interpret verdict for `domain`, voiced by a language model as an answer to a decision `question`, read at `targetDate` (or the start of `dateRange`, or today when neither is sent): the verdict, the running daśā and eventTiming are taken at that day. A malformed or pre-birth date is refused with 400 (`invalid_target_date`, `invalid_date_range`). Expect tens of seconds; set a client timeout of at least 90 s.

Required: birthData, domain, question

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  },
  "domain": "career",
  "question": "Should I accept the offer?",
  "targetDate": "2026-11-15"
}

Ephemeris

Raw astronomical positions from AstroNest’s own engine, built on NASA JPL’s DE440 ephemeris: no Swiss Ephemeris licence or other astrology API needed. Deterministic, about a millisecond per position, no language model. One key scope (`ephemeris`) covers all five operations.

POST/v1/ephemeris/positions

0.1 credit

Positions at a moment.

Use it when you need where the Sun, Moon and planets are at a moment (sidereal or tropical), not a reading.

Sun, Moon, planets and lunar nodes at one moment: longitude, latitude, distance, speed and retrograde flag, with sign, and nakṣatra and its quarter when sidereal. `equatorial: true` adds apparent right ascension and declination.

Required: datetime

{
  "datetime": "2026-10-06T06:00:00Z",
  "bodies": [
    "Sun",
    "Moon",
    "Mars",
    "Jupiter",
    "Saturn",
    "TrueNode"
  ],
  "zodiac": "sidereal",
  "ayanamsa": "lahiri"
}

POST/v1/ephemeris/angles

0.1 credit

Ascendant, MC and house cusps.

Use it when you need the ascendant, midheaven or house cusps for a moment and place.

Ascendant, midheaven and twelve cusps for a moment and place. Placidus is undefined beyond the polar circles at some moments; the call then returns 422 houses_undefined_at_latitude.

Required: datetime, latitude, longitude

{
  "datetime": "1990-05-12T14:35:00+05:30",
  "latitude": 28.6139,
  "longitude": 77.209,
  "houseSystem": "placidus"
}

POST/v1/ephemeris/ayanamsa

0.1 credit

Ayanamsa values.

Use it when you need an ayanamsa value at a moment.

The ayanāṁśa (the sidereal offset) at a moment, for each supported ayanāṁśa (mean, without nutation).

Required: datetime

{
  "datetime": "2026-10-06T00:00:00Z"
}

POST/v1/ephemeris/sunrise

0.1 credit

Sunrise and sunset.

Use it when you need sunrise and sunset for a date and place, or where the Vedic day begins.

Sunrise, sunset and the next sunrise for a local date and place: upper limb at the sea-level horizon with 36.6′ refraction. The Vedic day runs from sunrise to the next sunrise.

Required: date, timezone, latitude, longitude

{
  "date": "2026-10-06",
  "timezone": "Asia/Kolkata",
  "latitude": 28.6139,
  "longitude": 77.209
}

POST/v1/ephemeris/series

1 credit

Positions over a range.

Use it when you need planetary positions across a range of dates, for a transit table or to find when a planet changes sign or stations.

Positions from start to end (inclusive) every stepMinutes, for transit tables and station finding. At most 1,000 points (too_many_points beyond). A 365-point daily table costs 4 credits.

Required: start, end, stepMinutes

{
  "start": "2026-10-01T00:00:00Z",
  "end": "2026-10-10T00:00:00Z",
  "stepMinutes": 1440,
  "bodies": [
    "Mercury",
    "Venus"
  ]
}

Birth data

One object, validated before anything runs

Every reading takes a birthData object: date (YYYY-MM-DD), time (HH:MM or HH:MM:SS, local; omit if unknown), timezone (IANA, e.g. Asia/Kolkata), latitude and longitude. It is validated before anything is computed, so a malformed request is never charged. The API is stateless: birth data is used for the call and not stored.

Ephemeris inputs

A moment, not birth data

The Ephemeris operations take a moment instead of birth data: ISO 8601 with Z or an explicit offset (2026-10-06T06:00:00Z, 1990-05-12T14:35:00+05:30). A time without a zone is refused rather than guessed. Coverage is 1800-01-02 to 2149-12-31 UTC, from NASA JPL DE440. The zodiac defaults to sidereal with the Lahiri ayanamsa; pass zodiac: "tropical" or another ayanamsa to change it. One key scope, ephemeris, covers all five operations; keys created before it existed gain it by editing the key's scopes in the portal.

Domains

What a reading can be about

For interpret, forecast and timing/resolve:

careerbusinessfinancechildrenpropertyeducationtravelspiritualitylineagereputationpartnershipslegalfamilymarriagehealth

Coverage

Reading the coverage object

Every reading response carries coverage, and every layer in it is always named. You never have to infer that a layer was skipped from a missing key, which is what the object exists to prevent. A layer being empty or unavailable does not mean the call failed; the verdict and its timing stand on their own.

StateMeaning
presentThe layer ran and returned something. The matching top-level key is populated.
computed_emptyThe layer ran and found nothing for this chart. A RESULT, not an error: a domain with no classical title behind it is a real and reportable state.
not_coveredThis endpoint does not carry that layer for this request. Nothing went wrong; ask a different endpoint.
failedThe layer errored or timed out. Every layer is computed fail-open, so the rest of the response is unaffected, but do not read its absence as agreement or as emptiness.

The one to handle deliberately is methodAgreement. When present it tells you whether the engine’s own routes reached the opposite reading from the verdict in the same response. Treating a failed there as “the methods agreed” is the single most costly misreading of this response.

Responses also echo readingWindow: the referenceDate and timezone actually used. If you sent neither, this is how you find out what the server chose, so a response can be reproduced exactly.

Errors

Every failure is named, and none is charged

Errors return { "error": "<code>", "message": "…", "requestId": "…", "statusCode": n }. Quote the requestId in any support request. No error is charged.

StatusMeaning
400Invalid request. Codes: invalid_json, missing_birthdata, invalid_birthdata, invalid_timezone, invalid_coordinates, missing_required_field, invalid_domain, invalid_reference_date, invalid_range, no_days_evaluable. Not charged.
401missing_api_key, invalid_api_key, revoked_key or expired_key. Not charged.
402credits_exhausted: the one-time free credits are used or have expired (60 days from the first live key) and the paid balance is too low for this call; buy a credit pack in the developer portal. key_credit_limit_reached: this key has reached the monthly credit limit set on it in the portal (resets on the 1st, UTC). Never charged.
403insufficient_scope: the key is not scoped for this endpoint. Not charged.
422chart_integrity_failed, dasha_failed or guidance_failed: the birth data could not produce a valid result. Not charged.
429rate_limited (over 120 requests a minute for this account) or concurrency_limit (too many requests at once). Retry-After says when to retry. Not charged.
500Our error. Not charged.
502narration_failed: the language model did not return a reading. Not charged.

Readings carry qualitative confidence and plain-language reasons. They never include internal scores, rule identifiers or verbatim passages from the source texts. Where an endpoint cites its classical grounding, it names book titles only.

Rate limits

120 requests a minute per account

Each account may make up to 120 requests a minute (sandbox included) and run 2 at once (5 after any purchase). Over the limit, the API answers 429 rate_limited or 429 concurrency_limit with a Retry-After header; neither is charged. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset when limited.

Beta terms

What you agree to

Version beta-1-2026-10-07. You accept these in the portal before creating a live key or buying credits.

  1. The API is in beta. It is provided as is, without an SLA, and may change; we will try to give notice of breaking changes.
  2. Readings are symbolic interpretation only — not medical, legal, financial or psychological advice. You show the response's disclaimer to your users and do not present a reading as a diagnosis or a guarantee.
  3. You do not use readings to make decisions about people in employment, credit, insurance, housing or matchmaking on the basis of caste or religion, or any decision with legal effect based solely on a reading.
  4. You keep your keys secret and call the API from your server. You are responsible for calls made with your keys.
  5. You may display responses inside your own product. You do not resell raw API access, scrape the API to build a competing dataset or model, or try to reverse-engineer the rules behind the readings.
  6. You are responsible for your end users' personal data and for having a lawful basis to send it. We process birth data only to answer each call and do not store request bodies or responses.
  7. Credits are prepaid and non-refundable except where the law requires; failed calls are never charged. We may suspend keys used in breach of these terms.
  8. Full terms of service and a data processing addendum are being finalised. When they are published you will be asked to accept them before your next live key or purchase.

Drafts of the full documents, under review: the Developer API terms of service and the Developer API privacy policy, which also cover the MCP server and connections from AI assistants. Questions: astronest@onedotlinks.com.

Use responsibly

Symbolic interpretation only — not medical, legal, financial or psychological advice. Show the disclaimer field to your users. The API is in beta: there is no SLA yet, and the terms of service are being finalised.