Extract names

This endpoint extracts complete names from unstructured text very fast. By using a combination of 1.712.459 first names and 5.238.897 last names we can identify and extract complete names with an extremely high precision and accuracy.

The name extraction endpoint is very useful for software developers and publishers. Extract names from unstructured text with an extremely high precision and accuracy. Use our API and Web App to extract names from unstructured text or documents.

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.

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
                        }
                    }
                },
                email: null,
                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
                        }
                    }
                },
                email: null,
                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.