API DOCS

SIMPLE USAGE

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

GET https://gender-api.com/get?name=Diana

The request will be returned as:

{"name":"diana","gender":"female","samples":36,"accuracy":100,"duration":"41ms"}

Let's have a look at the generated response:

Key Datatype Description
name String Submitted name
gender String Possible values: male, female
samples Integer Number of records found in our database which are matching your request.
accuracy String 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 that took the server to process the request.

LOCALIZATION

Add more accuracy to your request by localizing your query:

GET https://gender-api.com/get?name=Andrea&country=IT
GET https://gender-api.com/get?name=Andrea&country=DE

These requests will be returned as:

{"name":"andrea","gender":"male","country":"IT","samples":160,"accuracy":97,"duration":"29ms"} //In Italy, Andrea is male.
{"name":"andrea","gender":"female","country":"DE","samples":19,"accuracy":95,"duration":"31ms"} //In Germany, Andrea is female.
Key Datatype Description
country String Submitted country code

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
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
GM
Gambia
GN
Guinea
GP
Guadeloupe
GR
Greece
GT
Guatemala
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
JM
Jamaica
JO
Jordan
JP
Japan
KE
Kenya
KG
Kyrgyzstan
KH
Cambodia
KR
South Korea
KW
Kuwait
KZ
Kazakhstan
LA
Laos
LB
Lebanon
LK
Sri Lanka
LR
Liberia
LT
Lithuania
LU
Luxembourg
LV
Latvia
LY
Libya
MA
Morocco
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
NE
Niger
NG
Nigeria
NI
Nicaragua
NL
Netherlands
NO
Norway
NP
Nepal
NZ
New Zealand
OM
Oman
PA
Panama
PE
Peru
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
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
TG
Togo
TH
Thailand
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 his IP address:

GET https://gender-api.com/get?name=john&ip=54.201.16.177
GET https://gender-api.com/get?name=tanja&ip=178.27.177.23
GET https://gender-api.com/get?name=thomas&ip=auto

These requests will be returned as:

{"name":"John","country":"US","gender":"male","samples":4,"accuracy":100,"duration":"38ms"} //Country: US
{"name":"Tanja","country":"DE","gender":"female","samples":10,"accuracy":100,"duration":"36ms"} //Country: Germany.
{"name":"Thomas","country":"DE","gender":"male","samples":13,"accuracy":100,"duration":"39ms"} //Country: Based on the browser IP. Can only be used by the Javascript API.

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 his browser locale:

GET https://gender-api.com/get?name=john&language=en-US
GET https://gender-api.com/get?name=tanja&language=de-DE
GET https://gender-api.com/get?name=thomas&language=auto

These requests will be returned as:

{"name":"John","country":"US","gender":"male","samples":4,"accuracy":100,"duration":"38ms"} //Country: US
{"name":"Tanja","country":"DE","gender":"female","samples":10,"accuracy":100,"duration":"36ms"} //Country: Germany.
{"name":"Thomas","country":"DE","gender":"male","samples":13,"accuracy":100,"duration":"39ms"} //Country: Based on the browser language. Can only be used by the Javascript API.

ADVANCED USAGE

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

GET https://gender-api.com/get?name=Anna;Jack;Stephen

The request will be returned as:

{"name":"Anna;Jack;Stephen","result":[
            {"name":"Anna","gender":"female","samples":211,"accuracy":97},
            {"name":"Jack","gender":"male","samples":105,"accuracy":100},
            {"name":"Stephen","gender":"male","samples":48,"accuracy":100}
            ],"duration":"42ms"}

Let's have a look at the generated response:

Key Datatype Description
name String Submitted names. The maximum number of names is limited to 100.
result Array See generated response under "Simple Usage".
duration String Time that took the server to process the request.

E-MAIL ADDRESS

You can also query a gender by an email address which contains a first name:

GET https://gender-api.com/get?email=markus.p@gmail.com
GET https://gender-api.com/get?email=jack@gmail.com&country=US

The request will be returned as:

{"email":"markus.p@gmail.com","name":"markus","gender":"male","samples":150,"accuracy":99,"duration":"44ms"}
{"email":"jack@gmail.com","name":"jack","country":"US","gender":"male","samples":6,"accuracy":67,"duration":"49ms"}

Let's have a look at the generated response:

Key Datatype Description
email String The submitted e-mail address
name String The name found in the address
gender String Possible values: male, female
samples Integer Number of records found in our database which are matching your request.
accuracy String 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 that took the server to process the request.

ERROR CODES

errno errmsg Description
10 invalid country code See "Valid country codes"
20 name not set No name was received by the server
21 too many names Only 100 names at once allowed
30 limit reached query limit reached
500 unknown error Internal server error