Introduction

Astrology applications are complex to build from scratch. Calculating planetary positions requires precise ephemeris data, complex trigonometry, and timezone handling.

FreeAstroAPI abstracts all of this complexity into a single, high-performance REST endpoint.

In this guide, we'll build a React component that fetches a user's natal chart data and displays their sun, moon, and rising signs.

Prerequisites

Before we begin, ensure you have:

1. Node.js 18+ installed.
2. A React project (Next.js, Vite, or CRA).
3. A FreeAstroAPI Key. You can get one for free in your Dashboard.

Step 1: The API Client

First, let's create a strongly-typed utility function to fetch the data. We'll use the native fetch API, but you can use Axios if you prefer.

// lib/astro.ts

interface NatalRequest {
  year: number;
  month: number;
  date: number;
  hours: number;
  minutes: number;
  latitude: number;
  longitude: number;
  tz_str?: string; // e.g. "Europe/London"
}

export const fetchNatalChart = async (data: NatalRequest) => {
  const response = await fetch('https://api.freeastroapi.com/v1/natal/calculate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.NEXT_PUBLIC_ASTRO_API_KEY || '',
    },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    throw new Error('Failed to calculate chart');
  }

  return await response.json();
};

Step 2: The Chart Component

Now, let's create a component to display the data. We'll focus on the "Big Three": Sun, Moon, and Ascendant.

// components/NatalChart.tsx
import { useState, useEffect } from 'react';
import { fetchNatalChart } from '../lib/astro';

export default function NatalChart() {
  const [chart, setChart] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    // Example data: Born Jan 1st, 2000 at 12:00 PM in London
    fetchNatalChart({
        year: 2000,
        month: 1,
        date: 1,
        hours: 12,
        minutes: 0,
        latitude: 51.5074,
        longitude: -0.1278,
        tz_str: "Europe/London"
    })
    .then(setChart)
    .catch(console.error)
    .finally(() => setLoading(false));
  }, []);

  if (loading) return <div>Loading cosmic data...</div>;

  return (
    <div className="p-6 bg-slate-900 text-white rounded-xl">
      <h2 className="text-2xl font-bold mb-4">Your Natal Chart</h2>
      
      <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
        {/* Sun Sign */}
        <div className="bg-slate-800 p-4 rounded-lg">
          <h3 className="text-yellow-400 font-bold">Sun Data</h3>
          <p>{chart.planets.find(p => p.name === 'Sun').sign}</p>
        </div>

        {/* Moon Sign */}
        <div className="bg-slate-800 p-4 rounded-lg">
          <h3 className="text-blue-400 font-bold">Moon Data</h3>
          <p>{chart.planets.find(p => p.name === 'Moon').sign}</p>
        </div>

         {/* Ascendant (Rising) */}
        <div className="bg-slate-800 p-4 rounded-lg">
          <h3 className="text-purple-400 font-bold">Ascendant</h3>
          <p>{chart.axes.ascendant.sign}</p>
        </div>
      </div>
    </div>
  );
}

Step 3: Handling Timezones

One of the most challenging aspects of building astrology apps is handling historical timezones and Daylight Savings Time (DST). A person born in London in June has a different UTC offset than someone born in December.

FreeAstroAPI handles this for you.

Instead of manually calculating UTC offsets, simply pass the tz_str parameter (e.g., Europe/New_York, Asia/Kolkata) along with the local birth time. Our engine automatically calculates the precise universal time, taking into account historical time changes for that specific location and date.

Next Steps

Congratulations! You've successfully built a basic natal chart calculator.

From here, you can:

• Visualize the chart using SVG.
• Add interpretation texts for each placement.
• Calculate Synastry (compatibility) between two users.

Check out our Documentation for more advanced endpoints.