Extract names
This API endpoint extracts complete names from unstructured text very fast. By using a combination of 2.208.942 first names and 6.119.869 surnames 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.
Don't want to write your own code and start extracting names from text quickly? We've done the heavy lifting for you. Have a look at our extended example code on Github.
Request parameters
| Name | Description |
|---|---|
| api_key | Your API key is required for every API call. Register for a free API key. |
| text | 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. |
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=USResponse 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 surname frequency. A higher frequency means that the name is more common and thereby more accurate. Names with a low frequency (lower than 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. |