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
- Node.js 22 or newer
- A verified Cosmic Ephemeris account
- An API key with the
astro:natal-svgscope
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
Create a .env file in the project folder:
COSMICEPHEMERIS_KEY=PASTE_YOUR_FULL_API_KEY_HERE
Replace the placeholder with your full API key. You can create one on the API Keys page.
Add .env to your .gitignore:
.env
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;
}
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
On success, you'll see:
Created birth-chart.svg.
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:
-
themeto"light"or"monochrome" -
show_aspectstofalsefor a simpler chart -
zodiacto"sidereal"withayanamsa: "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-svgscope. - 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)