Numerology API for JavaScript and Node.js

Your first chart

Get a free key from the pricing section and set it as NUMEROLOGY_API_KEY:

const res = await fetch("https://simplenumerologyapi.com/v1/charts/pythagorean", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "X-API-Key": process.env.NUMEROLOGY_API_KEY,
  },
  body: JSON.stringify({
    first_name: "María",
    middle_name: "Stefania",
    last_name: "García López",
    birthdate: "1990-03-12",
  }),
});
if (!res.ok) throw new Error(`Numerology API: ${res.status}`);
const chart = await res.json();

console.log(chart.life_path_number);    // 7
console.log(chart.destiny_number);      // 5
console.log(chart.karmic_debt_numbers); // [13]

The response has 47 fields, from life path and soul urge to pinnacles, challenges and planes of expression. The chart object reference documents each one.

A small helper

Every endpoint is a POST with a JSON body, so one function covers them all:

const API = "https://simplenumerologyapi.com";

async function numerology(path, body) {
  const res = await fetch(API + path, {
    method: "POST",
    headers: { "content-type": "application/json", "X-API-Key": process.env.NUMEROLOGY_API_KEY },
    body: JSON.stringify(body),
  });
  const json = await res.json();
  if (!res.ok) throw Object.assign(new Error(json.error.message), json.error, { status: res.status });
  return json;
}

await numerology("/v1/cycles", { birthdate: "1990-03-12", date: "2026-09-26", years_ahead: 3 });
await numerology("/v1/compatibility", { a: personA, b: personB });
await numerology("/v1/charts/batch", { charts: people });   // up to 100 charts

TypeScript

The OpenAPI 3.1 document describes every response, so a tool such as openapi-typescript can generate the types for you. One modelling note if you write them by hand: type number fields as number, not a 1–9 union, because master numbers 11, 22 and 33 survive reduction. hidden_passion_number is number[], since ties are allowed.

Next.js and other front ends

Keys are server credentials, and the API sends no CORS headers, so never call it from the browser with a real key. Call it from a route handler, server action, API route or edge function, and send only the fields you need to the client:

// app/api/chart/route.js (Next.js App Router)
export async function POST(req) {
  const { first_name, last_name, birthdate } = await req.json();
  const res = await fetch("https://simplenumerologyapi.com/v1/charts/pythagorean", {
    method: "POST",
    headers: { "content-type": "application/json", "X-API-Key": process.env.NUMEROLOGY_API_KEY },
    body: JSON.stringify({ first_name, last_name, birthdate }),
  });
  const chart = await res.json();
  if (!res.ok) return Response.json(chart, { status: res.status });
  return Response.json({
    lifePath: chart.life_path_number,
    destiny: chart.destiny_number,
    soulUrge: chart.soul_urge_number,
  });
}

Charts are deterministic, so cache them forever: the same name and birthdate always produce the same numbers.

Errors and retries

Every error has the same JSON shape: {"error": {"type", "code", "message", "param", "request_id"}}. Retry 429 and 5xx responses with backoff, and honour Retry-After when it is sent. A 402 means the month’s quota is used up, and the X-Quota-Remaining header on every response shows what is left.

Frequently asked questions

Is there a free numerology API for JavaScript?

Yes. The free plan includes 100 charts a month on every endpoint, with no card.

Can I call the numerology API directly from the browser?

Not with a real key. API keys are server credentials, so the API sends no CORS headers. Call it from your backend, a serverless function or an edge function instead.

Does it work with Deno, Bun and Cloudflare Workers?

Yes. It is a plain HTTPS JSON API, so the built-in fetch in Node 18+, Deno, Bun and edge runtimes is all you need.

Does it support TypeScript?

Yes. Generate types from the OpenAPI 3.1 document at /openapi.json, or write them from the chart object reference.