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.
• Modern Promise-based API: Uses async/await and fetch (Node 20+).
• Batch Processing: Resolve up to 100 names in a single request.

Installation

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

Requires Node.js 20 or higher.

Usage

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

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?: RequestOptions)
• getByFullName(fullName: string, options?: RequestOptions)
• getByEmailAddress(email: string, options?: RequestOptions)
• getByFirstNameMultiple(items: FirstNameRequestItem[])
• getByFullNameMultiple(items: FullNameRequestItem[])
• getByEmailAddressMultiple(items: EmailRequestItem[])
• getCountryOfOrigin(request: CountryOfOriginRequest)
• getStatistics()

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

License

MIT