FREQUENTLY ASKED QUESTIONS

What happens if a name can be male as well as female?
Can there be differences for the same name per country?
How do you gather the data?
How often do you update name records?
Do you provide any help to implement the API?
What if we need a high level of accuracy?
How many names do you have stored in your database?
Which countries are supported?
Do you support arabic names?
Can I query multiple names in one request?
I heard about your email API. What exactly is it?
I have a huge amount of data. Can I bulk upload a CSV file?
How needs the CSV file to be formatted?
Can I upload an Excel file?
I found a bug. What am I supposed to do?
Is Gender-API compliant with the General Data Protection Regulation (GDPR)?
Do you provide any libraries for programming languages?
How do requests get counted?
Where can I find and manage my API keys?
Can I share my account with multiple people?
Can I protect my account by enabling two-step verification?
Can I use third party apps when two-step-verification is enabled?
What is the difference between a paid and a free account?
What is the difference between a subscription and a one-time payment?
I need a certificate of residence. Can you issue such a certificate?
How can I buy a package / more requests?
How can I cancel my subscription?

WHAT HAPPENS IF A NAME CAN BE MALE AS WELL AS FEMALE?
Depending on your API version or the integration you're using, our endpoints will either return an accuracy or a probability value in the response. The accuracy parameter returns how sure we are that this name is either male or female. The value is calculated by the number of records in our database. For example, if we have 100 samples of a name, 96 are female, and 4 are male, the accuracy is 96% (or a .96 probability). A low accuracy indicates that this name is probably used by multiple genders and cannot be conjugated to a specific gender.

CAN THERE BE DIFFERENCES FOR THE SAME NAME PER COUNTRY?
While the name 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 (or a probability value between 0 and 1). It tells you how certain we are in having detected the correct gender. You can significantly increase the API's result quality by providing some geographical information about your query. This can either be a country code, the browser's locale, or an IP address. You can learn more about localizing a query in our API docs.

HOW DO YOU GATHER THE DATA?
To provide the highest possible accuracy, we combine data from multiple sources. The main sources for new records are publicly available data, governmental data and manual additions/corrections. Based on the source of a new name, the name may have to be verified by a second source before it is added to our list. For example, if we add a name from publicly available data, this name may need a second verification, like a manual confirmation, before it is finally added to our database. You can find a list of supported countries here.

HOW OFTEN DO YOU UPDATE NAME RECORDS?
We regularly update our data depending on the country and the available public data. Most western countries are updated once a year. Also, the distribution of names across genders may change over the years. For example, if a name was used exclusively by women in the 1970s, it may be used predominantly by male people decades later. That's why we also use birth data for several countries, such as the US, to enrich the results. Our models try to take all these factors into account as well as possible. The returned accuracy value is regularly adjusted to reflect the actual usage in the population as accurate as possible. The value is supposed to provide a reasonable evaluation based on the last decades and may expresses a possible fluctuation. We do look at about the last 4 decades of the data. If you run a query and repeat the same query a year later, you may get a different result because our system might have dropped old data, and new data might have been added. Every time new data is added, we perform so-called integration tests afterward. In this process, our API is tested against a previously validated data set to ensure quality. This data set is continuously expanded with names and test cases to achieve the broadest coverage possible.

DO YOU PROVIDE ANY HELP TO IMPLEMENT THE API?
Yes, we provide email support for all customers. You can email us to contact gender-api.com. We will then get back to you as soon as possible. You can also find coding examples here. Please note that we cannot help you with every programming language and use case. In most cases, you can use a standard rest client in your app to query our API. Many libraries also support the import of an OpenAPI definition file. You can download our openapi.yml definition file here.

WHAT IF WE NEED A HIGH LEVEL OF ACCURACY?
Languages and names are fluid and change over time. From customer to customer, data sets also vary a lot in quality, scope and origin. Therefore, we cannot guarantee that all results you receive from our API are 100% correct and match your data pool. But we can promise that we are always committed to providing you with the best results possible and that we regularly improve and update our algorithms. We also add new data on a very regular basis. You can find out more about our updates here. In the unlikely event of our service not matching up with your expectations, we give you a straightforward 14-day money-back guarantee. Of course, we also offer to test our service completely free of charge. If you sign up here, you will receive 100 requests for free every month. If you query a name, our endpoints will either return an accuracy or a probability value in the response, depending on your API version. The accuracy parameter returns how sure we are that this name is either male or female. The value is calculated by the number of records for this in our database. Since use cases differ significantly, we do not give any recommendations on the level of accuracy. Depending on your use case, it is up to you to decide what results and accuracy levels to accept. Even with an accuracy of at least 99%, there is a possibility that the result is incorrect. However, a value above 95% fits most use cases in general.

HOW MANY NAMES DO YOU HAVE STORED IN YOUR DATABASE?
Our database contains 6,084,389 validated names from 191 different countries. All over the world we store 6,195,008 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 191 countries. Full support means that we collected at least 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.
Andorra
1,342
2.
United Arab Emirates
24,000
3.
Afghanistan
3,657
4.
Albania
9,928
5.
Armenia
2,560
6.
Angola
17,608
7.
Argentina
18,725
8.
Austria
18,058
9.
Australia
16,329
10.
Azerbaijan
7,973
11.
Bosnia and Herzegovina
6,282
12.
Barbados
689
13.
Bangladesh
18,448
14.
Belgium
48,156
15.
Burkina Faso
5,373
16.
Bulgaria
7,938
17.
Bahrain
7,563
18.
Burundi
1,316
19.
Benin
8,416
20.
Brunei
1,201
21.
Bolivia
2,965
22.
Brazil
93,465
23.
Bahamas
971
24.
Botswana
3,981
25.
Belarus
5,455
26.
Belize
585
27.
Canada
26,187
28.
Congo - Kinshasa
2,119
29.
Congo - Brazzaville
7,835
30.
Switzerland
37,788
31.
Côte d’Ivoire
29,601
32.
Chile
11,353
33.
Cameroon
17,532
34.
China
46,378
35.
Colombia
25,550
36.
Costa Rica
4,055
37.
Cuba
2,354
38.
Cape Verde
3,251
39.
Cyprus
6,631
40.
Czech Republic
28,020
41.
Germany
92,526
42.
Djibouti
2,956
43.
Denmark
12,322
44.
Dominican Republic
7,348
45.
Algeria
41,590
46.
Ecuador
8,125
47.
Estonia
3,570
48.
Egypt
26,773
49.
Western Sahara
403
50.
Spain
300,734
51.
Ethiopia
5,964
52.
Finland
8,663
53.
Fiji
1,564
54.
Micronesia
396
55.
France
208,218
56.
Gabon
5,275
57.
United Kingdom
105,368
58.
Georgia
2,670
59.
French Guiana
1,498
60.
Ghana
16,393
61.
Gibraltar
685
62.
Greenland
337
63.
Gambia
1,724
64.
Guinea
1,982
65.
Guadeloupe
1,193
66.
Equatorial Guinea
1,528
67.
Greece
21,689
68.
Guatemala
3,993
69.
Guam
533
70.
Guyana
672
71.
Hong Kong SAR China
11,574
72.
Honduras
2,759
73.
Croatia
5,376
74.
Haiti
1,630
75.
Hungary
20,347
76.
Indonesia
107,059
77.
Ireland
11,509
78.
Israel
14,677
79.
India
149,630
80.
Iraq
15,966
81.
Iran
15,702
82.
Iceland
2,822
83.
Italy
118,384
84.
Jersey
721
85.
Jamaica
2,866
86.
Jordan
9,461
87.
Japan
39,530
88.
Kenya
16,962
89.
Kyrgyzstan
2,623
90.
Cambodia
3,704
91.
Comoros
974
92.
South Korea
51,070
93.
Kuwait
18,370
94.
Kazakhstan
7,126
95.
Laos
1,622
96.
Lebanon
14,202
97.
Saint Lucia
593
98.
Liechtenstein
366
99.
Sri Lanka
11,671
100.
Liberia
1,252
101.
Lesotho
1,135
102.
Lithuania
4,217
103.
Luxembourg
4,734
104.
Latvia
3,309
105.
Libya
4,513
106.
Morocco
52,767
107.
Monaco
955
108.
Moldova
3,511
109.
Montenegro
1,751
110.
Madagascar
5,853
111.
Macedonia
5,892
112.
Mali
5,697
113.
Myanmar [Burma]
7,184
114.
Mongolia
1,389
115.
Martinique
1,023
116.
Mauritania
1,892
117.
Malta
3,718
118.
Mauritius
7,320
119.
Maldives
1,811
120.
Malawi
1,961
121.
Mexico
33,427
122.
Malaysia
46,913
123.
Mozambique
9,859
124.
Namibia
4,092
125.
New Caledonia
613
126.
Niger
2,466
127.
Nigeria
101,869
128.
Nicaragua
2,459
129.
Netherlands
57,468
130.
Norway
13,165
131.
Nepal
5,793
132.
New Zealand
6,060
133.
Oman
12,514
134.
Panama
3,382
135.
Peru
15,609
136.
French Polynesia
730
137.
Papua New Guinea
1,401
138.
Philippines
37,394
139.
Pakistan
22,909
140.
Poland
25,763
141.
Puerto Rico
4,527
142.
Palestinian Territories
3,968
143.
Portugal
44,374
144.
Paraguay
2,478
145.
Qatar
10,433
146.
Réunion
6,210
147.
Romania
32,764
148.
Serbia
11,751
149.
Russia
49,964
150.
Rwanda
3,757
151.
Saudi Arabia
70,408
152.
Seychelles
1,006
153.
Sudan
7,360
154.
Sweden
29,095
155.
Singapore
19,257
156.
Saint Helena
2,469
157.
Slovenia
5,277
158.
Slovakia
9,364
159.
Sierra Leone
1,246
160.
San Marino
492
161.
Senegal
17,514
162.
Somalia
1,276
163.
Suriname
688
164.
São Tomé and Príncipe
486
165.
El Salvador
5,072
166.
Syria
6,672
167.
Swaziland
879
168.
Chad
829
169.
Togo
6,000
170.
Thailand
93,345
171.
Tajikistan
1,243
172.
Timor-Leste
488
173.
Turkmenistan
1,002
174.
Tunisia
23,123
175.
Turkey
112,624
176.
Trinidad and Tobago
2,003
177.
Taiwan
35,140
178.
Tanzania
8,548
179.
Ukraine
18,808
180.
Uganda
10,927
181.
United States
169,208
182.
Uruguay
2,862
183.
Uzbekistan
3,332
184.
Venezuela
17,889
185.
U.S. Virgin Islands
449
186.
Vietnam
30,496
187.
Yemen
6,352
188.
Mayotte
543
189.
South Africa
50,459
190.
Zambia
3,796
191.
Zimbabwe
4,627

DO YOU SUPPORT ARABIC NAMES?
Yes, our API supports Arabic names. They can also be written in chars from the Arabic alphabet. Arabic is written from right to left in a cursive style and includes 28 letters. As an example, if you query "عبد ال" you will get the following result: "gender": "male" , "accuracy": 100. The arabic name "عبد ال" is urlencoded in this example and the query url would look like: https://gender-api.com/get?name=%D8%B9%D8%A8%D8%AF%20%D8%A7%D9%84&key=YOUR_API_KEY. You can find a full list of supported countries here.

I HEARD ABOUT YOUR EMAIL API. WHAT EXACTLY IS IT?
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 100 entries for free every month. The CSV bulk upload requires a Gender-API.com account. For reasons of data protection, uploaded files will be automatically deleted after one year.

HOW NEEDS THE CSV FILE TO BE FORMATTED?
We support CSV files created on Windows, MacOS, 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 301MB. We recommend using a UTF-8 formatted CSV file with a semicolon as the delimiter to achieve the best results possible. Otherwise, the CSV file can contain further, arbitrary rows, which will also be included in the output file. The file must have at least one column with first names only or a column with full names. 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 300,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. For reasons of data protection, uploaded files will be automatically deleted after one year. 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:
PHP with Composer PHP Legacy TypeScript JavaScript Python Java C#

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 remaining 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

First install our library with npm:

See full client documentation here:

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

First install our library with npm:

See full client documentation here:

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

Download A Sample Project Here:

Documentation:

https://github.com/microknights/Gender-API

HOW DO REQUESTS GET COUNTED?
Every account will be recharged to 100 requests on the first day of every month if there are less than this number of requests left. Only if a result is found, the request will be counted. One name lookup will be counted as one request. If multiple names are requested in one query, each name will be counted as a single request.

WHERE CAN I FIND AND MANAGE MY API KEYS?
We generate an initial API key when you sign up for a Gender-API.com account. You can find this API key at the bottom of your account overview page. If you want to revoke this key, click on the "Revoke and Regenerate" button. Our system will then invalidate the existing API key and will generate a new one. All your applications that use the old token will then be unable to access our API until you replace this code with the new API key. Screenshot API key box You can also create more than one API key. This is useful, for example, if you have multiple applications in which you want to include our API. Please note there is no distinction between the keys and how many requests it has used. All requests are counted collectively. To manage or create multiple API keys, click on the "Settings" button in the account menu and then on "API Keys". Manage multiple API keys By clicking on the button "Create New Key", you can generate a new API key. You can give every token a name to later identify more easily where this key has been used. You can change this name at any time. Also, some of our widgets will auto-generate a key hereg. For example, if you use our "Quick Lookup Widget" in your account, our system will generate a key in advance, and this widget will then use this token to query our API. Furthermore, third-party apps will create a key here once they are connected. Every token can be revoked at any time by simply clicking on the "x". Once revoked, the connected application will no longer have access to our API.

CAN I SHARE MY ACCOUNT WITH MULTIPLE PEOPLE?
You can share your account with up to 50 more colleagues or other people connected to your project in your account. To manage your team, log into your account and, in the account menu, click on "Settings" => "Manage Your Team". On this page, click on the "Invite a new member" button to invite people via email to your team. When inviting members, you can choose between two different account types. A) Users can view, create, update and delete API keys, upload and genderize CSV and Excel files, access all API endpoints, buy requests and connect third-party apps. B) Administrators can do the same things users can, plus update account settings and billing address, create and view data processing agreements, invite, update and delete team members.

CAN I PROTECT MY ACCOUNT BY ENABLING TWO-STEP VERIFICATION?
You can protect your account by enabling two-step verification. To enable this additional security measure, log into your account and, in the accounts menu, click on "Settings" => "Change Password / 2FA". Make sure you have an authenticator app installed on your phone. We recommend using an app like Authy (App Store, Play Store) or Google Authenticator (App Store, Play Store). Then click on the "Enable Now" button and follow the instructions on the screen. You can add multiple devices here to ensure, for example, that you still have access to your account after losing a device. Once enabled, you will be required to enter the generated code by your phone's authenticator app to log in successfully.

CAN I USE THIRD PARTY APPS WHEN TWO-STEP-VERIFICATION IS ENABLED?
Some integrations or third-party apps work flawlessly with two-step verification enabled. Others may require to connect without two-step verification. If you have problems logging into some app with your Gender-API.com credentials, log into your account on Gender-API directly and click on "Settings" => "Change Password / 2FA" in the account menu. Then click on the "Two-Step Verification" tab and set "Third-party app access" to "Not restricted". Please note, you can only change this setting if two-step verification is enabled.

WHAT IS THE DIFFERENCE BETWEEN A PAID AND A FREE ACCOUNT?
Both account types offer the same functionality. All API endpoints are available for both account types and will return the same results. Free accounts are limited to a certain amount of requests per month. When you sign up, 100 requests are immediately available to you for free. On the first day of each month, our system will reset this number, and the free requests will be available again. Please create only one account. If you need more requests, you can upgrade to one of our paid plans at any time here.

WHAT IS THE DIFFERENCE BETWEEN A SUBSCRIPTION AND A ONE-TIME PAYMENT?
If you want to buy one of our packages, you can choose between a one-time payment, or subscribing to this package. Subscriptions are recommended if you want to use our service regularly. You can be assured that there are always enough remaining requests in your account. Requests purchased with a subscription can be used within one month. With an active subscription, our system will recharge your account after one month to the selected amount of requests. For example, if you are subscribed to our 25,000 requests package and have used 21,500, our system will replenish your account to 25,000 requests after one month. One-time packages can be purchased for a single use case and can be used within one year. For example, if you want to process an Excel or CSV file, we recommend the one-time purchase. One-time purchases do not renew. You have to make sure to not run out of requests. You can switch between both package types on our purchase page. Purchase Types Please don't mix both purchase types until you have talked to our support first or know exactly what you are doing. Buying a one-time package while you're subscribed to one of our packages can prevent the subscription from refilling your requests. For example, when there are more requests left from the one-time purchase, than the subscription would refill.

I NEED A CERTIFICATE OF RESIDENCE. CAN YOU ISSUE SUCH A CERTIFICATE?
If you need a certificate of residence from our company, please contact our support regarding your request. The certificate has to be individually requested for every company. Include in your request the full address of your company, your country of residence, and, if available, your tax number. The certificate of residence needs to be signed through our revenue office. It usually takes 2-3 weeks to receive the signed form, which we can then provide as a digital scan. Screenshot Certificate Of Resicence

HOW CAN I BUY A PACKAGE / MORE REQUESTS?
You can choose between either a subscription plan or a one-time-payment here. One-time-payment is recommended, if you want to process a large CSV file or if you prefer to use your requests on an 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.

HOW CAN I CANCEL MY SUBSCRIPTION?
You can change or cancel your subscription at any time here. If you want to stop your recurring payments, click on the "Cancel this subscription" button.
Chat
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.
Privacy Policy Terms Of Use
Accept All Deny All