How to Build a Horoscope App with the GitStrology API

A complete, step-by-step tutorial for building a production horoscope application using the GitStrology API, the official TypeScript SDK, and Next.js. From authentication to deployment — with real code you can copy and run.

Why GitStrology for Your Horoscope App?

Building a horoscope app used to mean scraping outdated astrology websites or licensing expensive, opaque APIs with per-call pricing that punished you for growing. GitStrology flips that model. It is a developer-first astrology API with a transparent credit system, a fully typed TypeScript SDK, a command-line tool, and even a GitHub Actions integration for automated daily readings.

The free tier gives you 100 API credits per month with no credit card required — enough to prototype, test, and even serve a small user base. Each horoscope request costs just 1 credit, so those 100 free credits translate to 100 daily horoscope calls. When you are ready to scale, the Pro plan offers 10,000 credits for $19/month.

What We Will Build

In this tutorial, we will build a Next.js application that lets users select their zodiac sign and view a daily horoscope complete with mood, energy ratings, lucky numbers, and personalized advice. We will also add a moon-phase widget and a natal chart summary. The entire app communicates with the GitStrology API through the official SDK.

Prerequisites

• Node.js 18 or later
• A free GitStrology account and API key
• Basic familiarity with React and TypeScript

Step 1: Get Your API Key

Before writing any code, you need an API key. Sign up at GitStrology and navigate to the dashboard to generate a key. Keys follow the format gs_live_ followed by a hex string. Store your key in an environment variable immediately — the full key is only shown once at creation time.

New accounts start on the free tier with 100 credits per month. That is enough to build and test the entire app described in this tutorial. See the quickstart guide for details on account setup and making your first request.

Step 2: Install the SDK

The GitStrology SDK is a lightweight TypeScript package that wraps every API endpoint with full type safety. Install it alongside Next.js:

npm install gitstrology next react react-dom

Alternatively, if you are starting from scratch, scaffold a new Next.js project first and then add the SDK:

npx create-next-app@latest my-horoscope-app
cd my-horoscope-app
npm install gitstrology

Step 3: Configure Environment Variables

Never hardcode your API key. Create a .env.local file in the root of your project:

# .env.local
GITSTROLOGY_API_KEY=gs_live_your_key_here

The SDK reads from GITSTROLOGY_API_KEY automatically, so you only need to pass it explicitly if you are using a custom variable name. See the authentication docs for security best practices including key rotation and environment separation.

Step 4: Create the API Client

Create a single, reusable client instance. In a Next.js App Router project, place this in a server-side utility file so it never leaks to the browser:

// lib/gitstrology.ts
import { Gitstrology } from "gitstrology";

if (!process.env.GITSTROLOGY_API_KEY) {
  throw new Error("GITSTROLOGY_API_KEY is not set");
}

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

This singleton pattern ensures you initialize the client once and reuse it across all server components and API routes. The SDK automatically handles the X-API-Key header, JSON serialization, and response parsing.

Step 5: Fetch a Daily Horoscope

The horoscope endpoint returns a rich daily reading for any zodiac sign. It costs just 1 credit per call. Let's create a server component that fetches the horoscope and renders it:

// app/horoscope/[sign]/page.tsx
import { gs } from "@/lib/gitstrology";

const SIGNS = [
  "aries", "taurus", "gemini", "cancer", "leo", "virgo",
  "libra", "scorpio", "sagittarius", "capricorn", "aquarius", "pisces",
];

export async function generateStaticParams() {
  return SIGNS.map((sign) => ({ sign }));
}

export default async function HoroscopePage({
  params,
}: {
  params: Promise<{ sign: string }>;
}) {
  const { sign } = await params;

  const response = await gs.dailyHoroscope(sign);
  const h = response.data;

  return (
    <main>
      <h1>{sign.toUpperCase()} Daily Horoscope</h1>
      <p>Mood: {h.mood}</p>
      <p>{h.summary}</p>
      <p>Advice: {h.advice}</p>
      <p>Lucky Number: {h.luckyNumber} | Lucky Color: {h.luckyColor}</p>
      <ul>
        <li>Energy: {h.energy}/5</li>
        <li>Luck: {h.luck}/5</li>
        <li>Love: {h.love}/5</li>
        <li>Career: {h.career}/5</li>
      </ul>
    </main>
  );
}

The response object includes a credits envelope so you can track usage in real time. Every response follows the same structure:

{
  "data": {
    "date": "2026-08-03",
    "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 }
}

Step 6: Add a Moon Phase Widget

Moon phases are a popular feature in astrology apps and they cost only 1 credit. The gs.moonPhase() method returns the current lunar phase, illumination percentage, age, and the zodiac sign the moon is transiting:

// app/components/MoonPhase.tsx
import { gs } from "@/lib/gitstrology";

export default async function MoonPhase() {
  const response = await gs.moonPhase();
  const moon = response.data;

  return (
    <div className="moon-widget">
      <span className="moon-emoji">{moon.emoji}</span>
      <h3>{moon.name}</h3>
      <p>Illumination: {Math.round(moon.illumination * 100)}%</p>
      <p>Moon in {moon.zodiacSign}</p>
    </div>
  );
}

The moon-phase endpoint accepts an optional date query parameter in YYYY-MM-DD format, so you can display phases for any day past or future.

Step 7: Add a Natal Chart Feature

For a more advanced feature, let users generate their full natal chart by entering birth date, time, and location. This endpoint costs 5 credits but returns a comprehensive chart with planetary positions, houses, and aspects. See the natal chart docs for the full response schema.

// app/api/natal-chart/route.ts
import { NextRequest, NextResponse } from "next/server";
import { gs } from "@/lib/gitstrology";

export async function POST(request: NextRequest) {
  const body = await request.json();

  // Validate required fields
  if (!body.date || !body.latitude || !body.longitude) {
    return NextResponse.json(
      { error: "date, latitude, and longitude are required" },
      { status: 400 }
    );
  }

  try {
    const response = await gs.natalChart({
      date: body.date,
      time: body.time,
      latitude: body.latitude,
      longitude: body.longitude,
      timezone: body.timezone,
    });

    return NextResponse.json(response);
  } catch (error) {
    return NextResponse.json(
      { error: "Failed to generate natal chart" },
      { status: 500 }
    );
  }
}

The natal chart response includes sunSign, moonSign, risingSign, a full planets array with longitude, sign, house, and retrograde status for each celestial body, plus an aspects array detailing the angular relationships between planets.

Step 8: Implement Client-Side Sign Selection

For the interactive sign selector, use a client component that navigates to the corresponding horoscope page. This keeps the data fetching on the server while giving users a smooth picker experience:

// app/components/SignPicker.tsx
"use client";

import { useRouter } from "next/navigation";

const SIGNS = [
  { name: "aries", symbol: "♈" },
  { name: "taurus", symbol: "♉" },
  { name: "gemini", symbol: "♊" },
  { name: "cancer", symbol: "♋" },
  { name: "leo", symbol: "♌" },
  { name: "virgo", symbol: "♍" },
  { name: "libra", symbol: "♎" },
  { name: "scorpio", symbol: "♏" },
  { name: "sagittarius", symbol: "♐" },
  { name: "capricorn", symbol: "♑" },
  { name: "aquarius", symbol: "♒" },
  { name: "pisces", symbol: "♓" },
];

export default function SignPicker() {
  const router = useRouter();

  return (
    <div className="sign-grid">
      {SIGNS.map((sign) => (
        <button
          key={sign.name}
          onClick={() => router.push(`/horoscope/${sign.name}`)}
          className="sign-card"
        >
          <span className="symbol">{sign.symbol}</span>
          <span className="name">{sign.name}</span>
        </button>
      ))}
    </div>
  );
}

Step 9: Handle Rate Limits and Credits

GitStrology uses a credit system combined with per-minute rate limits. Every response includes a credits object showing how many credits the call consumed and how many remain in your monthly allocation. On the free plan, you get 10 requests per minute. On the Pro plan, that increases to 60 per minute.

Always wrap your API calls in error handling to gracefully deal with rate limits (HTTP 429) and credit exhaustion:

// lib/safe-fetch.ts
import { Gitstrology } from "gitstrology";

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

export async function safeHoroscope(sign: string) {
  try {
    const response = await gs.dailyHoroscope(sign);
    return { data: response.data, credits: response.credits };
  } catch (error: any) {
    if (error.status === 429) {
      return {
        error: "Rate limit reached. Please wait a moment and try again.",
      };
    }
    if (error.status === 402) {
      return {
        error: "Out of credits. Upgrade your plan for more requests.",
      };
    }
    throw error;
  }
}

For a detailed breakdown of credit costs per endpoint and plan limits, see the rate limits and credits documentation.

Step 10: Test with the CLI

Before deploying, verify your API key and test responses using the GitStrology CLI. No installation required — use npx:

# Test a daily horoscope
npx gitstrology horoscope --sign aries

# Generate a natal chart
npx gitstrology chart --birth 1990-03-15 --time 14:30 --lat 44.8 --lon 20.4

The CLI is perfect for quick debugging and for scripting one-off requests from your terminal.

Deploying Your Horoscope App

When you are ready to ship, deploy to Vercel (or any platform that supports Next.js). Add your GITSTROLOGY_API_KEY as an environment variable in your hosting provider's dashboard. Since all API calls in this tutorial run server-side via the SDK, your key never reaches the browser.

For a cost-effective launch, start on the free tier. With 100 credits per month and horoscopes costing 1 credit each, you can serve approximately 100 daily horoscope requests. When traffic grows, upgrade to the Pro plan for 10,000 monthly credits and higher rate limits.

Automate Daily Readings with GitHub Actions

GitStrology ships with an official GitHub Action that posts daily horoscopes on a schedule — perfect for automated content pipelines or team Slack integrations:

# .github/workflows/daily-horoscope.yml
name: Daily Horoscope
on:
  schedule:
    - cron: "0 8 * * *"
  workflow_dispatch:

jobs:
  horoscope:
    runs-on: ubuntu-latest
    steps:
      - uses: gitstrology/daily-horoscope-action@v1
        with:
          api-key: ${{ secrets.GITSTROLOGY_API_KEY }}
          sign: aries

This runs every morning at 8 AM UTC. Combine it with the optional Slack webhook input to pipe readings directly into a channel.

Key Takeaways

• GitStrology offers a developer-first astrology API with a typed TypeScript SDK, CLI, MCP server, and GitHub Actions integration.
• The free tier includes 100 credits per month — horoscopes cost just 1 credit each, making it easy to prototype and launch without upfront cost.
• The SDK handles authentication, serialization, and response parsing automatically. Initialize once, reuse everywhere.
• Every response includes a credits envelope so you can monitor usage and implement graceful degradation when limits are hit.
• All sensitive API calls should run server-side. Never expose your API key in client-side code.
• For production apps, implement error handling for rate limits (429) and credit exhaustion (402) to deliver a smooth user experience.

Ready to start building? Grab your API key from the dashboard, follow the quickstart guide, and ship your horoscope app today.