Skip to content
Finowl

Node.js · Gender prediction

Predict gender from a name in Node.js

For Node.js services that personalize onboarding emails or build aggregate audience reports, the gender name endpoint returns a compact prediction under data. The interesting fields are result_status, gender, confidence, confidence_kind and source. Sending a country code with each name gives Finowl a hint for names like Jean or Andrea whose usage varies by region, and the response echoes the country it used.

The script below looks up a handful of names in sequence and prints a line for each one. When result_status is unknown, gender is null and reason explains why, so the code logs the reason instead of guessing. Results like that are successful, charged responses, so your code should store them as unknown rather than retry them in the hope of a different answer.

Steps

  1. 1

    Export FINOWL_API_KEY and save the example as gender-by-name.mjs.

  2. 2

    Run node gender-by-name.mjs to see predictions for each name and country pair.

  3. 3

    Check result_status first and only read gender when it is identified.

  4. 4

    Persist confidence and source with each prediction so reports can exclude weak results.

  5. 5

    Switch to /v1/gender/batch when you need to enrich more than a few records at once.

Get an API key API reference
Predict gender from a name in Node.js
// gender-by-name.mjs (Node.js 18+)
import { setTimeout as sleep } from "node:timers/promises";

async function predictGender(name, country) {
  const body = country ? { name, country } : { name };
  for (let attempt = 0; attempt < 3; attempt++) {
    const res = await fetch("https://api.finowl.co/v1/gender/name", {
      method: "POST",
      headers: {
        Authorization: "Bearer " + process.env.FINOWL_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(10_000),
    });
    if (res.ok) return (await res.json()).data;

    const code = (await res.json().catch(() => ({})))?.error?.code ?? "unknown_error";
    if (res.status === 400) throw new Error("Bad input for " + name + ": " + code);
    if (res.status === 401) throw new Error("Unauthorized: check FINOWL_API_KEY");
    if (res.status === 429 && code === "rate_limited") {
      await sleep((Number(res.headers.get("retry-after")) || 1) * 1000);
      continue;
    }
    throw new Error("Finowl error " + res.status + ": " + code);
  }
  throw new Error("Rate limited too many times");
}

const people = [
  { name: "Jean", country: "FR" },
  { name: "Jean", country: "US" },
  { name: "Andrea", country: "IT" },
  { name: "Zzyxq" },
];

for (const { name, country } of people) {
  const p = await predictGender(name, country);
  const label = name + " (" + (country ?? "no country") + ")";
  if (p.result_status === "unknown") {
    console.log(label + ": unknown, reason=" + p.reason);
    continue;
  }
  console.log(
    label + ": " + p.gender + " confidence=" + p.confidence +
      " source=" + p.source + " country=" + p.country
  );
}

IN PRODUCTION

Production tips

  • Sending names one at a time with await in a loop is simple but slow. For imports, group up to 50 items into one batch request, which counts once toward the rate limit.

  • Normalize the country hint from your own data, such as an ISO code on the billing address. Finowl accepts any case, and the hint is optional, so omit it when you lack a trustworthy value.

  • Use predictions for aggregate analytics or low-stakes personalization only, mention the lookup in your privacy notice, and let users override the value in their profile.

Each lookup costs 1 credit (3 when it requests AI), with 100 free credits every month. See pricing and error codes.

A FEW GOOD QUESTIONS

Common questions

Related guides

Predict gender from a name in Node.js

Grab an API key, paste the example and run it. 100 free credits every month.

Start buildingView pricing