FREQUENTLY ASKED QUESTIONS

WHAT ABOUT THE NEW GENERAL DATA PROTECTION REGULATION (GDPR)?

The new European General Data Protection Regulation (GDPR) goes into effect on May 25, 2018. We can assure you that all Gender-API.com services will be in full compliance with GDPR by this date. We provide a Data Processing Agreement (DPA), which enables you to comply with your GDPR obligations. You can request this agreement here in your account. A sample agreement can be downloaded here.

WHAT HAPPENS IF A NAME CAN BE MALE AS WELL AS FEMALE?

If you can provide a country code or specific territory in your query, we can guarantee a significant improve in detecting the right gender. For example: While Andrea is male in Italy, Andrea is a female name in Germany and can even be both in the US. In this case, we provide an accuracy value in the query result, ranging between 0 and 100. It tells you how certain we are in having detected the right gender. If you think the value is too low, you can still ask your user to provide the right gender themselves. In most countries, however, we can determine the correct gender in over 94% of cases.

HOW DO YOU GATHER THE DATA?

To provide the highest possible accuracy, we combine the data of multiple data sources. We use data from publicly available governmental sources and combine them with data we crawl from social networks, which provides you the best possible matches. Each name has to be verified by different sources to be added to our list.

HOW MANY NAMES DO YOU HAVE STORED IN YOUR DATABASE?

Our database contains 1,877,786 validated names from 178 different countries. All over the world we store 811,429 unique names. On an average we analyze about 10,000,000 datasets per month to improve the quality of our results.

WHICH COUNTRIES ARE SUPPORTED?

The API fully supports 178 countries. Full support means that we collected at least 300 names in this respective country. However, in most countries our dataset is much larger. Take a look at the following table to learn more about how many names we support in which country. Keep in mind that if we do not provide a suitable support for a country ourselves, you can still crawl the requested names against the entire dataset to get an adequate result.

1.
Afghanistan
2,163
2.
Albania
6,429
3.
Algeria
24,724
4.
Andorra
768
5.
Angola
8,546
6.
Argentina
11,051
7.
Armenia
1,627
8.
Aruba
139
9.
Australia
10,251
10.
Austria
11,300
11.
Azerbaijan
5,094
12.
Bahamas
545
13.
Bahrain
4,388
14.
Bangladesh
11,308
15.
Barbados
435
16.
Belarus
3,377
17.
Belgium
29,455
18.
Belize
302
19.
Benin
4,763
20.
Bermuda
119
21.
Bhutan
179
22.
Bolivia
1,728
23.
Bosnia and Herzegovina
4,039
24.
Botswana
2,330
25.
Brazil
55,485
26.
Brunei
580
27.
Bulgaria
5,228
28.
Burkina Faso
3,319
29.
Burundi
844
30.
Cambodia
2,289
31.
Cameroon
9,458
32.
Canada
16,196
33.
Cape Verde
1,855
34.
Central African Republic
128
35.
Chad
423
36.
Chile
6,677
37.
China
26,660
38.
Colombia
15,060
39.
Comoros
459
40.
Congo - Brazzaville
4,400
41.
Congo - Kinshasa
1,288
42.
Costa Rica
2,582
43.
Croatia
3,395
44.
Cuba
1,343
45.
Cyprus
4,144
46.
Czech Republic
16,529
47.
Côte d’Ivoire
15,617
48.
Denmark
7,043
49.
Djibouti
1,624
50.
Dominican Republic
4,221
51.
Ecuador
4,745
52.
Egypt
15,926
53.
El Salvador
3,156
54.
Equatorial Guinea
754
55.
Estonia
2,411
56.
Ethiopia
3,680
57.
Faroe Islands
134
58.
Fiji
943
59.
Finland
5,424
60.
France
122,717
61.
French Guiana
898
62.
French Polynesia
353
63.
Gabon
2,955
64.
Gambia
1,015
65.
Georgia
1,670
66.
Germany
54,475
67.
Ghana
9,225
68.
Gibraltar
422
69.
Greece
13,358
70.
Greenland
179
71.
Grenada
133
72.
Guadeloupe
724
73.
Guam
314
74.
Guatemala
2,445
75.
Guernsey
170
76.
Guinea
1,160
77.
Guinea-Bissau
115
78.
Guyana
345
79.
Haiti
872
80.
Honduras
1,658
81.
Hong Kong SAR China
6,698
82.
Hungary
11,663
83.
Iceland
1,633
84.
India
95,051
85.
Indonesia
63,041
86.
Iran
10,020
87.
Iraq
9,648
88.
Ireland
7,100
89.
Isle of Man
169
90.
Israel
9,606
91.
Italy
69,854
92.
Jamaica
1,690
93.
Japan
24,067
94.
Jersey
468
95.
Jordan
5,842
96.
Kazakhstan
4,515
97.
Kenya
9,899
98.
Kuwait
10,638
99.
Kyrgyzstan
1,511
100.
Laos
804
101.
Latvia
2,203
102.
Lebanon
8,752
103.
Lesotho
594
104.
Liberia
735
105.
Libya
2,658
106.
Liechtenstein
183
107.
Lithuania
2,680
108.
Luxembourg
2,860
109.
Macedonia
3,784
110.
Madagascar
3,347
111.
Malawi
1,200
112.
Malaysia
25,983
113.
Maldives
812
114.
Mali
3,282
115.
Malta
2,353
116.
Martinique
626
117.
Mauritania
996
118.
Mauritius
4,266
119.
Mayotte
248
120.
Mexico
19,691
121.
Micronesia
167
122.
Moldova
2,164
123.
Monaco
571
124.
Mongolia
769
125.
Montenegro
1,068
126.
Morocco
30,875
127.
Mozambique
5,093
128.
Myanmar [Burma]
4,252
129.
Namibia
2,325
130.
Nepal
3,549
131.
Netherlands
35,917
132.
New Caledonia
352
133.
New Zealand
3,721
134.
Nicaragua
1,478
135.
Niger
1,303
136.
Nigeria
51,405
137.
Norway
7,732
138.
Oman
7,259
139.
Pakistan
13,957
140.
Palestinian Territories
2,552
141.
Panama
2,069
142.
Papua New Guinea
830
143.
Paraguay
1,452
144.
Peru
8,390
145.
Philippines
20,712
146.
Poland
14,368
147.
Portugal
25,293
148.
Puerto Rico
2,717
149.
Qatar
5,984
150.
Romania
16,998
151.
Russia
30,111
152.
Rwanda
2,361
153.
Réunion
3,711
154.
Saint Helena
1,340
155.
Saint Lucia
293
156.
San Marino
307
157.
Saudi Arabia
38,373
158.
Senegal
10,112
159.
Serbia
7,438
160.
Seychelles
507
161.
Sierra Leone
753
162.
Singapore
11,001
163.
Slovakia
5,813
164.
Slovenia
3,241
165.
Solomon Islands
131
166.
Somalia
721
167.
South Africa
30,545
168.
South Korea
29,708
169.
Spain
161,432
170.
Sri Lanka
7,035
171.
Sudan
4,365
172.
Suriname
332
173.
Swaziland
493
174.
Sweden
17,666
175.
Switzerland
22,895
176.
Syria
4,168
177.
São Tomé and Príncipe
212
178.
Taiwan
19,099
179.
Tajikistan
685
180.
Tanzania
4,953
181.
Thailand
54,192
182.
Timor-Leste
204
183.
Togo
3,442
184.
Trinidad and Tobago
1,163
185.
Tunisia
14,407
186.
Turkey
64,496
187.
Turkmenistan
542
188.
U.S. Virgin Islands
250
189.
Uganda
6,416
190.
Ukraine
11,584
191.
United Arab Emirates
14,519
192.
United Kingdom
61,246
193.
United States
97,486
194.
Uruguay
1,810
195.
Uzbekistan
2,070
196.
Venezuela
10,086
197.
Vietnam
18,575
198.
Western Sahara
197
199.
Yemen
3,744
200.
Zambia
2,200
201.
Zimbabwe
2,894

I HEARD ABOUT YOUR EMAIL API. WHAT EXACTLY IS THIS?

Our email API can extract names from email addresses and provide the appropriate gender to this respective address. This can help you to personalize your emailings with a proper salutation. For example, from the email address "marie.johnson@gmail.com", API will extract the name "Marie" and determine the correct gender, which is "female". For details please take a look at our API Docs.

I HAVE A HUGE AMOUNT OF DATA. CAN I BULK UPLOAD A CSV FILE?

As a registered user you can upload any CSV file containing a first name column. For a better determination result, you can optionally add a country column to your dataset. While it is not necessary to specifically name the columns, our assistant guides you through the process by letting you choose which column contains which token, first name or country included. The feature is located within your account. Processed records will be charged like requests so that you can upload a CSV file with up to 500 entries for free every month. The CSV bulk upload requires a Gender-API.com account.

HOW IS THE CSV FILE TO BE FORMATTED?

We support CSV files created on Windows, Mac OSX or Linux. In addition, we support files with delimiters like ";", "," or a tab. The enclosure char must be a ". Furthermore, you can upload multi-line CSV files with a maximum of 10,000,000 rows and 200MB. To achieve the best results possible, we however recommend using a UTF-8 formatted CSV file with semicolon as delimiter. Otherwise, the CSV file can contain further, arbitrary rows which will also be included in the output file. The file must contain at least one column with first names only. Click here to download a sample file. Please create a Gender-API.com account to upload a CSV file.

CAN I UPLOAD AN EXCEL FILE?

You can upload Excel files with up to 200,000 rows. For larger datasets, please use our CSV file upload. We support .xlsx files with a single sheet. If you upload a file with more than one sheet, only the first will be processed. The first row in your sheet must contain the column names. The file must contain at least one column with first names, the country column is optional. Download sample file here. Example:
Excel Example

DO YOU PROVIDE ANY LIBRARIES FOR PROGRAMMING LANGUAGES?

Due to the simplicity of our API, we do not provide a lib for any programming language, except the jQuery Plugin. Most languages support a json parser out-of-the-box and for almost every other language, there is already an external lib you can use. Take a look at our coding examples to get started with using the API:

First install our library with composer:

$ composer require gender-api/client
use GenderApi\Client as GenderApiClient;

try {
    $apiClient = new GenderApiClient('insert your API key');

    // Query a single name
    $lookup = $apiClient->getByFirstName('elisabeth');
    if ($lookup->genderFound()) {
        echo $lookup->getGender();      // female
    }

    // Query a full name and improve the result by providing a country code
    $lookup = $apiClient->getByFirstNameAndLastNameAndCountry('Thomas Johnson', 'US');
    if ($lookup->genderFound()) {
        echo $lookup->getGender();      // male
        echo $lookup->getFirstName();   // Thomas
        echo $lookup->getLastName();    // Johnson
    }

} catch (GenderApi\Exception $e) {
    // Name lookup failed due to a network error or insufficient requests
    // left. See https://gender-api.com/en/api-docs/error-codes
    echo 'Exception: ' . $e->getMessage();
}

See full client documentation here:

https://github.com/markus-perl/gender-api-client

function getGender($firstname) {
    $myKey = 'insert your server key here';
    $data = json_decode(file_get_contents(
        'https://gender-api.com/get?key=' . $myKey .
        '&name=' . urlencode($firstname)));
    return $data->gender;
}

echo getGender('markus'); //Output: male

First install our library with npm:

$ npm i gender-api.com-client --save
import {Client as GenderApiClient, ResultSingleName} from "gender-api.com-client";

const genderApiClient = new GenderApiClient("your API key");

try {
    genderApiClient.getByFirstName('theresa', (response: ResultSingleName) => {
      console.log(response.gender); //female
      console.log(response.accuracy); //98
    });
  
    genderApiClient.getByFirstNameAndCountry('john', 'US', (response: ResultSingleName) => {
      console.log(response.gender); //male
      console.log(response.accuracy); //99
    });
}
catch(e) {
  console.log('Error:', e);
}

See full client documentation here:

https://github.com/markus-perl/gender-api-client-npm

First install our library with npm:

$ npm i gender-api.com-client --save
try {
    var GenderApi = require('gender-api.com-client');

    var genderApiClient = new GenderApi.Client('your api key');

    genderApiClient.getByFirstName('theresa', function (response) {
        console.log(response.gender); //female
        console.log(response.accuracy); //98
    });

    genderApiClient.getByFirstNameAndCountry('john', 'US', function (response) {
        console.log(response.gender); //male
        console.log(response.accuracy); //99
    });

}
catch(e) {
    console.log('Error:', e);
}

See full client documentation here:

https://github.com/markus-perl/gender-api-client-npm

Python 3.*
import json

from urllib.request import urlopen

myKey = "insert your server key here"
url = "https://gender-api.com/get?key=" + myKey + "&name=kevin"
response = urlopen(url)
decoded = response.read().decode('utf-8')
data = json.loads(decoded)
print( "Gender: " + data["gender"]); #Gender: male

Python 2.*
import json
import urllib2

myKey = "insert your servery key here"
data = json.load(urllib2.urlopen("https://gender-api.com/get?key=" + myKey + "&name=markus"))
print "Gender: " + data["gender"]; #Gender: male
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import com.google.gson.Gson;
import com.google.gson.JsonObject;

public class Main {

  public static void main(String[] args) {

  try {

    String myKey = "insert your server key here";
    URL url = new URL("https://gender-api.com/get?key=" + myKey + "&name=markus");
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();

    if (conn.getResponseCode() != 200) {
      throw new RuntimeException("Error: " + conn.getResponseCode());
    }

    InputStreamReader input = new InputStreamReader(conn.getInputStream());
    BufferedReader reader = new BufferedReader(input);

    Gson gson = new Gson();
    JsonObject json = gson.fromJson(reader, JsonObject.class);
    String gender = json.get("gender").getAsString();
    System.out.println("Gender: " + gender); // Gender: male
    conn.disconnect();

    } catch (IOException e) {
      e.printStackTrace();
    }
  }
}

HOW DO REQUESTS GET COUNTED?

Every account will be recharged to 500 credits on the first day of every month if there are less than this number of credits left. Only if a result is found, the request will be counted. One credit will be charged for each request. If multiple names are requested in one query, each name will be counted as a single request.

HOW CAN I BUY MORE REQUESTS?

You can choose between either a subscription plan or one-time-payment. One-time-payment is recommended, if you want to process a large CSV file or if you prefer to use your requests on a irregular basis. You can charge your account with the required amount of requests at any time. Requests bought with one-time-payment can be used within one year. If you prefer to sign up for a subscription plan, your account will be refilled to the selected amount of requests every month. Subscriptions can be changed or canceled at any time.

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