API Docs Unified API v2.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
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
{"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
Query by full name - 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:
Post
Required Requests: 1
URL
https://gender-api.com/v2/gender
Headers
Content-Type: application/json
JSON Payload
Field
Type
Required
Description
full_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 full name only
{"full_name":"Theresa Miller"}
Query by full name and country code
{"full_name":"Theresa Miller","country":"US"}
Query by full name and browser locale
{"full_name":"Thomas Johnson","locale":"en_US"}
Query by full name and use an IP address for localization
{"full_name":"Markus Stefan NonExistingLastName","ip":"54.201.16.177"}
Query multiple names in a single request
[{"full_name":"Theresa Miller"},{"full_name":"Thomas Johnson","country":"US"}]
Response
{
"input": {
"full_name": "Theresa Miller"
},
"details": {
"credits_used": 1,
"duration": "33ms",
"samples": 8961,
"country": null,
"first_name_sanitized": "theresa"
},
"result_found": true,
"last_name": "Miller",
"first_name": "Theresa",
"probability": 0.98,
"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.full_name_sanitized
int
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
full_name
string
The full 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
Query by email address
You can also query a gender using an email address containing a email address:
Post
Required Requests: 1
URL
https://gender-api.com/v2/gender
Headers
Content-Type: application/json
JSON Payload
Field
Type
Required
Description
email
string
Yes
Email address 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 email address only
{"email":"theresa.miller14@gmail.com"}
Query by email address and country code
{"email":"thomas.clarks@hotmail.com","country":"US"}
Query by email address and browser locale
{"email":"Thomas.j32@live.com","locale":"en_US"}
Query by email address and use an IP address for localization
{"email":"thomasfromnewyork@gmail.com","ip":"54.201.16.177"}
Query multiple names in a single request
[{"email":"thomas.clarks@hotmail.com","country":"US"},{"email":"theresa.miller14@gmail.com"}]
Response
{
"input": {
"email": "theresa.miller14@gmail.com"
},
"details": {
"credits_used": 1,
"duration": "12ms",
"samples": 8961,
"country": null,
"first_name_sanitized": "theresa"
},
"result_found": true,
"last_name": "Miller",
"first_name": "Theresa",
"probability": 0.98,
"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.email_sanitized
int
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
email
string
The email address 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
Get Country Of Origin
Get a name's country of origin:
Post
Required Requests: 2
URL
https://gender-api.com/v2/country-of-origin
Headers
Content-Type: application/json
JSON Payload
Field
Type
Required
Description
first_name
string
Yes
First name to query
full_name
string
No
Full name to query. Can be provided instead of the first_name field
email
string
No
Email address to query. Can be provided instead of the first_name field
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
{"first_name":"Johann"}
Query by full name
{"full_name":"Theresa Miller"}
Query by email address
{"full_name":"sophia5342@gmail.com"}
Response
{
"input": {
"first_name": "Johann",
"id": 12
},
"details": {
"credits_used": 2,
"duration": "414ms",
"samples": 890,
"country": null,
"first_name_sanitized": "johann"
},
"result_found": true,
"country_of_origin": [
{
"country_name": "Germany",
"country": "DE",
"probability": 0.52,
"continental_region": "Europe",
"statistical_region": "Western Europe"
},
{
"country_name": "Austria",
"country": "AT",
"probability": 0.48,
"continental_region": "Europe",
"statistical_region": "Western Europe"
}
],
"first_name": "Johann",
"probability": 0.9,
"gender": "male"
}
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
country_of_origin_map_url
string
URL to an interactive map about this 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
country_of_origin
object
Top 25 countries of origin. See "Complete List Of Possible Countries" for a list of supported countries. Every record contains the fields country_name, country, probability, continental_region and statistical_region
Screenshot Interactive Map
Complete List Of Possible Countries
Country Code
Country Name
Statistical Region
Continental Region
CN
China
Eastern Asia
Asia
IN
India
Southern Asia
Asia
US
United States
Northern America
Americas
ID
Indonesia
South-eastern Asia
Asia
BR
Brazil
South America
Americas
PK
Pakistan
Southern Asia
Asia
NG
Nigeria
Western Africa
Africa
BD
Bangladesh
Southern Asia
Asia
RU
Russia
Eastern Europe
Europe
MX
Mexico
Central America
Americas
JP
Japan
Eastern Asia
Asia
ET
Ethiopia
Eastern Africa
Africa
PH
Philippines
South-eastern Asia
Asia
EG
Egypt
Northern Africa
Africa
VN
Vietnam
South-eastern Asia
Asia
DE
Germany
Western Europe
Europe
CD
Democratic Republic of the Congo
Middle Africa
Africa
IR
Iran
Southern Asia
Asia
TR
Turkey
Western Asia
Asia
TH
Thailand
South-eastern Asia
Asia
GB
United Kingdom
Northern Europe
Europe
FR
France
Western Europe
Europe
IT
Italy
Southern Europe
Europe
TZ
Tanzania
Eastern Africa
Africa
ZA
South Africa
Southern Africa
Africa
MM
Myanmar
South-eastern Asia
Asia
KR
South Korea
Eastern Asia
Asia
CO
Colombia
South America
Americas
KE
Kenya
Eastern Africa
Africa
ES
Spain
Southern Europe
Europe
AR
Argentina
South America
Americas
UA
Ukraine
Eastern Europe
Europe
UG
Uganda
Eastern Africa
Africa
DZ
Algeria
Northern Africa
Africa
SD
Sudan
Northern Africa
Africa
IQ
Iraq
Western Asia
Asia
PL
Poland
Eastern Europe
Europe
CA
Canada
Northern America
Americas
MA
Morocco
Northern Africa
Africa
AF
Afghanistan
Southern Asia
Asia
SA
Saudi Arabia
Western Asia
Asia
PE
Peru
South America
Americas
VE
Venezuela
South America
Americas
UZ
Uzbekistan
Central Asia
Asia
MY
Malaysia
South-eastern Asia
Asia
AO
Angola
Middle Africa
Africa
MZ
Mozambique
Eastern Africa
Africa
NP
Nepal
Southern Asia
Asia
GH
Ghana
Western Africa
Africa
YE
Yemen
Western Asia
Asia
MG
Madagascar
Eastern Africa
Africa
KP
North Korea
Eastern Asia
Asia
AU
Australia
AustraliaandNew Zealand
Oceania
CI
Ivory Coast
Western Africa
Africa
CM
Cameroon
Middle Africa
Africa
TW
Taiwan
Eastern Asia
Asia
NE
Niger
Western Africa
Africa
LK
Sri Lanka
Southern Asia
Asia
RO
Romania
Eastern Europe
Europe
BF
Burkina Faso
Western Africa
Africa
MW
Malawi
Eastern Africa
Africa
ML
Mali
Western Africa
Africa
SY
Syria
Western Asia
Asia
KZ
Kazakhstan
Central Asia
Asia
CL
Chile
South America
Americas
ZM
Zambia
Eastern Africa
Africa
NL
Netherlands
Western Europe
Europe
GT
Guatemala
Central America
Americas
EC
Ecuador
South America
Americas
ZW
Zimbabwe
Eastern Africa
Africa
KH
Cambodia
South-eastern Asia
Asia
SN
Senegal
Western Africa
Africa
TD
Chad
Middle Africa
Africa
SO
Somalia
Eastern Africa
Africa
GN
Guinea
Western Africa
Africa
SD
Sudan
Northern Africa
Africa
RW
Rwanda
Eastern Africa
Africa
TN
Tunisia
Northern Africa
Africa
CU
Cuba
Caribbean
Americas
BE
Belgium
Western Europe
Europe
BJ
Benin
Western Africa
Africa
GR
Greece
Southern Europe
Europe
BO
Bolivia
South America
Americas
HT
Haiti
Caribbean
Americas
BI
Burundi
Eastern Africa
Africa
DO
Dominican Republic
Caribbean
Americas
CZ
Czech Republic
Eastern Europe
Europe
PT
Portugal
Southern Europe
Europe
SE
Sweden
Northern Europe
Europe
AZ
Azerbaijan
Western Asia
Asia
HU
Hungary
Eastern Europe
Europe
JO
Jordan
Western Asia
Asia
BY
Belarus
Eastern Europe
Europe
AE
United Arab Emirates
Western Asia
Asia
HN
Honduras
Central America
Americas
TJ
Tajikistan
Central Asia
Asia
RS
Serbia
Southern Europe
Europe
AT
Austria
Western Europe
Europe
CH
Switzerland
Western Europe
Europe
IL
Israel
Western Asia
Asia
PG
Papua New Guinea
Melanesia
Oceania
TG
Togo
Western Africa
Africa
SL
Sierra Leone
Western Africa
Africa
HK
Hong Kong
Eastern Asia
Asia
BG
Bulgaria
Eastern Europe
Europe
LA
Laos
South-eastern Asia
Asia
PY
Paraguay
South America
Americas
SV
El Salvador
Central America
Americas
LY
Libya
Northern Africa
Africa
NI
Nicaragua
Central America
Americas
LB
Lebanon
Western Asia
Asia
KG
Kyrgyzstan
Central Asia
Asia
TM
Turkmenistan
Central Asia
Asia
DK
Denmark
Northern Europe
Europe
SG
Singapore
South-eastern Asia
Asia
FI
Finland
Northern Europe
Europe
SK
Slovakia
Eastern Europe
Europe
NO
Norway
Northern Europe
Europe
CG
Congo
Middle Africa
Africa
ER
Eritrea
Eastern Africa
Africa
PS
Palestine
Western Asia
Asia
CR
Costa Rica
Central America
Americas
IE
Ireland
Northern Europe
Europe
LR
Liberia
Western Africa
Africa
NZ
New Zealand
AustraliaandNew Zealand
Oceania
CF
Central African Republic
Middle Africa
Africa
OM
Oman
Western Asia
Asia
MR
Mauritania
Western Africa
Africa
HR
Croatia
Southern Europe
Europe
KW
Kuwait
Western Asia
Asia
PA
Panama
Central America
Americas
MD
Moldova
Eastern Europe
Europe
GE
Georgia
Western Asia
Asia
PR
Puerto Rico
Caribbean
Americas
BA
Bosnia and Herzegovina
Southern Europe
Europe
UY
Uruguay
South America
Americas
MN
Mongolia
Eastern Asia
Asia
AM
Armenia
Western Asia
Asia
AL
Albania
Southern Europe
Europe
JM
Jamaica
Caribbean
Americas
LT
Lithuania
Northern Europe
Europe
QA
Qatar
Western Asia
Asia
NA
Namibia
Southern Africa
Africa
BW
Botswana
Southern Africa
Africa
LS
Lesotho
Southern Africa
Africa
GM
The Gambia
Western Africa
Africa
MK
Republic of Macedonia
Southern Europe
Europe
SI
Slovenia
Southern Europe
Europe
GA
Gabon
Middle Africa
Africa
LV
Latvia
Northern Europe
Europe
GW
Guinea-Bissau
Western Africa
Africa
BH
Bahrain
Western Asia
Asia
TT
Trinidad and Tobago
Caribbean
Americas
SZ
Swaziland
Southern Africa
Africa
EE
Estonia
Northern Europe
Europe
TL
East Timor
South-eastern Asia
Asia
GQ
Equatorial Guinea
Middle Africa
Africa
MU
Mauritius
Eastern Africa
Africa
CY
Cyprus
Western Asia
Asia
DJ
Djibouti
Eastern Africa
Africa
FJ
Fiji
Melanesia
Oceania
RE
Réunion
Eastern Africa
Africa
KM
Comoros
Eastern Africa
Africa
BT
Bhutan
Southern Asia
Asia
GY
Guyana
South America
Americas
ME
Montenegro
Southern Europe
Europe
MO
Macau
Eastern Asia
Asia
SB
Solomon Islands
Melanesia
Oceania
LU
Luxembourg
Western Europe
Europe
SR
Suriname
South America
Americas
EH
Western Sahara
Northern Africa
Africa
CV
Cape Verde
Western Africa
Africa
GP
Guadeloupe
Caribbean
Americas
MV
Maldives
Southern Asia
Asia
MT
Malta
Southern Europe
Europe
BN
Brunei
South-eastern Asia
Asia
BS
Bahamas
Caribbean
Americas
MQ
Martinique
Caribbean
Americas
BZ
Belize
Central America
Americas
IS
Iceland
Northern Europe
Europe
BB
Barbados
Caribbean
Americas
PF
French Polynesia
Polynesia
Oceania
GF
French Guiana
South America
Americas
NC
New Caledonia
Melanesia
Oceania
VU
Vanuatu
Melanesia
Oceania
YT
Mayotte
Eastern Africa
Africa
ST
Sao Tome and Principe
Middle Africa
Africa
WS
Samoa
Polynesia
Oceania
LC
Saint Lucia
Caribbean
Americas
JE
Guernsey and Jersey
Northern Europe
Europe
GU
Guam
Micronesia
Oceania
CW
Curaçao
Caribbean
Americas
KI
Kiribati
Micronesia
Oceania
VC
Saint Vincent and the Grenadines
Caribbean
Americas
TO
Tonga
Polynesia
Oceania
GD
Grenada
Caribbean
Americas
FM
Federated States of Micronesia
Micronesia
Oceania
AW
Aruba
Caribbean
Americas
VI
United States Virgin Islands
Caribbean
Americas
AG
Antigua and Barbuda
Caribbean
Americas
SC
Seychelles
Eastern Africa
Africa
IM
Isle of Man
Northern Europe
Europe
AD
Andorra
Southern Europe
Europe
DM
Dominica
Caribbean
Americas
KY
Cayman Islands
Caribbean
Americas
BM
Bermuda
Northern America
Americas
GL
Greenland
Northern America
Americas
AS
American Samoa
Polynesia
Oceania
KN
Saint Kitts and Nevis
Caribbean
Americas
MP
Northern Mariana Islands
Micronesia
Oceania
MH
Marshall Islands
Micronesia
Oceania
FO
Faroe Islands
Northern Europe
Europe
SX
Sint Maarten
Caribbean
Americas
MC
Monaco
Western Europe
Europe
LI
Liechtenstein
Western Europe
Europe
TC
Turks and Caicos Islands
Caribbean
Americas
GI
Gibraltar
Southern Europe
Europe
SM
San Marino
Southern Europe
Europe
VG
British Virgin Islands
Caribbean
Americas
BQ
Caribbean Netherlands
Caribbean
Americas
PW
Palau
Micronesia
Oceania
CK
Cook Islands
Polynesia
Oceania
AI
Anguilla
Caribbean
Americas
WF
Wallis and Futuna
Polynesia
Oceania
NR
Nauru
Micronesia
Oceania
TV
Tuvalu
Polynesia
Oceania
PM
Saint Pierre and Miquelon
Northern America
Americas
MS
Montserrat
Caribbean
Americas
SH
Saint Helena Ascension and Tristan da Cunha
Western Africa
Africa
FK
Falkland Islands
South America
Americas
NU
Niue
Polynesia
Oceania
TK
Tokelau
Polynesia
Oceania
VA
Vatican City
Southern Europe
Europe
Get Stats
With this call you can pull some stats on your account:
Get
URL
https://gender-api.com/v2/statistic
Headers
Content-Type: application/json
Response
{
"is_limit_reached": false,
"remaining_credits": 24999,
"details": {
"credits_used": 0,
"duration": "83ms"
},
"usage_last_month": {
"date": "2018-03",
"credits_used": 25
}
}
Field
Type
Description
is_limit_reached
bool
Returns true if there are no more requests left
remaining_credits
int
Number of requests left
details.credits_used
int
The amount of requests used for this query
details.duration
string
Time the server needed to process the request
usage_last_month.date
string
Last month's date
usage_last_month.credits_used
int
Requests that you have used over the last month
Error Codes
Status
endpoint-not-found
HTTP Status Code
404
Description
API endpoint not found
Status
limit-exceeded
HTTP Status Code
401
Description
Limit exceeded. Thank you for using our service. Please consider to buy more requests.
Status
parameter-first-name-invalid
HTTP Status Code
400
Description
The "first_name" parameter is invalid. The parameter can only be a string with a length from 1 to 50 chars.
Status
parameter-full-name-invalid
HTTP Status Code
400
Description
The "full_name" parameter is invalid. The parameter can only be a string with a length from 3 to 100 chars.
Status
parameter-email-invalid
HTTP Status Code
400
Description
The "email" parameter is invalid. The parameter can only be a string with a length from 3 to 100 chars and must be a valid email address.
Status
key-parameter-missing
HTTP Status Code
400
Description
The "key" parameter is not set. Please create an account to fetch an API key.
Status
invalid-key
HTTP Status Code
400
Description
Invalid API key. You can find your personal API key in your account.
Status
invalid-country-code
HTTP Status Code
400
Description
The given country code is not valid. You can find a list of valid country codes in our API docs.
Status
invalid-ip-address
HTTP Status Code
400
Description
The given ip address is not valid. Please provide either a valid IPv4 or an IPv6 address.
Status
generic-error
HTTP Status Code
400
Description
Status
invalid-json
HTTP Status Code
400
Description
Status
invalid-locale
HTTP Status Code
400
Description
The given locale is not valid. You can find a list of valid country codes in our API docs.
Status
invalid-id
HTTP Status Code
400
Description
The given id is not valid. An id can be either an integer or a string with 50 chars at max.
Status
mandatory-parameter-missing
HTTP Status Code
400
Description
Mandatory parameter missing. Either first_name, full_name or email must be set.
Status
content-type-missing
HTTP Status Code
400
Description
Content-Type missing. Please add a "Content-Type: application/json" to your API call.
Status
missing-json
HTTP Status Code
400
Description
We weren't able to find a json body in your API call. Please make sure the body is sent with a POST request to our API endpoint.
Status
too-many-queries
HTTP Status Code
400
Description
Too many queries in a single API call.
Status
too-many-queries-api-key
HTTP Status Code
400
Description
Too many queries in a single API call. Your API key is limited to 3 lookups per request.
Status
authorization-header-missing
HTTP Status Code
400
Description
Your query misses the "Authorization" header with the bearer token.
Status
invalid-auth-token
HTTP Status Code
400
Description
Invalid authentication token provided. Please log in to your account to find a list of valid tokens or to create a new one.
Status
email-invalid
HTTP Status Code
400
Description
Invalid or empty email address given.
Status
password-invalid
HTTP Status Code
400
Description
Invalid credentials. Login failed. Please also check your account that third-party app access is not restricted.: https://gender-api.com/de/account/password
Status
label-invalid
HTTP Status Code
400
Description
Invalid label given. A label must be a string between 2 and 30 chars.
Status
email-account-not-found
HTTP Status Code
400
Description
No Gender-API.com account found. Please create a free account first, to sign-in with Google or try to login with an existing username or password.
Status
invalid-list-of-names
HTTP Status Code
400
Description
Invalid list of names. Expected array of strings.
© Gender-API.com 2023. All rights reserved.
This website uses cookies
To improve our website, to personalize content and adverts, to provide social media features,
and to analyze our traffic, we use cookies. We also share information about your use of our site with our social media,
advertising and analytics partners, who may combine it with other information that you’ve provided to them or that they’ve
collected from you during the use of their services. By continuing to use our site, you consent to the use of cookies on this site..
Cookie declaration last updated on 2022-08-10.
We need your consent
We use cookies (including third-party cookies) to collect information about visitors'
use of our website. These cookies help us to provide you with the best possible online experience and to constantly
improve our websites. Information collected via cookies may also be processed outside the European Union, for example, in the USA.
By clicking the "Accept All" button, you agree to the use of cookies. To withdraw your consent at any time, change your settings or for more information
about the use of cookies, click
here or "Cookie Settings" at the end of the page.