API Docs Unified API v2.0

API v1.0

We also offer another API version with endpoints that are easier to integrate. If you're a beginner in implementing API's you can switch to our v1.0 endpoint.
View API v1.0

OpenAPI

View our API documentation in Swagger

Postman

Import our API definition into Postman
Query By First Name
Query By Full Name
Query By Email Address
Get Country Of Origin
Get Stats
Error Codes

Query by first name

This is the easiest way to query a gender by a name. Each response is JSON encoded:

Post
Required Requests: 1
URL
https://gender-api.io/v2/gender
Headers
Content-Type: application/json
Authorization: Bearer <your authorization token>
link
JSON Payload
Field Type Required Description
first_name string Yes Name to query
country string No ISO 3166 ALPHA-2 Country Code
link
locale string No Browser Locale
ip string No Valid IPv4 or IPv6 address
id string No Max 50 chars. You can set this id to any alphanumeric value you want. As an example, you can set the id to your internal id of the dataset in your database. In an asynchronus environment this can help you to better connect the response to a previous request

Examples

Query by first name only
play_arrow Test live with codepen.io 
{"first_name":"Sandra"}
Query by first name and country code
play_arrow Test live with codepen.io 
{"first_name":"Sandra","country":"US"}
Query by first name and browser locale
play_arrow Test live with codepen.io 
{"first_name":"Sandra","locale":"en_US"}
Query by first name and use an IP address for localization
play_arrow Test live with codepen.io 
{"first_name":"Sandra","ip":"54.201.16.177"}
Query multiple names in a single request
play_arrow Test live with codepen.io 
[{"first_name":"Sandra","country":"US"},{"first_name":"Jason","country":"US"}]
Response
{
    "input": {
        "first_name": "Sandra"
    },
    "details": {
        "credits_used": 1,
        "samples": 464,
        "country": null,
        "first_name_sanitized": "sandra",
        "duration": "436ms"
    },
    "result_found": true,
    "first_name": "Sandra",
    "probability": 0.85,
    "gender": "female"
}
Field Type Description
input object The submitted payload
details.credits_used int The amount of requests used for this query
details.samples int Number of records found in our database which match your request
details.country string The country we found
details.first_name_sanitized string The name after we applied our normalizer to it
details.duration string Time the server needed to process the request
result_found bool True if we were able to query a gender for the given name
first_name string The first name we used for genderization
probability float This value (between 0 and 1) determines the reliability of our database. A value of 1 means that the results on your gender request are 100% accurate.
gender string Possible values: male, female, unknown
This product includes GeoLite2 data created by MaxMind, available from http://www.maxmind.com.
Chat