DEV Community

Cosmic Ephemeris
Cosmic Ephemeris

Posted on

Generate a Birth Chart SVG with Node.js and an Astrology API

Want to turn a date, time, and location into a birth-chart image?

This walkthrough uses Node.js to call an astrology API and save the result as an SVG. You can open the image locally or serve it from your application.

We're the team behind Cosmic Ephemeris, the API used in this example.

What you'll need

The example uses synthetic birth details.

1. Create the project

Run:

mkdir birth-chart-demo
cd birth-chart-demo
npm init -y
npm install cosmicephemeris@0.5.0
Enter fullscreen mode Exit fullscreen mode

Create a .env file in the project folder:

COSMICEPHEMERIS_KEY=PASTE_YOUR_FULL_API_KEY_HERE
Enter fullscreen mode Exit fullscreen mode

Replace the placeholder with your full API key. You can create one on the API Keys page.

Add .env to your .gitignore:

.env
Enter fullscreen mode Exit fullscreen mode

Keep the key in your local or server environment. Your frontend should never receive it.

2. Generate the SVG

Create birth-chart.mjs:

import { writeFile } from "node:fs/promises";
import {
  CosmicEphemeris,
  CosmicEphemerisError,
} from "cosmicephemeris";

try {
  const api = new CosmicEphemeris();

  const chart = await api.natalSvg({
    birth: {
      date: "1990-01-01",
      time: "12:00",
      timezone: "America/New_York",
      lat: 40.7128,
      lon: -74.006,
    },
    zodiac: "tropical",
    house_system: "equal",
    theme: "dark",
    show_aspects: true,
  });

  await writeFile("birth-chart.svg", chart.svg, {
    encoding: "utf8",
    flag: "wx",
    mode: 0o600,
  });

  console.log("Created birth-chart.svg.");
} catch (error) {
  if (error instanceof CosmicEphemerisError) {
    console.error(
      "Chart request failed:",
      error.code,
      error.status ?? ""
    );
  } else if (error?.code === "EEXIST") {
    console.error(
      "birth-chart.svg already exists. Rename it before running again."
    );
  } else {
    console.error(
      "Could not save the chart. Check your folder permissions."
    );
  }

  process.exitCode = 1;
}
Enter fullscreen mode Exit fullscreen mode

natalSvg() calculates and renders the chart in one request. The SVG comes back in chart.svg, so there is no need for a separate calculation call first.

The wx flag prevents accidentally overwriting an existing file.

3. Run it

From the project folder:

node --env-file=.env birth-chart.mjs
Enter fullscreen mode Exit fullscreen mode

On success, you'll see:

Created birth-chart.svg.
Enter fullscreen mode Exit fullscreen mode

Open the generated file in your browser.

Running the script calls the hosted API and consumes your account's request allowance. Rename the output file before running it again.

Why the timezone matters

The date and time in this request are local to America/New_York.

Coordinates and timezone serve different purposes: coordinates identify the location, while the timezone lets the API interpret the local time. Keep both explicit, especially when daylight-saving time applies.

Customize the result

Try changing:

  • theme to "light" or "monochrome"
  • show_aspects to false for a simpler chart
  • zodiac to "sidereal" with ayanamsa: "lahiri"

When integrating this into an app, generate the chart on your server and serve it through an image route with Content-Type: image/svg+xml. Keep charts containing personal birth details behind your application's access controls.

Troubleshooting

  • 401 or 403: Check the key, account status, and astro:natal-svg scope.
  • 429: Check request allowance and rate limits before retrying.
  • EEXIST: Rename the existing SVG file.
  • Missing .env: Run the command from the folder containing that file.

The full tutorial includes a chart preview, downloadable script, and additional integration details.

You can also watch the short demonstration.

Top comments (0)