Gender API for JavaScript

Keep the API call on the server

The JavaScript client runs in server-side runtimes including Node.js, Deno and Bun. Do not bundle a private API key into browser code. A secret included in a frontend build can be read by every visitor and reused outside your application.

Create the client from a server environment variable and reuse it. Send a country only when your record contains a meaningful market signal. The response includes gender, probability, confidence, total_names and source, so model unknown and unverified states explicitly rather than narrowing the type to two strings.

If a browser needs the result, expose a narrow authenticated endpoint in your own backend. Validate the input there, apply your user-level limits and return only the fields the interface needs.

import { NameGender } from 'namegender';

const client = new NameGender(process.env.NAMEGENDER_API_KEY);
const result = await client.name('Ayşe', { country: 'TR' });

console.log(result.gender);
console.log(result.probability);
console.log(result.source);

Batch independent lookups

Use the bulk method when several names are already available. One request reduces connection overhead and gives retry logic a clear unit of work. For more than the current bulk limit, split the input into bounded chunks rather than starting an unbounded Promise.all over individual calls.

Preserve the original record key beside every submitted lookup. Names repeat and results are not database identifiers. Joining only on a normalized name can be wrong when country differs, so use the normalized name and country together or retain input positions.

For queue workers, make each chunk idempotent and persist completion before acknowledging the job. A process restart should resend at most one bounded chunk, not an entire customer export.

const results = await client.bulk(['Ayşe', 'Mehmet', 'Priya']);
const usable = results.filter((item) =>
  item.gender !== null && item.probability >= 90
);

Handle responses by meaning

An unknown gender is data, not a thrown failure. Display or store a neutral fallback and keep the row available for review. Authentication, validation, quota and network failures are operational states and should follow separate code paths.

Abort requests that exceed your service timeout. Retry transient responses with bounded exponential backoff and jitter, and respect Retry-After when it is present. Never retry malformed input or an invalid key in a tight loop.

Avoid sending names to analytics and generic error trackers by default. Log status, duration and a request identifier for operations; keep the customer payload inside the system that is authorised to process it.

Questions

Related pages