Astrology API quickstart: make your first call

You need:

• an API key (step 1);
• a birth date, the local clock time, and the place as latitude, longitude and a time zone name (if you have only a city name, look up those three first);
• a server that can send HTTPS requests: curl, Node.js 18 or later, Python with the requests package, or PHP with curl.

1. Get a key

Create an account, then open the API keys page and create a key. The full key is shown only once, so copy it somewhere safe. Keys start with afa_test_ or afa_live_.

Test keys work as soon as you create them and are never billed. They allow 1,000 calls a month. They return calculations for any chart, but written readings only for the sample charts. See test keys.

No key yet? The free kundli tool runs this same call, POST /v1/planets, with no key. The API reference shows a real recorded answer for every endpoint.

Save your key as an environment variable on your server. The examples below read it from ASTROLOGY_API_KEY.

# macOS and Linux
export ASTROLOGY_API_KEY="afa_test_..."

# Windows PowerShell
$env:ASTROLOGY_API_KEY="afa_test_..."

2. Make your first call

Send the birth details as JSON. You must send year, month, day, latitude, longitude and timezone. The time zone is a name from the IANA time zone database, such as America/New_York. Also send hour and minute on the local clock. They are optional, but they default to 0, which is midnight.

This example is John Doe, born on August 15, 1990 at 10:30 AM in New York.

# John Doe, born Aug 15, 1990, 10:30 AM, New York
curl -X POST "https://apiforastrology.com/api/astrology/v1/planets" \
  -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"}'

Call the API from your server, not from a web page or mobile app, so the key stays private. The JavaScript example uses await at the top level, so save it as a .mjs file.

Prefer an API client? The Postman collection has every endpoint with John Doe’s details filled in. Import it into Postman, Insomnia, Bruno or Hoppscotch. Then set the apiKey variable to your key.

3. Read the response

A successful call returns 200 and the chart as JSON. It starts with the ascendant (the rising sign, the sign coming up in the east at the moment of birth). Then it lists each planet with its sign, degree, house and nakshatra (one of 27 star groups). A house is one of the 12 parts of the chart. Here is a short part of John Doe’s chart, with the ascendant and the first two planets:

{
  "ascendant": {
    "name": "Ascendant",
    "sign": "Virgo",
    "degree_in_sign": 19.934155,
    "house": 1,
    "nakshatra": "Hast"
  },
  "positions": [
    {
      "name": "Sun",
      "sign": "Cancer",
      "degree_in_sign": 28.7753409,
      "house": 11,
      "nakshatra": "Ashlesha"
    },
    {
      "name": "Moon",
      "sign": "Taurus",
      "degree_in_sign": 24.5750352,
      "house": 9,
      "nakshatra": "Mrigashira"
    }
  ]
}

degree_in_sign is the degree inside the sign, from 0 to 30. The full answer has more fields for each planet, such as longitude, retrograde and dignity. The retrograde field says whether the planet seems to move backward. The dignity field says how well the planet is placed in its sign. The answer lists every planet. Its meta block says how the chart was worked out. It names the ayanamsa and the time zone offset used.

Note the Sun sign. In this answer John Doe’s Sun is in Cancer, but a Western horoscope puts it in Leo. Both are right. The API uses the Vedic (sidereal) zodiac, and the two zodiacs are about 24 degrees apart. See Vedic vs Western astrology for what to tell your users.

Common first-call errors

Every error comes back as JSON with a code, a message and, for a bad field, a field. A first call can get these:

• 401 unauthorized with the message Provide a key as "Authorization: Bearer <key>" or "X-API-Key: <key>". The key variable is empty. Run the export line again in the same terminal window.
• 401 unauthorized with The API key is invalid. The key is mistyped or cut short. Copy it again.
• 422 invalid_input with Field required and "field": "latitude". A required field is missing. The field property names it.
• 422 invalid_input with "field": "timezone". The time zone is not a zone name, for example New York instead of America/New_York.
• 422 invalid_input for a birth time on a night the clocks changed. The time happened twice or never. See times and time zones.

Two mistakes give no error at all, just a wrong chart:

• Leaving out hour and minute. The API reads the time as midnight. For John Doe, the rising sign then comes back as Taurus instead of Virgo.
• Sending a fixed offset that ignores daylight saving time. New York was on UTC-4 on August 15, 1990, not UTC-5. With "timezone": -5, John Doe’s rising sign moves from Virgo to Libra. Send the zone name, and the API finds the right offset for that date.

More cases like these, with real charts, are in time zone errors in birth charts. Every code is in the errors guide.

Next steps

• Browse every endpoint in the API reference and send test requests with your key.
• Read how authentication and rate limits work.
• Check the conventions for whole-sign houses, the ayanamsa (the gap between the Vedic and Western zodiacs) and time zones. To pick an ayanamsa, see Lahiri, KP and Raman compared.
• Building a chatbot? The AI assistants guide shows which endpoints to offer as tools and which fields to quote.
• See what one chart can become: the sample report for John Doe.
• Follow new endpoints and fixes in the changelog.