Generate random names
This API endpoint generates names by combining a random first name and a random surname for any given country code. Additionally, the endpoint also generates a fictional email address and strong password making it a great solution to create development databases.
The name generator endpoint is very useful for software developers. Instead of developing software with real data its more secure to use fictional accounts instead. Use our API and Web App to generate fictional accounts including email address, strong password, gender and country details.
Do you want to get started quickly? Have a look at our extended example code on Github. Or, if you're looking for a big name database with firstnames and surnames checkout Name Census .
Request parameters
| Name | Description |
|---|---|
| api_key | Your API key is required for every API call. Register for a free API key. |
| gender | Use the gender parameter the specify for what gender you want to generate random names. Use the letter 'f' for female names and 'm' for male names. |
| results | The number of generated names you want to receive in the response object. For example: 5 will give you 5 different generated name objects. The maximum number of results is 25. |
| country_code | Use the country_code parameter if you want to generate random names for a specific country. The name generator works differently per country. For example; in Spanish-speaking countries it is common to have two surnames. The country code should be 2 characters according to the ISO 3166-2 country code specification. |
| ip | Use the 'ip' parameter if you want to generate random names for a specific country. We convert the IP address to a country_code internally. |
Request URL
This is the easiest way to generate a random name. Each response is JSON encoded so easy to use. You can copy past the request URL in the address bar of your browser to see the response.
https://api.parser.name/?api_key=YOUR_KEY&endpoint=generateIf you want to generate random names for a specific country you can provide the country_code parameter. The country_code is limited to the countries that we support.
https://api.parser.name/?api_key=YOUR_KEY&endpoint=generate&country_code=DEDepending on your subscription you can generate multiple names in a single request by adding the 'results' parameter. If you use the 'results' parameter then the response object will contain multiple name objects.
https://api.parser.name/?api_key=YOUR_KEY&endpoint=generate&results=3Response object
{
results: 1,
error: null,
data: [
{
salutation: {
salutation: "Mr.",
initials: "J.",
lastname: "Bruch"
},
title: null,
name: {
nickname: null,
firstname: {
name: "John",
name_ascii: "John",
validated: true,
gender: "m",
gender_formatted: "male",
unisex: false,
gender_deviation: 0,
country_code: "US",
country_certainty: 60,
country_rank: 3,
alternative_countries: {
GB: 13,
CA: 3
}
},
lastname: {
name: "Bruch",
name_ascii: "Bruch",
validated: true,
country_code: "US",
country_certainty: 62,
country_rank: 1,
alternative_countries: {
GB: 24,
CA: 3,
AU: 3
}
}
},
email: {
address: "j.bruch.87@yahoo.com",
username: "j.bruch.87",
domain: "yahoo.com",
provider: {
name: "Yahoo Mail",
country_code: "US"
},
business: false
},
password: "JB27-RGOCLh_",
country: {
country_code: "US",
country_certainty: 63,
country_code_alpha: "USA",
name: "United States",
continent: "North America",
demonym: "American",
primary_language_code: "en",
primary_language: "English",
currency: "USD",
alternative_countries: {
GB: 19,
CA: 3,
AU: 3
}
}
}
]
}Response parameters
Most response parameters are self-explanatory. However, there are a few fields that need an additional explanation. These fields are listed in the table below. If you're looking for is a response parameter that is not in this list, please contact us and we'll add it to this list.
| Name | Type | Description |
|---|---|---|
| validated | boolean | The validated key is a boolean indicating if a first name, middle name or surname exists in an official database. Most countries and their governments have great open data initiatives and provide official first names, gender and frequencies. For the first name and middle names the validated key is a boolean indicating if the name is also in the official database for the resulting country. If the validated key is 'false' then the name is derived from another country. It's still an existing name, but we don't have the official database for that country. For the surname it means it has at least to occur two times in the resulting country. |
| gender | enum | The gender is always an "m" (male) or "f" (female). Our database holds 2.208.942 official first names and their gender received from governments. By providing the country_code in the request parameter the accuracy of the gender will be higher. |
| unisex | boolean | A unisex name is a given name that can be used by a person regardless of their gender. |
| gender_deviation | integer | The gender deviation is a percentage indication the change that the gender is the opposite as provided. |
| alternative_countries | array | Each name (first name, middle name or surname) has a country code. The country code is the most likely country where the name originates from. The alternative countries is an array that hold the 'second best' estimations. The values are the country certainty percentages (higher is more likely). After analyzing all names and countries the services makes a selects the most likely country where the complete name originates from. |
| array | For every generated name we also generate a fictional email address. We will add random separation characters and select random email providers that actually exist in the resulting country. | |
| password | string | For every generated name we also generate a strong password. The email address and password can be used together to create accounts for development databases. |