API DOCS

SIMPLE USAGE

This is the easiest way to request a gender determination. Each response is JSON encoded:

Request
GET https://gender-api.com/get?name=Diana&key=<your private server key>
Field Type Description
name String Name to query
key String Your private server key
Response
{"name":"diana","name_sanitized":"Diana","gender":"female","samples":523,"accuracy":93,"duration":"41ms","credits_used":1}
Field Type Description
name String Submitted name in lower case
name_sanitized String The name after we applied our normalizer to it
gender String Possible values: male, female, unknown
samples Integer Number of records found in our database which match your request
accuracy Integer This value determines the reliability of our database. A value of 100 means that the results on your gender request are 100% accurate.
duration String Time the server needed to process the request
credits_used Integer The amount of credits used for this query

LOCALIZATION

Add more accuracy to your request by localizing your query:

Request
Example Italy
GET https://gender-api.com/get?name=Andrea&country=IT&key=<your private server key>
Request
Example Germany
GET https://gender-api.com/get?name=Andrea&country=DE&key=<your private server key>
Field Type Description
name String Name to query
country String ISO 3166 ALPHA-2 Country Code
key String Your private server key
Response
Example Italy
//In Italy, Andrea is male. 
{"name":"andrea","name_sanitized":"Andrea","country":"IT","gender":"male","samples":1068,"accuracy":95,"duration":"15ms","credits_used":1}
Response
Example Germany
//In Germany, Andrea is female. 
{"name":"andrea","name_sanitized":"Andrea","country":"DE","gender":"female","samples":4089,"accuracy":85,"duration":"33ms","credits_used":1}
Field Type Description
name String Submitted name in lower case
name_sanitized String The name after we applied our normalizer to it
country String Submitted country code
gender String Possible values: male, female, unknown
samples Integer Number of records found in our database which match your request
accuracy Integer This value determines the reliability of our database. A value of 100 means that the results on your gender request are 100% accurate.
duration String Time the server needed to process the request
credits_used Integer The amount of credits used for this query

Valid country codes:

AD
Andorra
AE
United Arab Emirates
AF
Afghanistan
AL
Albania
AM
Armenia
AO
Angola
AR
Argentina
AT
Austria
AU
Australia
AZ
Azerbaijan
BA
Bosnia and Herzegovina
BB
Barbados
BD
Bangladesh
BE
Belgium
BF
Burkina Faso
BG
Bulgaria
BH
Bahrain
BI
Burundi
BJ
Benin
BN
Brunei
BO
Bolivia
BR
Brazil
BS
Bahamas
BW
Botswana
BY
Belarus
CA
Canada
CD
Congo - Kinshasa
CG
Congo - Brazzaville
CH
Switzerland
CI
Côte d’Ivoire
CL
Chile
CM
Cameroon
CN
China
CO
Colombia
CR
Costa Rica
CU
Cuba
CV
Cape Verde
CY
Cyprus
CZ
Czech Republic
DE
Germany
DJ
Djibouti
DK
Denmark
DO
Dominican Republic
DZ
Algeria
EC
Ecuador
EE
Estonia
EG
Egypt
ES
Spain
ET
Ethiopia
FI
Finland
FJ
Fiji
FR
France
GA
Gabon
GB
United Kingdom
GE
Georgia
GF
French Guiana
GH
Ghana
GI
Gibraltar
GM
Gambia
GN
Guinea
GP
Guadeloupe
GQ
Equatorial Guinea
GR
Greece
GT
Guatemala
GY
Guyana
HK
Hong Kong SAR China
HN
Honduras
HR
Croatia
HT
Haiti
HU
Hungary
ID
Indonesia
IE
Ireland
IL
Israel
IN
India
IQ
Iraq
IR
Iran
IS
Iceland
IT
Italy
JE
Jersey
JM
Jamaica
JO
Jordan
JP
Japan
KE
Kenya
KG
Kyrgyzstan
KH
Cambodia
KM
Comoros
KR
South Korea
KW
Kuwait
KZ
Kazakhstan
LA
Laos
LB
Lebanon
LK
Sri Lanka
LR
Liberia
LS
Lesotho
LT
Lithuania
LU
Luxembourg
LV
Latvia
LY
Libya
MA
Morocco
MC
Monaco
MD
Moldova
ME
Montenegro
MG
Madagascar
MK
Macedonia
ML
Mali
MM
Myanmar [Burma]
MN
Mongolia
MQ
Martinique
MR
Mauritania
MT
Malta
MU
Mauritius
MV
Maldives
MW
Malawi
MX
Mexico
MY
Malaysia
MZ
Mozambique
NA
Namibia
NC
New Caledonia
NE
Niger
NG
Nigeria
NI
Nicaragua
NL
Netherlands
NO
Norway
NP
Nepal
NZ
New Zealand
OM
Oman
PA
Panama
PE
Peru
PF
French Polynesia
PG
Papua New Guinea
PH
Philippines
PK
Pakistan
PL
Poland
PR
Puerto Rico
PS
Palestinian Territories
PT
Portugal
PY
Paraguay
QA
Qatar
RE
Réunion
RO
Romania
RS
Serbia
RU
Russia
RW
Rwanda
SA
Saudi Arabia
SC
Seychelles
SD
Sudan
SE
Sweden
SG
Singapore
SH
Saint Helena
SI
Slovenia
SK
Slovakia
SL
Sierra Leone
SN
Senegal
SO
Somalia
SV
El Salvador
SY
Syria
SZ
Swaziland
TD
Chad
TG
Togo
TH
Thailand
TJ
Tajikistan
TM
Turkmenistan
TN
Tunisia
TR
Turkey
TT
Trinidad and Tobago
TW
Taiwan
TZ
Tanzania
UA
Ukraine
UG
Uganda
US
United States
UY
Uruguay
UZ
Uzbekistan
VE
Venezuela
VN
Vietnam
YE
Yemen
ZA
South Africa
ZM
Zambia
ZW
Zimbabwe

LOCALIZATION - COUNTRY BY IP

Choose the country of your customer based on their IP address:

Request
Example with a US IP address
GET https://gender-api.com/get?name=john&ip=54.201.16.177&key=<your private server key>
Request
Example with a German IP address
GET https://gender-api.com/get?name=tanja&ip=178.27.177.23&key=<your private server key>
Field Type Description
name String Name to query
ip String Valid IP address
key String Your private server key
Response
Example with a US IP address
{"name":"john","name_sanitized":"John","country":"US","gender":"male","samples":9991,"accuracy":99,"duration":"44ms","credits_used":1}
Response
Example with a German IP address
{"name":"tanja","name_sanitized":"Tanja","country":"DE","gender":"female","samples":143,"accuracy":97,"duration":"508ms","credits_used":1}
Field Type Description
name String Submitted name in lower case
name_sanitized String The name after we applied our normalizer to it
country String Submitted country code
gender String Possible values: male, female, unknown
samples Integer Number of records found in our database which match your request
accuracy Integer This value determines the reliability of our database. A value of 100 means that the results on your gender request are 100% accurate.
duration String Time the server needed to process the request
credits_used Integer The amount of credits used for this query

Gender-API.com includes GeoLite2 data created by MaxMind, available from http://www.maxmind.com.

LOCALIZATION - COUNTRY BY BROWSER LANGUAGE / LOCALE

Choose the country of your customer based on their browser locale:

Request
Example with a US locale
GET https://gender-api.com/get?name=john&locale=en_US&key=<your private server key>
Request
Example with a German locale
GET https://gender-api.com/get?name=tanja&locale=de_DE&key=<your private server key>
Field Type Description
name String Name to query
locale String Browser locale
key String Your private server key
Response
Example with a US locale
{"name":"john","name_sanitized":"John","country":"US","gender":"male","samples":991,"accuracy":99,"duration":"47ms","credits_used":1}
Response
Example with a German locale
{"name":"tanja","name_sanitized":"Tanja","country":"DE","gender":"female","samples":143,"accuracy":97,"duration":"99ms","credits_used":1}
Field Type Description
name String Submitted name in lower case
name_sanitized String The name after we applied our normalizer to it
country String Submitted country code
gender String Possible values: male, female, unknown
samples Integer Number of records found in our database which match your request
accuracy Integer This value determines the reliability of our database. A value of 100 means that the results on your gender request are 100% accurate.
duration String Time the server needed to process the request
credits_used Integer The amount of credits used for this query

Gender-API.com includes GeoLite2 data created by MaxMind, available from http://www.maxmind.com.

QUERY MULTIPLE NAMES

Sometimes it is necessary to fetch multiple names with one query:

Request
Without country code
GET https://gender-api.com/get?name=lisa;jess;thomas&key=<your private server key>
Request
With country code
GET https://gender-api.com/get?name=anna;jack;stephen&country=DE;US;CA&key=<your private server key>
Field Type Description
name String Comma separated list of names to query
country String Comma separated list of country codes
key String Your private server key
Response
Without country code
{"name":"lisa;jess;thomas","result":[
{"name":"lisa","name_sanitized":"Lisa","country":"","gender":"female","samples":806,"accuracy":98},
{"name":"jess","name_sanitized":"Jess","country":"","gender":"female","samples":28,"accuracy":75},
{"name":"thomas","name_sanitized":"Thomas","country":"","gender":"male","samples":2239,"accuracy":99}],
"country":"","duration":"425ms","credits_used":3}
Response
With country code
{"name":"anna;jack;stephen","result":[
{"name":"anna","name_sanitized":"Anna","country":"DE","gender":"female","samples":1245,"accuracy":98},
{"name":"jack","name_sanitized":"Jack","country":"US","gender":"male","samples":667,"accuracy":90},
{"name":"stephen","name_sanitized":"Stephen","country":"CA","gender":"male","samples":77,"accuracy":82}],
"country":"DE;US;CA","duration":"668ms","credits_used":3}
Field Type Description
name String Submitted names in lower case. The maximum number of names is limited to 100.
result Array See response under "Simple Usage"
country String Submitted list of country codes
duration String Time the server needed to process the request
credits_used Integer The amount of credits used for this query

Please note: If multiple names are requested in one query, each name will be counted as a single request.

EMAIL ADDRESS

You can also query a gender using an email address containing a first name:

Request
Without country code
GET https://gender-api.com/get?email=markus.johnson@gmail.com&key=<your private server key>
Request
With country code
GET https://gender-api.com/get?email=jack.meyer@gmail.com&country=US&key=<your private server key>
Field Type Description
name String Name to query
email String Email address
key String Your private server key
Response
Without country code
{"email":"markus.johnson@gmail.com","last_name":"Johnson","first_name":"Markus","mail_provider":"gmail","name":"markus","name_sanitized":"Markus","country":"","gender":"male","samples":150,"accuracy":99,"duration":"669ms","credits_used":1}
Response
With country code
{"email":"jack.meyer@gmail.com","last_name":"Meyer","first_name":"Jack","mail_provider":"gmail","name":"jack","name_sanitized":"Jack","country":"US","gender":"male","samples":667,"accuracy":90,"duration":"1011ms","credits_used":1}
Field Type Description
email String The submitted email address
last_name String The last name found
first_name String The first name found
mail_provider String Name of the email provider
name String First Name found in lowercase
name_sanitized String The name after we applied our normalizer to it
country String Submitted country code
gender String Possible values: male, female, unknown
samples Integer Number of records found in our database which match your request
accuracy Integer This value determines the reliability of our database. A value of 100 means that the results on your gender request are 100% accurate.
duration String Time the server needed to process the request
credits_used Integer The amount of credits used for this query

SPLIT FIRST AND LAST NAME

If you use a combined field for first and last name on your page, use this api to extract the parts:

Request
Without country code
GET https://gender-api.com/get?split=theresa%20miller&key=<your private server key>
Request
With country code
GET https://gender-api.com/get?split=tim%20johnson&country=US&key=<your private server key>
Request
Strict mode on
GET https://gender-api.com/get?split=markus%20stefan%20nonExistingLastName&strict=1&key=<your private server key>
Field Type Description
split String Full name
country String ISO 3166 ALPHA-2 Country Code
strict Boolean (1|0) When the strict mode is enabled, we will return null in the last_name field if the last_name cannot be found in our database. When the strict mode is disabled, we will try to extract the last name even if it cannot be found in our database
key String Your private server key
Response
Without country code
{"last_name":"Miller","first_name":"Theresa","strict":false,"name":"theresa","name_sanitized":"Theresa","country":"","gender":"female","samples":70,"accuracy":74,"duration":"56ms","credits_used":1}
Response
With country code
{"last_name":"Johnson","first_name":"Tim","strict":false,"name":"tim","name_sanitized":"Tim","country":"US","gender":"male","samples":7,"accuracy":100,"duration":"58ms","credits_used":1}
Response
Strict mode on
{"last_name":"","first_name":"Markus Stefan","strict":true,"name":"markus","name_sanitized":"Markus","country":"","gender":"male","samples":150,"accuracy":99,"duration":"85ms","credits_used":1}
Field Type Description
last_name String The last name found
first_name String The first name found
strict Boolean True if the strict mode is enabled
name String First Name found in lowercase
name_sanitized String The name after we applied our normalizer to it
country String Submitted country code
gender String Possible values: male, female, unknown
samples Integer Number of records found in our database which match your request
accuracy Integer This value determines the reliability of our database. A value of 100 means that the results on your gender request are 100% accurate.
duration String Time the server needed to process the request
credits_used Integer The amount of credits used for this query

Please indicate your customers enter their names in the form "First Name, Last Name", which makes our response more accurate.

GET STATS

With this call you can pull some stats on your account:

Request
GET https://gender-api.com/get-stats?&key=<your private server key>
Field Type Description
key String Your private server key
Response
{"key":"yourkey","is_limit_reached":false,"remaining_requests":43566,"amount_month_start":90000,"amount_month_bought":100000,"duration":"37ms"}
Field Type Description
key String Your private server key
is_limit_reached Boolean Returns true if there are no more requests left
remaining_requests Integer Counts remaining requests
amount_month_start Integer Requests left at the beginning of the month
amount_month_bought Integer Requests bought this month
duration String Time the server needed to process the request

ERROR CODES

Response
Error Example Message
{"errno":30,"errmsg":"limit reached"}
errno (Error Number) errmsg (Error Message) Description
10 invalid country code See "Valid country codes"
11 number of country codes not equal to number of names The name count does not match the count of country codes
20 name not set No name was received by the server
21 too many names Only 100 names allowed at once
30 limit reached Query limit reached
40 invalid or missing key Your server key was not found in our database
500 unknown error Internal server error
This product includes GeoLite2 data created by MaxMind, available from http://www.maxmind.com.
We use cookies to ensure that we give you the best experience on our website. If you continue to use this site we will assume that you are happy with it.
Got it