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.
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.com/v2/gender
|
||||||||||||||||||||||||
Headers |
Content-Type: application/json
Authorization: Bearer <your authorization token>
|
||||||||||||||||||||||||
JSON Payload |
|
Examples
Query by first name only
{"first_name":"Sandra"}
Query by first name and country code
{"first_name":"Sandra","country":"US"}
Query by first name and browser locale
{"first_name":"Sandra","locale":"en_US"}
Query by first name and use an IP address for localization
{"first_name":"Sandra","ip":"54.201.16.177"}
Query multiple names in a single request
[{"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.