Add today’s transits to a birth chart
Combine a natal chart with planetary positions for another date. The script uses today’s UTC date by default, or accepts a date you choose.
Available on Free: 500 standard requests per UTC calendar month. No credit card required. This example makes 1 calculation request per run.
1. Set up your project
You need Node.js 22+ and a verified Cosmic Ephemeris account. Create a free account and verify your email if you have not already.
- Open API Keys and enter a Key label, such as
Developer tutorial. - Under Access scopes, select
astro:transit-svg, then click Create API key. Selecting a specific scope replaces the default “All calculation endpoints”. - Click Copy key and save the complete key privately. It is shown only once; the shortened prefix in the key list will not work.
mkdir transit-chart-demo
cd transit-chart-demo
npm init -y
npm install cosmicephemeris@0.5.0Already have a key? Reuse it if it includes this tutorial’s scope. One key can serve several projects: select all their required scopes when creating it. You do not need a separate key for each tutorial.
Save your key in a private .env file
Inside the project folder you just created, use your text editor to create a file named .env (not .env.txt). Put this single line in it:
COSMICEPHEMERIS_KEY=PASTE_YOUR_FULL_API_KEY_HEREReplace PASTE_YOUR_FULL_API_KEY_HERE with the full key you copied. This is a placeholder, not a working key. Keep .env in the same folder where you will run transit-chart.mjs; the command later uses --env-file=.env to load it.
Create or open .gitignore in that folder and add this line so Git will ignore the key file:
.envKeep the key on your server or local development computer. Do not put it in browser JavaScript, URLs, screenshots or a public repository. Signing in to this website does not authenticate your Node.js script; it still needs the key. See the authentication guide.
2. Save the complete script
Save this as transit-chart.mjs, or download the script. It calls POST https://api.cosmicephemeris.com/api/astro/transit-svg.
// Node.js 22+; server-side only. Install: npm install cosmicephemeris@0.5.0
// Set COSMICEPHEMERIS_KEY privately. No automatic retries.
import { mkdir, writeFile } from "node:fs/promises";
import { CosmicEphemeris, CosmicEphemerisError } from "cosmicephemeris";
// Optional first argument: an explicit UTC date, for example 2026-10-28.
// Without it, use today's UTC date at 12:00 UTC (not the current instant).
const transitDate = process.argv[2] ?? new Date().toISOString().slice(0, 10);
const output = "transit-chart-output";
try {
if (!/^\d{4}-\d{2}-\d{2}$/.test(transitDate)) {
console.error("Use a date in YYYY-MM-DD format.");
process.exit(1);
}
const api = new CosmicEphemeris();
await mkdir(output, { mode: 0o700 });
const chart = await api.transitSvg({
birth: {
date: "1990-01-01", time: "12:00", timezone: "America/New_York",
lat: 40.7128, lon: -74.006,
},
transitDate, transitTime: "12:00", timezone: "UTC",
zodiac: "tropical", house_system: "equal",
theme: "dark", show_aspects: true,
});
await writeFile(`${output}/transits.svg`, chart.svg, {
encoding: "utf8", flag: "wx", mode: 0o600,
});
console.log(`Created transit-chart-output/transits.svg for ${transitDate} at 12:00 UTC.`);
} catch (error) {
if (error instanceof CosmicEphemerisError) {
console.error("API request failed:", error.code, error.status ?? "");
} else if (error?.code === "EEXIST") {
console.error("Output folder already exists. Rename it before another run.");
} else {
console.error("Could not finish. Check the input and folder permissions.");
}
process.exitCode = 1;
}3. Run it once
node --env-file=.env transit-chart.mjs 2026-10-28If your server already sets the environment variable, omit --env-file=.env. Results are saved in the private transit-chart-output folder. Rename an existing folder before another run; the script checks that before making a request. A failed run may leave an empty or partially completed folder.
Each admitted calculation uses one standard unit, including failed calculations. A successful run uses one unit. A timeout may still consume quota. The script makes no automatic retries. Viewing these sample results and downloading files makes no calculation request.
Today or a chosen date
The command above reproduces the dated preview. Omit the date argument to use today’s UTC date:
node --env-file=.env transit-chart.mjsThe example always uses 12:00 UTC. That means noon on the selected date, not the current instant. Change transitTime and timezone explicitly if your product needs a different moment.
The natal chart is the inner wheel and transits are the outer wheel. Transit positions use the birth location. The chart displays positions and aspects; it does not generate an interpretation.
Add it to your app
Keep the API call on your server and display the returned SVG through an image route. You can reuse a saved result for the same birth details, transit instant and settings. Request a new chart when those inputs change; avoid making a calculation on every browser repaint. The downloaded script runs once and does not create a daily schedule.
Inputs and troubleshooting
If Node says it cannot find .env: run the command from the project folder and check that the filename is exactly .env. If the key is missing or invalid, replace the placeholder with your complete key. If you receive HTTP 403, check the key’s required scope above.
Modern civil dates cover 1800-01-01 through 2200-12-31, subject to route and derived-time limits. Use explicit timezones. Historical inputs require the separate historical date contract; do not substitute BCE years into these date strings. The birth details shown here are synthetic; keep real customer data private.
A missing or malformed key fails before the request. For HTTP 401/403, check your key, account and scope. For 400, check the documented input. For 429, check allowance, key budget and rate or concurrency limits. For a timeout or server error, check service status before deciding whether to rerun.
All developer projects · SDK quickstart · Postman collection