FREQUENTLY ASKED QUESTIONS

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.

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.

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.

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.

Yes, we do. We support AES_256_CBC up to TLS 1.2 to give you the best possible privacy protection.

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.

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.

Yes, this is absolutely possible. You can query up to 100 names at once. For details, please take a look at our API Docs.

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.

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.

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.

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:

We very much appreciate your help. Please send us an email to contact gender-api.com and we will try to fix this bug as soon as possible.

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:

$ 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();
}

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

$ 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);
}

$ 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);
}

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();
    }
  }
}

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.

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.