Parse names

Don't want to write your own code and start parsing names quickly? We've done the heavy lifting for you. Have a look at our extended example code on Github.

Request parameters

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 10 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 contain 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

Response objects

There are two different response objects with three different status codes possible. If the name can be parsed you will receive an object with all the components of the parsed name and the status code will be 200. If the name can not be parsed, because it is misspelled, you will receive an error and there are two possibilities. In some cases we can detect the spelling mistake that are made in the first name, and we'll return a list with the possible first names accompanied by status code 404. If we can't parse the name and can't detect any spelling mistakes we'll return a status code 400.

This is how a successful parsed response objects looks like:

{
    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: [ ]
            }
        }
    ]
}

This is how an unsuccessful parsed response objects looks like:

{
    results: 0,
    error: "The service could not find a name in 'Chriatian'. Select of the following suggested first names instead.",
    data: [
        {
            firstnames: [
                {
                    name: "Christian",
                    name_ascii: "christian",
                    similarity: 89,
                    levenshtein: 1,
                    frequency: 43419,
                },
               {
                    name: "Christiaan",
                    name_ascii: "christiaan",
                    similarity: 84,
                    levenshtein: 2,
                    frequency: 680,
                },
               {
                    name: "Christiana",
                    name_ascii: "christiana",
                    similarity: 84,
                    levenshtein: 2,
                    frequency: 604,
                }
            ]
        }
    ]
}

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.