Guides

Free astrology API: free credits, your API key and a first call

You can start with our astrology API for free. Sign up and we give you 150 free credits. You don't need a credit card. You get a real access token and real data from our live API.

This guide shows what the free credits include, how to get your key, and how to make your first call in curl, Node and Python. It also explains what happens when the credits run out.

What you get for free

A free account starts with a 14-day trial. When you activate it, we add your 150 free credits to your wallet. A wallet is the balance that each API call draws from.

• 150 free credits, added to your wallet when the trial starts.
• No credit card at signup.
• Up to 100 API calls a day during the trial.
• One access token that works across our suites: Vedic, Western, horoscope and more. You don't need a separate key for each one.

When the credits run out, you have two choices. You can top up your wallet and pay per call. The minimum top-up is $5 (USD) or ₹500 (INR). Or you can pick a monthly plan on our pricing page. The pay-as-you-go guide explains how the wallet works.

Get your API key in 3 steps

People often search for an "astrology API key". With us, the key you use is called an access token. You send it in a header with every call.

1. Sign up. Go to the signup page and enter your name, email and a password. There is no card step.
2. Verify your email. We send you an email with a link. Open the link to activate your account, then log in.
3. Activate the trial and copy your token. On your first login, we ask for your domain or app name and your role. Then we show your access token. Copy it and keep it secret. You can always find it again on the Credentials page in your dashboard.

To create more tokens, add balance to your wallet first. If you buy a subscription plan, the Credentials page also lists a user ID and API key for that plan. That pair uses HTTP Basic auth instead of a header. Our tokens vs. API keys guide compares the two.

Your first call in under 5 minutes

We'll call planets. It takes a birth date, time and place. It returns where each planet was at that moment, in Vedic (sidereal) astrology. Every JSON endpoint is a POST to https://json.astrologyapi.com/v1.

The request body has eight fields:

• day, month, year: the birth date.
• hour, min: the local birth time, in 24-hour format.
• lat, lon: the birth place in decimal degrees.
• tzone: the UTC offset as a decimal, for example 5.5 for India. See Timezones, DST, and birth data.

curl

Paste your token into the first line, then run both commands.

export ASTROLOGY_ACCESS_TOKEN="paste-your-token-here"

curl -s -X POST https://json.astrologyapi.com/v1/planets \
  -H "x-astrologyapi-key: $ASTROLOGY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -w "\nHTTP status: %{http_code}\n" \
  -d '{"day":10,"month":5,"year":1990,"hour":19,"min":55,"lat":19.2056,"lon":25.2056,"tzone":5.5}'

Node.js

Set ASTROLOGY_ACCESS_TOKEN in your environment. Save the file as first-call.mjs and run it.

// first-call.mjs - Node 18+ (built-in fetch). Run it with: node first-call.mjs
// Run this on your server. Never put your token in browser code.
const TOKEN = process.env.ASTROLOGY_ACCESS_TOKEN
if (!TOKEN) throw new Error('Set ASTROLOGY_ACCESS_TOKEN first')

const birth = {
  day: 10, month: 5, year: 1990,
  hour: 19, min: 55,
  lat: 19.2056, lon: 25.2056,
  tzone: 5.5,
}

const res = await fetch('https://json.astrologyapi.com/v1/planets', {
  method: 'POST',
  headers: {
    'x-astrologyapi-key': TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(birth),
})

if (!res.ok) {
  throw new Error(`planets failed with ${res.status}: ${await res.text()}`)
}

const planets = await res.json()
for (const p of planets) {
  console.log(p.name, p.sign, p.normDegree.toFixed(2))
}

Python

Install requests, set the same environment variable and run python first_call.py.

# first_call.py - Python 3.8+. Install the client with: pip install requests
import os
import sys

import requests

TOKEN = os.environ.get("ASTROLOGY_ACCESS_TOKEN")
if not TOKEN:
    sys.exit("Set ASTROLOGY_ACCESS_TOKEN first")

birth = {
    "day": 10, "month": 5, "year": 1990,
    "hour": 19, "min": 55,
    "lat": 19.2056, "lon": 25.2056,
    "tzone": 5.5,
}

res = requests.post(
    "https://json.astrologyapi.com/v1/planets",
    headers={"x-astrologyapi-key": TOKEN},
    json=birth,  # sends a JSON body with Content-Type: application/json
    timeout=15,
)

if res.status_code != 200:
    sys.exit(f"planets failed with {res.status_code}: {res.text}")

for p in res.json():
    print(p["name"], p["sign"], round(p["normDegree"], 2))

What comes back

We return an array with one object per planet. Here is the sample response, trimmed to the Sun and the Moon:

[
  {
    "id": 0,
    "name": "Sun",
    "fullDegree": 72.18954079246434,
    "normDegree": 12.189540792464342,
    "isRetro": "false",
    "sign": "Gemini",
    "signLord": "Mercury",
    "nakshatra": "Ardra",
    "nakshatraLord": "Rahu",
    "nakshatra_pad": 2,
    "house": 9
  },
  {
    "id": 1,
    "name": "Moon",
    "fullDegree": 11.72351598586304,
    "normDegree": 11.72351598586304,
    "isRetro": "false",
    "sign": "Aries",
    "signLord": "Mars",
    "nakshatra": "Ashwini",
    "nakshatraLord": "Ketu",
    "nakshatra_pad": 4,
    "house": 7
  }
  // ...one object for each other planet, then the Ascendant
]

• fullDegree is the position from 0 to 360 around the zodiac.
• normDegree is the degree inside the sign, from 0 to 30.
• isRetro is a string, "true" or "false". Retro means the planet looks like it moves backward.

For a smaller first response, try astro_details with the same body. It returns one object with the ascendant, Moon sign and nakshatra (lunar mansion). Full field lists are on the planets docs page.

Can I call it without authentication?

No. Every call needs your credentials. We have no open, keyless endpoints. There are two reasons for this.

• Your token is your balance. Each call draws credits from your wallet. Anyone who has your token can spend your credits. So the token must stay on your server.
• We send no CORS headers. CORS is the browser rule that decides which websites may call an API. Without those headers, browsers block direct calls to our API. A call from your server works fine.

The safe pattern is a small server route. Your web or mobile app calls your server. Your server adds the access token and calls us. The token lives in an environment variable and never reaches the browser.

// server.mjs - Node 18+. Install with: npm install express
// Your browser code calls /api/planets on YOUR server.
// Only this server knows the token.
import express from 'express'

const TOKEN = process.env.ASTROLOGY_ACCESS_TOKEN
if (!TOKEN) throw new Error('Set ASTROLOGY_ACCESS_TOKEN first')

const app = express()
app.use(express.json())

app.post('/api/planets', async (req, res) => {
  // Forward only the birth fields. Never trust extra input.
  const { day, month, year, hour, min, lat, lon, tzone } = req.body
  try {
    const upstream = await fetch('https://json.astrologyapi.com/v1/planets', {
      method: 'POST',
      headers: {
        'x-astrologyapi-key': TOKEN,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ day, month, year, hour, min, lat, lon, tzone }),
    })
    if (!upstream.ok) {
      return res.status(502).json({ error: `planets returned ${upstream.status}` })
    }
    return res.json(await upstream.json())
  } catch (err) {
    console.error('planets request failed:', err)
    return res.status(502).json({ error: 'Could not reach the astrology API' })
  }
})

app.listen(3000, () => console.log('Listening on http://localhost:3000'))

Create one token for each app on the Credentials page. If a token leaks, delete it there and create a new one. Your other apps keep working. Read Access tokens vs. User ID and API key and the access token usage guide for the details.

How far the free credits go

Each endpoint has its own credit cost. A planet position call, a daily horoscope and a PDF report don't cost the same. Look up each endpoint in our credits calculator before you plan your tests.

These habits make your free credits last longer:

• Start with one endpoint. Get one call working end to end before you add more.
• Cache responses. A birth chart never changes for the same birth details. Save the response and reuse it. A daily horoscope is the same for everyone with that sign, so fetch it once per sign per day.
• Use the docs samples first. Every endpoint page in our docs has a Try it panel with a sample request and sample response. It doesn't make a live call, so it uses no credits. Study the response shape there, then call the live API.
• Don't retry 4xx errors. A wrong token or a bad date fails the same way every time. Fix the request instead. See Going to production for error handling and caching.

Free vs paid

Here is how the free trial compares with the two paid options.

Frequently asked questions

For AI agents

• Free tier: sign up at /signup for 150 free credits, no card, 14-day trial, up to 100 calls a day.
• Credential: an access token from the dashboard Credentials page. Send it as the x-astrologyapi-key header.
• No keyless access. No CORS headers. Call from a server only, with the token in an environment variable.
• First call: POST https://json.astrologyapi.com/v1/planets with a JSON body of day, month, year, hour, min, lat, lon, tzone. Returns an array of planet objects.
• Credit cost varies by endpoint. Look it up at /credits-calculator. Do not assume a fixed cost per call.
• After the free credits: top up the wallet (minimum $5 (USD) or ₹500 (INR)) or buy a monthly plan at /pricing.