Frequently Asked Question

genderLookup - Determine Gender from a given foreanme

Last Updated 7 days ago

GenderLookup API

Overview

The GenderLookup API provides gender and title information based on a given forename. It queries a database to determine the likely gender and appropriate title for the provided name across 8 million forenames in 15 languages. Logic is applied to handle deliberate mis-spelling and spelling variations.

The returned information is a best guess based on the information given, it is not 100% accurate

Version

1.001

Endpoint

/v2/genderlookup.php

Authentication

This API requires authentication using an API key. The key should be passed in the HTTP_X_API_KEY header.

Request Parameters

Parameter	Type	Description
f	string	Forename to look up (required, max 30 characters)

Response

The API returns a JSON object with the following structure:

Field	Type	Description
status	string	"ok" if successful, or an error message
forename	string	The forename as stored in the database (only if found)
gender	string	"M" for male, "F" for female, or "?" if not found
title	string	"Mr" for male, "Mrs" for female (only if found)

Example Response (Success)


{
  "status": "ok",
  "forename": "john",
  "gender": "M",
  "title": "Mr"
}

Example Response (Not Found)


{
  "status": "Forename not found",
  "gender": "?"
}

Error Handling

If no forename is provided: {"status": "Missing forename"}
If the forename is not found in the database: {"status": "Forename not found", "gender": "?"}
If there's an authentication error: {"status": "[validation status]"}

Notes

The API converts the input forename to lowercase before querying the database.
The gender determination is based on a very large lookup table, fuzzy logic is applied.
The title is automatically set to "Mr" for male names and "Mrs" for female names.

Security

Ensure that the API key is kept secure and not exposed in client-side code.
All responses are sent with the "Content-Type: application/json" header.