The Gender API takes an individual's name and returns the best estimate of its gender, as well as a confidence score on the gender assessment. An optional parameter of a country may be passed as well to specify the name's country of origin and this increase the accuracy of the gender estimate.
The Gender API, like all of Abstract's APIs, is organized around REST. It is designed to use predictable, resource-oriented URL's and to use HTTP status codes to indicate errors.
The Gender API requires all communications to be secured TLS 1.2 or greater.
All of Abstract's API are versioned. The Gender API is currently on Version 1.
Your API key is your unique authentication key to be used to access Abstract's Gender API. Note that each of Abstract's API has a unique API key, so you will need different keys to access the Gender and Avatar APIs, for example. To authenticate your requests, you will need to append your API key to the base URL.
Your unique API key. Note that each user has unique API keys for each of Abstract's APIs, so your User Avatar API key will not work for as your Gender API key, for example.
The name(s) you want to determine the gender of. Note that bulk requests are supported also (see below for details on making bulk requests).
An optional parameter to increase the accuracy of your results by specifying the person's country of origin. Should be passed using ISO 3166-1 alpha-2 format.
The API response is returned in a universal and lightweight JSON format.
The un-sanitized string that was submitted in the original request.
The sanitized input that was used to check the gender against. Abstract will automatically correct capitalization, clip whitespace, remove unnecessary special characters, etc.
"M" for male, "F" for female, "U" for unknown.
A number between 0.001 and 0.999 reflecting the confidence in the gender designation based on the available data.
The ISO 3166-1 alpha-2 country code that was submitted to localize and increase accuracy of a request.
To request the gender from a name, the absolute minimum that's required is your unique API key and the name you would like to check.
? api_key = YOUR_UNIQUE_API_KEY
& names = John
That's all your need to get the gender from a name! There are only two required parameters: the name and your unique API key.
Each individual name you submit counts as a credit. If you submit 5 names in a single bulk request, that will count as 5 credits. Credits are also counted per request, not per response. So if you submit a request for the name "jkrepuii3ds" and the API is unable to determine a gender for it, that still counts as 1 credit.
While the majority of names have a consistent gender across countries and cultures, the gender of some names vary significantly between country. For example, in the United States "Jean" is primarily a female name, while in France it is primarily a male name. If you only submit the name without a country, Abstract's Gender API will give you the average gender response across all entries in our dataset. However, if you pass a country code along with the name, the API will return gender data specifically for that name and country where it exists.
? api_key = YOUR_UNIQUE_API_KEY
& names = John
& country = US
Note that if the optional country parameter is passed in a request, it will be returned in the response as well.
The API also supports submitting multiple names in a single request
? api_key = YOUR_UNIQUE_API_KEY
& name = John,Paul,George,Ringo
The response for bulk requests will follow the same format as with a single request, except that the genders for individual names will be returned in an array.
The API will sanitize any strings submitted to it in a request before attempting to determine a gender. This typically involves standardizing the capitalization and removing any special characters or extra spaces in the string. If a full name (first and last) is submitted, we will do our best to separate those and only determine the gender of the first name. In the response we return the sanitized string. This is what we used in our attempt to determine the gender.
For example, the string "john smith" would be sanitized to "John", "sandy.jones@" to "Sandy", etc.
While we do our best to write reasonable heuristics to sanitize names, if you're noticing errors or incorrect gender lookups as a result of this sanitation, please contact us and let us know so we can improve the sanitation rules.
Whenever you make a request that fails for some reason, an error is returned also in the JSON format. The errors include an error code and description, which you can find in detail below.
Everything worked as expected.
The request was unacceptable. Typically due to the API key missing or incorrect.
Internal Server Error
The request could not be completed due to an error on the server side.
The server was unavailable.
The Abstract Gender API is a simple application programming interface (API) that allows any individual, company, non-profit, or other organization to determine gender of a first name. Unlike other more complex data sources, this API is very straightforward to use but provides a fast response in accurate data. Only an individual’s name needs to be submitted and the best guess at a gender as well as a confidence score will be returned by the API. More detailed and complex functionality, such as seeing gender and confidence breakdowns by name and country, are available for an additional charge.
The data for the Abstract Gender API comes from a variety of sources that are constantly updated, analyzed, and validated for accuracy and completeness. Data is most commonly taken from a variety of publicly available data sets, such as the tax or birth records made available by various governments. For example, the United States Census Bureau or the Social Security Administration maintain detailed records of the names, genders, and birth years of individuals in the United States. Other entities -- such as Canada's Census Bureau -- maintain similar data sets for their countries. These data sets are matched with a variety of public and private data to ensure they contain the most accurate and up-to-date analysis of the relationship between a name and it's likely gender.
There are many cases where being able to determine the gender of an individual’s name is highly beneficial. The most common commercial application is in improving the segmentation and personalization of an existing data set. For example, let's say an e-commerce company has a list of customers. To ensure they send those customers the most accurate and effective marketing messages, they may want to segment the customers into males or females along with other possible segmentations.
There are many non-commercial use cases as well, particularly in research and media. For example, much attention recently has rightly been given to the gender gap in many aspects of society. Being able to quickly understand the gender of individuals such as film directors or the authors of scientific papers can help illustrate the skewed representation in these industries. If you are working on a non-commercial research project, please contact us for a discount on your subscription to the API.
There are several names that are often unisex or are changing the gender is most commonly associated with them. In this case the API will return its best guess on the gender as well as a confidence score. If it is evenly split then the confidence score will be 0.50 or near that. For advanced users we offer the option to submit a birth year and / or birth country that is associated with a name. This information is often helpful to get a more accurate estimate of the gender of a given name.
While many names may be common across countries and cultures, the gender assigned to those names may actually vary significantly, even in the same time period. For example, the name "Jean" is relative common in both the United States and France. However, in France it is most commonly a male name, while in the United States it is very often a female name. This is why it's important to understand the country or culture of the individual whose name you're trying to find. If you happen to have the individual's IP address, you could use Abstract's IP Geolocation API to determine the country easily and thus improve the accuracy of the gender lookup.
The gender API is very powerful yet simple to use. It contains relatively complete data for names and genders of all countries in the world. However, new names are always being used and the gender associated with those names is changing as society itself evolves. While we try our best to keep the data set updated with this information, we recognize that it is at best a partial representation of the latest name / gender trends. If you notice any inaccuracies please do let us know.
Currently we users to integrate directly with the API itself. We're also working on a number to libraries in popular languages to make it easier and faster for anyone to use this data. If you create a library and are willing to publish it, we're happy to reward you with a significant number of API credits. Just email us at team [at] abstractapi.com. Lastly, we're working on the ability to upload a single CSV containing your data. If you're interested in trialing that functionality, please email us at the same address.
The gender API is very simple to use. First you need to sign up for a free Abstract account. Once your account is created and your email address is confirmed, you will be automatically issued an API key to make a limited number of requests for free. Please sign into your account to learn more about the abilities and restrictions of our various plans.
July 7, 2020
Improved support for Hebrew and Arabic names, as well as handling of Hebrew and Arabic script
June 27, 2020
Improved sanitization of named with special characters
Names with special characters, whether on purpose (e.g., Stéphane) or on accident (e.g., Mi#*37chel) would create issues with the sanitization process in some cases. These special characters are now handled better.
Each of our API's has a free plan as well as several paid options, which offer a greater number of requests, a higher level of data quality, and greater speed for higher prices. Please see the page above or sign into your account to view pricing for each API.
Absolutely! We want you to try before you buy. Each of our API's has a free tier with a generous usage allowance for you to try the product out and verify that the speed and data quality work for you.
We use Stripe to accept payment via major debit and credit cards (Visa, Mastercard, American Express). If you cannot use those payment methods, then contact us at team at abstractapi.com to arrange for an alternative payment method.
Yes, you can upgrade or downgrade your subscription at any time by visiting your dashboard. If you upgrade in the middle of a billing cycle, you will be charged a pro-rated amount for your new plan through the end of the billing cycle.
Yes, all of our subscriptions are month to month. You can cancel at any time, and you will not be charged again at the end of your billing cycle.
You can cancel your subscription at any time from your dashboard. Once canceled, your subscription will be active until the end your current billing cycle, and then it will be automatically moved to the free plan.
If your API usage exceeds the monthly limit set by your plan, then you will be charged a fee for each call over your limit. At the end of your billing period, your usage will reset again.
We do offer enterprise plans with custom features and pricing in limited circumstances. If our public pricing plans don't work for you, then contact us (team at abstractapi.com) and we'll work something out.
While we don't normally offer discounts, we do make exceptions for certain types of users and use cases. If you are a student or are engaged in academic work, or are working on a non-profit or open source project, we're happy to offer you discounts for our API's. Just email us at team at abstractapi.com.
All of our plans are currently paid month to month. We will be launching annual plans at a discount soon. If you're interested in an annual plan in the meantime, just contact us and we'll set you up.
We will typically attempt to charge your payment method up to three times after it fails. If we're still unable to collect payment, then your subscription will be automatically canceled and you'll be moved to the free plan.
Yes, a paid tier of our API may be used in conjunction with a commercial project. The free tiers of our API's may not be used in commercial projects.