Extract names

This endpoint extracts complete names of persons from any text. By using a combination of 1.597.154 first names and 5.012.607 last names we can identify and extract complete names with an extremely high precision and accuracy.

In the past extracting names from text was done using named-entity recognition (NER). Named-entity recognition is a form of natural language processing (NLP), a subfield of artificial intelligence. The great thing about named-entity recognition is that it is more efficient then going over each word in a text to check if it is a name. Unfortunately named-entity recognition is in many cases not accurate enough (~90%).

Our name extraction endpoint does not use AI. We use extremely fast servers and by combination databases with 1.597.154 first names and 5.012.607 last names (and some additional logic) we can identify and extract complete names fast, with an extremely high precision and a high accuracy.

The name extraction endpoint can be use to identify what names are in a news article, social media post or on a web page. 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
text required The text that you want to extract the complete names from. The text should not be longer then 2048 characters. Longer requests will result in an error. Make sure to use URL Encoding Functions when sending text to this endpoint. Veteran quarterback Philip Rivers moved ahead of Matteo Federica on the NFL's all-time passing list.
country_code optional If you know the country code associated with the text then you can provide it. By providing the country code the associated language(s) will be used to filter out common keywords and the accuracy of the gender will be higher. The country code should be 2 characters according to the ISO 3166-2 country code specification. DE
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 extract all names from a piece of text. 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=extract&text=Veteran%20quarterback%20Philip%20Rivers%20moved%20ahead%20of%20Matteo%20Federica%20on%20the%20NFL%27s%20all-time%20passing%20list.

If you know the country code associated with the text then you can provide it. By providing the country code the associated language(s) will be used to filter out common keywords and the accuracy of the gender will be higher. 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=extract&text=Veteran%20quarterback%20Philip%20Rivers%20moved%20ahead%20of%20Matteo%20Federica%20on%20the%20NFL%27s%20all-time%20passing%20list.&country_code=US

Response object

{
    results: 2,
    error: null,
    data: [
        {
            name: "Matteo Federica",
            frequency: 3020,
            parsed: {
                salutation: {
                    salutation: "Mr.",
                    initials: "M.",
                    lastname: "Federica"
                },
                title: null,
                name: {
                    nickname: null,
                    firstname: {
                        name: "Matteo",
                        name_ascii: "Matteo",
                        validated: true,
                        gender: "m",
                        gender_formatted: "male",
                        unisex: false,
                        gender_deviation: 0,
                        country_code: "IT",
                        country_certainty: 71,
                        country_rank: 10,
                        country_frequency: 3020,
                        alternative_countries: {
                            US: 11,
                            GB: 3
                        }
                    },
                    middlenames: null,
                    lastname: {
                        name: "Federica",
                        name_ascii: "Federica",
                        validated: false,
                        country_code: "AR",
                        country_certainty: 0,
                        country_rank: 154408,
                        alternative_countries: {
                            IT: 83,
                            US: 17
                        }
                    }
                },
                country: {
                    country_code: "IT",
                    country_certainty: 80,
                    country_code_alpha: "ITA",
                    name: "Italy",
                    continent: "Europe",
                    demonym: "Italian",
                    primary_language_code: "it",
                    primary_language: "Italian",
                    currency: "EUR",
                    alternative_countries: {
                        US: 15,
                        GB: 2,
                        LU: 1
                    }
                }
            },
        {
            name: "Philip Rivers",
            frequency: 2228,
            parsed: {
                salutation: {
                    salutation: "Mr.",
                    initials: "P.",
                    lastname: "Rivers"
                },
                title: null,
                name: {
                    nickname: null,
                    firstname: {
                        name: "Philip",
                        name_ascii: "Philip",
                        validated: true,
                        gender: "m",
                        gender_formatted: "male",
                        unisex: false,
                        gender_deviation: 0,
                        country_code: "GB",
                        country_certainty: 29,
                        country_rank: 77,
                        country_frequency: 1889,
                        alternative_countries: {
                            US: 28,
                            DE: 6,
                            IE: 4
                        }
                    },
                    middlenames: null,
                    lastname: {
                        name: "Rivers",
                        name_ascii: "Rivers",
                        validated: true,
                        country_code: "US",
                        country_certainty: 69,
                        country_rank: 868,
                        country_frequency: 339,
                        alternative_countries: {
                            GB: 23,
                            CA: 4,
                            AU: 3
                        }
                    }
                },
                country: {
                    country_code: "US",
                    country_certainty: 47,
                    country_code_alpha: "USA",
                    name: "United States",
                    continent: "North America",
                    demonym: "American",
                    primary_language_code: "en",
                    primary_language: "English",
                    currency: "USD",
                    alternative_countries: {
                        GB: 27,
                        CA: 4,
                        DE: 3
                    }
                }
            }
        }
    ]
}

Response parameters

The response object contains all the names that could be extracted. This means that the response object can contain multiple names. 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
name string The complete name that was extracted from the given text.
frequency integer The sum of the first name and last name frequency. A higher frequency means that the name is more common and thereby more accurate. Names with a low frequency (lower then 100) are less common and can be false positives.
parsed object For the ease of use we also return the parsed result of the extracted names.