API for Astrology

Quickstart: make your first call

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 ak_test_ or ak_live_.

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

Terminal
export ASTROLOGY_API_KEY="ak_test_..."

2. Make your first call

Send a birth date, the local clock time, the place as latitude and longitude, and the time zone name. This example is John Doe, born on August 15, 1990 at 10:30 AM in New York.

curl
# John Doe, born Aug 15, 1990, 10:30 AM, New York
curl -X POST "https://qastage01.apiforastrology.com/api/gateway/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"}'
JavaScript (fetch)
// John Doe, born Aug 15, 1990, 10:30 AM, New York
const res = await fetch("https://qastage01.apiforastrology.com/api/gateway/v1/planets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ASTROLOGY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "year": 1990,
    "month": 8,
    "day": 15,
    "hour": 10,
    "minute": 30,
    "second": 0,
    "latitude": 40.7128,
    "longitude": -74.006,
    "timezone": "America/New_York"
  }),
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${res.status} ${error.code}: ${error.message}`);
}
const chart = await res.json();
console.log(chart.ascendant.sign);
Python (requests)
import os
import requests

# John Doe, born Aug 15, 1990, 10:30 AM, New York
res = requests.post(
    "https://qastage01.apiforastrology.com/api/gateway/v1/planets",
    headers={"Authorization": f"Bearer {os.environ['ASTROLOGY_API_KEY']}"},
    json={
        "year": 1990,
        "month": 8,
        "day": 15,
        "hour": 10,
        "minute": 30,
        "second": 0,
        "latitude": 40.7128,
        "longitude": -74.006,
        "timezone": "America/New_York"
    },
    timeout=30,
)
res.raise_for_status()
chart = res.json()
print(chart["ascendant"]["sign"])
PHP (curl)
<?php
// John Doe, born Aug 15, 1990, 10:30 AM, New York
$ch = curl_init('https://qastage01.apiforastrology.com/api/gateway/v1/planets');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('ASTROLOGY_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'year' => 1990,
    'month' => 8,
    'day' => 15,
    'hour' => 10,
    'minute' => 30,
    'second' => 0,
    'latitude' => 40.7128,
    'longitude' => -74.006,
    'timezone' => 'America/New_York',
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$chart = json_decode(curl_exec($ch), true);
echo $chart['ascendant']['sign'];

Call the API from your server, not from a web page or mobile app, so the key stays private.

3. Read the response

A successful call returns 200 and the chart as JSON: the rising sign (ascendant) and each planet with its sign, degree, house and nakshatra. Here is a short part of John Doe's chart:

POST /v1/planets (shortened)
{
  "ascendant": {
    "sign": "Virgo"
  },
  "positions": [
    {
      "name": "Sun",
      "sign": "Cancer"
    },
    {
      "name": "Moon",
      "sign": "Taurus"
    },
    {
      "name": "Mars",
      "sign": "Aries"
    }
  ]
}

If something is wrong, you get a JSON error instead, such as {"error": {"code": "invalid_input", "message": "Field required", "field": "latitude"}}. See errors.

Next steps