API Documentation

Gender Engine exposes a single REST endpoint for determining the gender of a given name.

Quick Start

Pull and run the Docker image to get started in seconds:

Terminal

# Pull the latest image
$ docker pull ghcr.io/cryling/gender-engine:latest

# Start the server on port 8080
$ docker run -p 8080:8080 ghcr.io/cryling/gender-engine

Endpoint

GET /api/v1/gender

Returns the predicted gender for a given name, optionally scoped to a specific country.

Query Parameters

Parameter	Type	Required	Description
`name`	string	required	The first name (or full name) to look up.
`country`	string	optional	ISO 3166-1 alpha-2 country code (e.g. `US`, `DE`). Improves accuracy for region-specific names.

Example Request

Try it out with the public instance:

bash

$ curl -X GET "https://gender.kianreiling.com/api/v1/gender?name=tom&country=US"

Or if you're self-hosting:

bash

$ curl -X GET "http://localhost:8080/api/v1/gender?name=tom&country=US"

Example Response

json

{
  "message": "tom could be found",
  "result": {
    "Name": "tom",
    "Gender": "M",
    "Country": "US",
    "Probability": "0.99560356"
  }
}

Response Fields

Field	Type	Description
`message`	string	Human-readable status message.
`result.Name`	string	The name that was queried.
`result.Gender`	string	`"M"` for male, `"F"` for female.
`result.Country`	string	The country code used for the lookup.
`result.Probability` optional	string	Confidence score between 0 and 1. Only returned when sufficient data is available for the given name/country combination.

Notes

• The API is stateless and does not log or store any requests.
• The country parameter is optional but recommended for names common across cultures (e.g. "Andrea" is male in Italian, female in English).
• Supported country codes follow the ISO 3166-1 alpha-2 standard.
• Gender data is sourced from the World Gender Name Dictionary (WGND 2.0), published via the Harvard Dataverse.