Gender-API.com Client for JavaScript and TypeScript

Official Node.js client for Gender-API.com.
Determine the gender of a first name, full name, or email address with ease using our V2 API.

Features

• Full V2 API Support: Access all latest endpoints.
• TypeScript Support: First-class type definitions included.
• ESM and CommonJS: import and require both work, with types for each.
• Modern Promise-based API: Uses async/await and fetch (Node 24+).
• Batch Processing: Resolve up to 100 names in a single request.
• Timeouts and Retries: 30 second timeout by default, automatic retry on 429 and 5xx.

Installation

npm install gender-api.com-client --save

Requires Node.js 24 or higher. Node 20 reached its end of life; use gender-api.com-client@2 if you are still on it.

Usage

First, get your free API Key from Gender-API.com Account.

The package ships both an ESM and a CommonJS build, so either style works:

// ESM / TypeScript
import { Client } from 'gender-api.com-client';

// CommonJS
const { Client } = require('gender-api.com-client');

Basic Example (TypeScript / ES Modules)

import { Client } from 'gender-api.com-client';

const client = new Client('YOUR_API_KEY');

async function checkGender() {
  try {
    // By First Name
    const result = await client.getByFirstName('Theresa');
    console.log(`${result.first_name} is ${result.gender} (Probability: ${result.probability})`);

    // By Full Name
    const fullResult = await client.getByFullName('John Smith');
    console.log(`${fullResult.first_name} ${fullResult.last_name} is ${fullResult.gender}`);
    
  } catch (error) {
    console.error('Error:', error);
  }
}

checkGender();

Common Scenarios

1. Check a First Name

const result = await client.getByFirstName('Andrea', { country: 'IT' });
// Andrea in Italy is usually male

2. Check an Email Address

const result = await client.getByEmailAddress('marie.curie@example.com');
console.log(result.gender); // female

3. Batch Processing (Multiple Names)

Process lists efficiently using the batch endpoints.

const names = [
  { id: '1', first_name: 'Theresa', country: 'US' },
  { id: '2', first_name: 'John', country: 'US' }
];

const results = await client.getByFirstNameMultiple(names);

results.forEach(r => {
  console.log(`ID: ${r.input.id}, Gender: ${r.gender}`);
});

4. Account Statistics

Check your remaining credits.

const stats = await client.getStatistics();
console.log(`Credits Remaining: ${stats.remaining_credits}`);

API Reference

The Client class provides the following methods:

• getByFirstName(firstName: string, options?: Omit<FirstNameRequest, 'first_name'>, requestOptions?: RequestOptions)
• getByFullName(fullName: string, options?: Omit<FullNameRequest, 'full_name'>, requestOptions?: RequestOptions)
• getByEmailAddress(email: string, options?: Omit<EmailRequest, 'email'>, requestOptions?: RequestOptions)
• getByFirstNameMultiple(items: FirstNameRequestMultipleItem[], requestOptions?: RequestOptions)
• getByFullNameMultiple(items: FullNameRequestMultipleItem[], requestOptions?: RequestOptions)
• getByEmailAddressMultiple(items: EmailRequestMultipleItem[], requestOptions?: RequestOptions)
• getCountryOfOrigin(request: CountryOfOriginRequest, requestOptions?: RequestOptions)
• getStatistics(requestOptions?: RequestOptions)

All methods return a Promise that resolves to the result object or throws an error.

The options argument of the single lookups carries the optional country, locale and ip parameters. The batch endpoints accept at most MAX_BATCH_SIZE (100) items per call; a longer array is rejected client-side with a RangeError before a request is sent.

Constructor options

import { Client } from 'gender-api.com-client';

// Default base url: https://gender-api.com/v2
const client = new Client('YOUR_API_KEY');

// Point the client somewhere else, e.g. a mock server in tests
const local = new Client('YOUR_API_KEY', { baseUrl: 'http://localhost:8080/v2' });

// All options
const tuned = new Client('YOUR_API_KEY', {
  baseUrl: 'https://gender-api.com/v2', // default
  timeoutMs: 30000,                     // default, 0 waits indefinitely
  retries: 2,                           // default, 0 disables retries
  retryDelayMs: 500                     // default backoff base: 500, 1000, 2000 ms
});

Timeouts, aborts and retries

Every request is aborted after timeoutMs, 30 seconds by default, and throws a GenderApiTimeoutError. Pass your own AbortSignal per call to cancel from the outside:

const controller = new AbortController();
setTimeout(() => controller.abort(), 1000);

const result = await client.getByFirstName('Theresa', undefined, {
  signal: controller.signal,
  timeoutMs: 5000 // overrides the client wide timeout for this call
});

A caller abort is rethrown untouched as an AbortError, so your own cancellation logic keeps working.

Retries cover 429 and 5xx responses and network failures, with exponential backoff. A Retry-After header sent by the API takes precedence over the backoff. Timeouts and caller aborts are never retried: the client cannot know whether the server already processed the request.

Error handling

Three error types can be thrown:

Error	When
GenderApiError	The API answered with an error, or a 200 with an error body
GenderApiTimeoutError	The request exceeded timeoutMs
GenderApiNetworkError	The request never reached the API (DNS, TLS, refused connection); the original error is in cause

GenderApiError keeps the fields of the V2 ErrorModel instead of flattening them into a string:

import { Client, GenderApiError } from 'gender-api.com-client';

try {
  await client.getByFirstName('Theresa');
} catch (error) {
  if (error instanceof GenderApiError) {
    console.error(error.status); // 400
    console.error(error.title);  // 'invalid-key'
    console.error(error.type);   // link to the error description
    console.error(error.detail); // human readable description
    console.error(error.message); // 'API Error 400: Invalid API key.'
  }
}

Exported types and constants

Client, ClientOptions, RequestOptions, GenderApiError, GenderApiTimeoutError, GenderApiNetworkError, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, DEFAULT_RETRIES, DEFAULT_RETRY_DELAY_MS, MAX_BATCH_SIZE, VERSION, USER_AGENT, plus all request and result interfaces from lib/models.ts (FirstNameRequest, FullNameRequest, EmailRequest, FirstNameRequestMultipleItem, FullNameRequestMultipleItem, EmailRequestMultipleItem, CountryOfOriginRequest, SingleNameResult, FullNameResult, EmailResult, CountryOfOriginResult, StatisticResult, …).

License

MIT