← All developer projects

Compare two birth charts with Node.js

Place two synthetic birth charts on one wheel and show the major aspects between them. Use the result as a visual feature in your relationship or astrology app.

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.

1. Open API Keys and enter a Key label, such as Developer tutorial.
2. Under Access scopes, select astro:synastry-svg, then click Create API key. Selecting a specific scope replaces the default “All calculation endpoints”.
3. 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 synastry-chart-demo
cd synastry-chart-demo
npm init -y
npm install cosmicephemeris@0.5.0

Already 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_HERE

Replace 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 synastry-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:

.env

Keep 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 synastry-chart.mjs, or download the script. It calls POST https://api.cosmicephemeris.com/api/astro/synastry-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";

const output = "synastry-chart-output";
try {
  const api = new CosmicEphemeris();
  await mkdir(output, { mode: 0o700 });
  const chart = await api.synastrySvg({
    // Both birth records are synthetic examples.
    personA: {
      date: "1990-01-01", time: "12:00", timezone: "America/New_York",
      lat: 40.7128, lon: -74.006,
    },
    personB: {
      date: "1992-06-15", time: "08:30", timezone: "Europe/London",
      lat: 51.5074, lon: -0.1278,
    },
    zodiac: "tropical", house_system: "equal",
    theme: "dark", show_aspects: true,
  });
  await writeFile(`${output}/synastry.svg`, chart.svg, {
    encoding: "utf8", flag: "wx", mode: 0o600,
  });
  console.log("Created synastry-chart-output/synastry.svg.");
} 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 synastry-chart.mjs

If your server already sets the environment variable, omit --env-file=.env. Results are saved in the private synastry-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.

Read and display the wheel

Person A supplies the inner chart and its houses; person B supplies the outer planetary positions. Lines connect the major cross-chart aspects. The response includes the SVG and explicit calculation settings; it does not supply a compatibility percentage or relationship verdict.

Save chart.svg and display it with an image element, as in the birth-chart display example. Serve private charts through your own access-controlled image route with Content-Type: image/svg+xml.

Adapt the comparison

Keep each person’s local date, time, IANA timezone and numeric coordinates together. Swap personA and personB to change the inner wheel. Set show_aspects: false to hide the connecting lines, or use the light or monochrome theme. If your app needs an aspect table as well as the image, the separate synastry JSON endpoint provides structured data and uses an additional request.

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