Looking for the FullContact Address Book App? You can now find it at Contacts+

Learn More
FullContact Name Statistics API

What's Really In A Name? Ask the Name Stats API.

Written By:


A name by itself contains very little information; it’s just a string of letters. So what do you do when you need to know more about a name?

At FullContact, we’re solving the world’s contact management problem, an in doing so we’ve created a number of tools to deal with names, like the Name Similarity, Name Parser, Name Deducer, and Name Normalization APIs. We use these tools internally to increase the quality of our search results and overall data.

Today we’re announcing the release of the Name Stats API, which provides a variety of parameters that can be used to determine more about a name. By using U.S. census data, the Name Stats API can determine:

  • The likelihood the name is a given name or last name.
  • The likelihood the person with the name is male or female.
  • The estimated count of living people with the name in the US.
  • The rank of popularity of the name in the US.
  • The frequency in the US population that the name occurs.
  • The mean age of people with the particular name.
  • The mode age of people with the particular name.
  • The quartiles and median age of people with the particular name.

How Do You Use It?

A basic query to the Name Stats API looks like this:

https://api.fullcontact.com/v2/name/stats.json?name=chuck&apiKey=xxxx

Simply pass a name string via the name parameter. The response data will vary based on which parameters you submit data for.

Example JSON Response

{
  "status": 200,
  "name": {
    "value": "Robbie",
    "given": {
      "likelihood": 0.99,
      "count": 34586,
      "rank": 1021,
      "male": {
        "count": 18594,
        "likelihood": 0.538,
        "rank": 646,
        "frequencyRatio": "0.000140387",
        "age": {
          "densityCurve": {
            "mode": {
              "count": 824,
              "modeAge": 
              [
                48
              ]
            },
            "meanAge": 44.7,
            "quartiles": {
              "q1": 31.6,
              "q2": 41.6,
              "q3": 48.5
            }
          }
        }
      },
      "female": {
        "count": 15991,
        "likelihood": 0.462,
        "rank": 896,
        "frequencyRatio": "0.000121266",
        "age": {
          "densityCurve": {
            "mode": {
              "count": 457,
              "modeAge": 
              [
                54
              ]
            },
            "meanAge": 53.4,
            "quartiles": {
              "q1": 46.2,
              "q2": 55.8,
              "q3": 69.6
            }
          }
        }
      }
    },
    "family": {
      "likelihood": 0.01,
      "count": 363,
      "rank": 53420,
      "frequencyRatio": "0.000001499"
    }
  },
  "region": "USA"
}

Example Queries and Parameters

Name

The name parameter can be used when you only know a single name and you are uncertain whether it is the given name or family name.

https://api.fullcontact.com/v2/name/stats.json?name=chuck&apiKey=xxxx

givenName

The givenName parameter can be used when you know that the name is a given name (first name).

https://api.fullcontact.com/v2/name/stats.json?givenName=chuck&apiKey=xxxx

familyName

The familyName parameter can be used when you know that the name is a family name (last name).

https://api.fullcontact.com/v2/name/stats.json?familyName=testa&apiKey=xxxx

givenName & familyName

The givenName and familyName parameters can be used together when you know both the first name and last name of the person.

https://api.fullcontact.com/v2/name/stats.json?givenName=chuck&familyName=testa&apiKey=xxxx

How Does It Work?

The Name Stats API is powered by name statistics data from the US Social Security Administration and the US Census. Given name analysis is done based on an estimated living population for a name. Family name analysis was done based on 2010 US Census data. Because of the methods used by the US SSA and US Census, no personally identifiable information is available via this API. More information about the math behind the Name Stats API can be found here.

It’s Free, So What Are You Waiting For?

Like the other FullContact Name API methods, Name Stats is completely free to use. Just sign-up for a FullContact API key to get started. Let us know what you think, and if you have any feedback or questions, email me at robbie@fullcontact.com.

For more detailed examples and instructions, refer to the Name Stats API Documentation.

Recent Posts