Generate random name

This endpoint generates a random complete name by combining a random first name and a random last name for any given country code. Additionally the endpoint also returns the salutation and nationality of the fictional name.

The name generator endpoint is very useful for software development projects. For new projects you can generate fictional accounts including the salutation, gender and country details. Instead of using databases with real customer names in your development environment its more secure to use fictional names instead. We've compiled a list with use cases on a separate page.

Request parameters

Name Required Description Example
api_key required Your API key is required for every API call. Register for a free API key. 93d471ea85d1937e713e8aafffb32090
results optional The number of generated names you want to receive in the response object. For example: 3 will give you 3 different generated name objects. The maximum number of queries depends on you subscription. 3
country_code optional Use the country_code parameter if you want to generate random names for a specific country. The country code should be 2 characters according to the ISO 3166-2 country code specification. DE
ip optional If you don't know a country code you can always provide an IP address. We convert the IP address to a country_code internally. 66.249.64.85
response_type optional The API returns JSON objects written in key/value pairs by default. If needed you can also get the response as a JSON array instead. object, array
gender_type optional Different type of kind can be used as a value for gender_formatted. By default the gender field returns "male" or "female". You can change the formatting from sex (default) to gender, marital, birth and slang. sex, gender, marital, birth, slang

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=generate

If 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=DE

Depending 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=3

Response object

{
    results: 1,
    error: null,
    data: [
        {
            salutation: {
                salutation: "Mr.",
                initials: "J.",
                lastname: "Smith"
            },
            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: "Smith",
                    name_ascii: "Smith",
                    validated: true,
                    country_code: "US",
                    country_certainty: 62,
                    country_rank: 1,
                    alternative_countries: {
                        GB: 24,
                        CA: 3,
                        AU: 3
                    }
                }
            },
            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 last name 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 last name 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 1.597.154 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 last name) 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.
response optional The API returns JSON objects written in key/value pairs by default. If needed you can also get the response as a JSON array instead. object, array