Parse name

This endpoint parses a complete name or email address and returns the first name, middle names and last name. Additionally it also returns the nickname, salutation, title, email provider and the most likely nationality of the given name.

The name parsing endpoint is very useful for online businesses and services. It shortens forms, validates names and enriches existing customer database with their gender, salutation and nationality. Use our API and Web App to parse names into useful components.

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
name required * The complete name that you want to parse. Depending on your subscription you can query multiple names in a single request by making an array out of it.
Example: name[]=John Bruch&name[]=Sarah Jones
John Bruch
email required * The email address that you want to parse. Depending on your subscription you can query multiple email addresses in a single request by making an array out of it.
Example: email[]=alopez@t-online.de&email[]=j.bruch.87@yahoo.com
j.bruch.87@yahoo.com
validate optional We validate a name by checking if the given name is possibly fake When the parameter 'validate' is set to 'true' we will compare the name with 13.738 famous, fictional and humorous names. Additionally we will also check if the first name and last name are existing names. true
country_code optional If you know the country code associated with the name then you can provide it. By providing the country code the accuracy of the gender will be higher. The country code should be 2 characters according to the ISO 3166-2 country code specification. If the name parameter contains multiple names then the country_code should also be an array. DE
ip optional If you don't know the country code you can always provide an IP address. We convert the IP address to a country_code internally. If the name parameter contains multiple names then the ip should also be an array. 66.249.64.85
Note: required * means that either the 'name' or 'email' address is required. They can not be mixed or used at the same time.

Request URL

This is the easiest way to parse a name into it useful components. 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=parse&name=John%20Bruch

If you know the country code of the name then you can add the country code parameter. By specifying the country code the accuracy of the gender will increase. All endpoints use the ISO 3166-2 for country codes. Check our list of countries to see all supported country codes.

https://api.parser.name/?api_key=YOUR_KEY&endpoint=parse&name=John%20Bruch&country_code=US

It is possible to query multiple names in a single request. You can send a maximum array of 25 names in the same request. For the rate limit this counts as a single request making it ideal of you want to process high volumes of names. If you also use the country_code then you have to make an array of that as well.

https://api.parser.name/?api_key=YOUR_KEY&endpoint=parse&name[]=John%20Bruch&name[]=Sarah%20Jones

You can also get the name from a person out of the email address. The email parameter extracts the username from email address and then parses the username. The response object will contains all the name parts and information about the email provider.

https://api.parser.name/?api_key=YOUR_KEY&endpoint=parse&email=j.bruch.87@yahoo.com

Code examples

To make it extra easy to get started we prepared a few code examples. Choose a programming language below and copy the code to get started. Don't forget to replace the YOUR_KEY with the API key your API key.

<?php

function parseName($name){

    //Create variables (don't forget your API key).
    $api_key = "YOUR_KEY";
    $name = urlencode($name);
    $url = "https://api.parser.name/?api_key=".$api_key."&endpoint=parse&name=".$name;

    //Do some cURL magic here.
    $handle = curl_init();
    curl_setopt($handle, CURLOPT_URL, $url);
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($handle);
    if($response != false) {
        $output = json_decode($response, true);
    } else {
        return false;
    }

    //Return the complete name object.
    return $output['data'][0]['name'];
}

//Parse a name into an object.
$object = parseName("John Bruch");

//Print out the data.
print_r($object['firstname']); //Returns firstname object.
print_r($object['firstname']['name']); //Return the firstname "John".
print_r($object['firstname']['gender']); //Returns the gender: "m".
print_r($object['lastname']); //Returns firstname object.

?>
Coming soon
Coming soon
Coming soon

Response 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
                    }
                },
                middlenames: null,
                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
            },
            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
                }
            },
            validation: {
                pass_loose: true,
                pass_strict: true,
                listed_in: [ ],
                listed_as: [ ]
            }
        }
    ]
}

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. If the validated key is 'false' for the 'firstname' then the name is derived from another country. It's still an existing first name but we don't have the official database for that country. If the validated key is 'false' for the last name it means it does not exist in the resulting country.
gender enum The gender is always an 'm' (male) or 'f' (female). Our database holds 1.712.459 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.
email array If the parameter 'email' is used then the email array will contain additional information about the email provider. It contains the name and country of the email provider and also tells if an email address is a personal or a business email address.
validation array If the parameter 'validate' is to 'true' then the name is also validated. The key 'pass_lose' will be 'true' if the first name exist, lastname could be possible and the name should not be listed in our database with famous, fictional and humorous names. The key 'pass_strict' will be 'true' if the first name and last name exist (validated = true) and the name should not be listed in our database with famous, fictional and humorous names. If the name is listed then it will appear in the 'listed_in' and 'listed_as' key's.