Gender API plugin

• A failure arrives with HTTP 200. Gender API puts errno and errmsg in the body of every answer, with 0 on a good one. A live probe with a bad key answered 200 and {"errno":40,"errmsg":"invalid or missing key"}. The plugin throws whenever the code is non-zero, whatever the status was.
• The documented codes are 10, 11, 20, 21, 30, 40 and 500. They cover an invalid country code, a country count that does not match the name count, a missing name, more than 100 names, a used-up quota, an unknown key, and their own internal failure. GenderApiAPIError exposes errno so a caller can branch on them, and GENDER_API_ERRNO names each one.
• The quota is errno: 30, not a 429. A limit that ran out answers 200 with the code and a link to the pricing page, so it is not retried.
• gender can be unknown. The answer is still a success: samples and accuracy tell you how weak the data is. Gender API never returns a null gender.
• A country changes the answer. Andrea is male in Italy and female in Germany, and multi accepts one country for every name or one per name in the same order.
• A name is normalized before lookup. name_sanitized is the form the database actually matched, which is worth reading when a result looks wrong.
• fullName returns a null last name under strict. With strict: true Gender API returns a null last_name when it is not in the database, instead of guessing one.

• 6 typed API operations

Setup

npm install corsair @corsair-dev/genderapi better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/genderapi better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/genderapi better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/genderapi better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { genderapi } from '@corsair-dev/genderapi';

export const corsair = createCorsair({
	plugins: [
		genderapi(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

genderapi()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'genderapi',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.genderapi.api.lookup.name({ name: 'Andrea', country: 'IT' });

What’s next