Quickstart

Make your first astrology API request in under a minute.

1. Get an API key

Sign up and create a key in the dashboard. Free tier includes 100 credits/month — no credit card required.

2. Make a request

curl -X POST https://api.gitstrology.dev/v1/horoscope \
  -H "X-API-Key: gs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"sign":"aries"}'

You'll get a JSON response with the horoscope and your credit balance:

{
  "data": {
    "date": "2026-08-02",
    "sign": "aries",
    "mood": "ambitious",
    "energy": 4,
    "luck": 3,
    "love": 5,
    "career": 4,
    "summary": "Aries energy is running high today...",
    "advice": "Channel your fire into one decisive action today.",
    "luckyNumber": 42,
    "luckyColor": "gold"
  },
  "credits": { "used": 1, "remaining": 99 }
}

3. Use the SDK

TypeScript

import { Gitstrology } from "gitstrology";

const gs = new Gitstrology({ apiKey: process.env.GITSTROLOGY_API_KEY });

const chart = await gs.natalChart({
  date: "1990-03-15",
  time: "14:30",
  latitude: 44.8,
  longitude: 20.4,
});

console.log(chart.sunSign); // "pisces"

Python

from gitstrology import Gitstrology

gs = Gitstrology(api_key=os.environ["GITSTROLOGY_API_KEY"])

chart = gs.natal_chart(
    date="1990-03-15",
    time="14:30",
    latitude=44.8,
    longitude=20.4,
)

print(chart["sunSign"])  # "pisces"

4. Try the CLI

npx gitstrology chart --birth 1990-03-15 --time 14:30 --lat 44.8 --lon 20.4
npx gitstrology horoscope --sign aries

Next steps

Read about authentication, the natal chart endpoint, or rate limits and credits.