Use GenderAPI.io V2 with JavaScript and Node.js

Keep the integration on your Node.js server

This guide calls the GenderAPI.io V2 endpoint https://api.genderapi.io/api/v2/gender with a Bearer API key. Use Node.js 22 or later and download genderapi-v2.mjs into your project. This ES module uses built-in fetch and AbortSignal.timeout; no npm package is needed. The .mjs extension lets you import it from another ES module without changing package.json.

Set GENDERAPI_API_KEY in the server environment. Do not bundle it into React, Vue or browser JavaScript. Let your own server authenticate application users and call GenderAPI.io. The placeholder below is not a working key; importing the module or running it without an explicit run flag sends no request.

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Download genderapi-v2.mjs →
• Verify your key with the free usage endpoint →

Send one JSON POST with an explicit AI policy

Save this code as single.mjs beside the downloaded module and run node single.mjs. It sends the V2 fields type and value with options.ai_mode: off. Read the estimate from response.data and the request and billing details from response.meta. A completed lookup costs 1 credit even when gender is null; the sample name does not guarantee a particular result.

The helper requires an explicit AI mode and a 24-character hexadecimal key, then checks meta.access.mode is api_key. A successful trial response triggers an access-mismatch error instead of silently proceeding. The server may already have consumed a trial credit before the helper detects that mismatch.

import { predict, GenderAPIError } from "./genderapi-v2.mjs";

try {
  const response = await predict({
    type: "name", value: "Alice", options: { ai_mode: "off" },
  });
  const result = response.data;
  console.log(result.result_status, result.gender);
  console.log(result.confidence, result.confidence_kind);
  console.log(response.meta.usage);
} catch (error) {
  if (!(error instanceof GenderAPIError)) throw error;
  // Do not log error.body: it can include the submitted value.
  console.error("Request failed:", error.code, error.requestId);
  process.exitCode = 1;
}

• All single-request fields →

Keep the result and its evidence together

An inferred association is not a person's self-declared gender. Keep the original input, the returned evidence and any information provided by the person separate. An unknown result is a valid outcome; it should not become a guessed category in your application.

• Response fields and unknown outcomes →
• Accuracy and confidence explained →
• Data sources and the dated database profile →

Handle each item in a mixed batch

GenderAPI.io V2 uses POST https://api.genderapi.io/api/v2/gender/batch for mixed batches: up to 50 items with an account key or 10 for the IP trial. These examples require an account key. Give every item a stable, unique id and explicit AI mode. A batch can mix names, emails and usernames, with optional country context on each item.

Read every item in data and the summary in meta.summary. HTTP 200 can include item errors; an all-failed batch can be a top-level Problem response containing the results. Successful unknowns count as succeeded. The original index and id let you attach an outcome to the correct source row.

For larger jobs, divide input into groups of at most 50 and submit sequentially at first. Save each response and its usage before advancing. Stop on transport, account or unconfirmed-billing failures and reconcile the current group. Add concurrency only after checking your account limits; a batch-size limit is not a throughput guarantee.

import { predictBatch, GenderAPIError } from "./genderapi-v2.mjs";

const items = [
  { id: "row-1", type: "name", value: "Alice", options: { ai_mode: "off" } },
  { id: "row-2", type: "email", value: "alex@example.com", options: { ai_mode: "off" } },
  { id: "row-3", type: "username", value: "sample_handle", options: { ai_mode: "off" } },
];
try {
  const response = await predictBatch(items);
  for (const item of response.data) {
    if (item.error) {
      console.log(item.id, "failed", item.error.code);
    } else {
      console.log(item.id, item.data.result_status, item.data.gender);
    }
  }
  console.log(response.meta.summary, response.meta.usage);
  if (response.meta.summary.failed > 0) process.exitCode = 2;
} catch (error) {
  if (!(error instanceof GenderAPIError)) throw error;
  // error.body can retain an all-failed batch and billing details.
  console.error("Batch needs review:", error.code, error.requestId);
  process.exitCode = 1;
}

• Batch input, results and billing →

Choose when to use AI

forceToGenderize is optional for names, email addresses and usernames. With it enabled, omit ai_mode or use fallback; off and always conflict with it and return 422. A positive starting balance is enough to begin a request even if its final charge takes the balance below zero.

Nickname mode can return a gender with name: null. It can also return an unknown result. Neither ordinary fallback nor nickname inference guarantees a correct or non-null answer.

This JavaScript helper always requires options.ai_mode. For nickname inference, send forceToGenderize: true together with options: { ai_mode: 'fallback' }.

• AI options and nickname inference →
• Credits and usage →

Decide what to do after a failure

The examples send each operation once. They do not retry automatically: a new submission is a new billable operation. A timeout or connection failure means the client did not receive a complete response; it does not prove that the server stopped or that no credits were charged.

Keep the returned request ID and billing state with your job record. The error object retains the response for controlled inspection, but it can contain the original input; do not put the whole object, response or API key into routine logs.

• Problem Details and retry decisions →
• Credits and billing confirmation →

Understand the fetch timeout and response checks

The default timeout is 10,000 milliseconds using AbortSignal.timeout, including reading the response body. Aborting the client does not establish that server processing or billing stopped. The module disables redirects, distinguishes HTTP failures from unreadable responses, and never retries automatically.

Transport-fixture tests exercise successful responses, unknowns, partial batches, credential fallbacks and errors. No real prediction or credit operation is needed for these tests; they are not a live availability or accuracy benchmark.

node genderapi-v2.mjs --run-single
# Run separately to submit another billable sample batch:
node genderapi-v2.mjs --run-batch

• Node.js fetch reference →
• Node.js AbortSignal.timeout reference →

Frequently asked questions