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

Learn More
Person API location deduction

FullContact Person API Gets Improved Location Data

Written By:

While a single string of location data is useful, there’s ultimately only a limited amount of things you can do with it. For example:

{"locationGeneral":"Greater Denver Area"}    < Ugh!

So starting today, we’re giving you more to work with.

As of this morning, we’re excited to announce new functionality. You now have granularity and greater control over the location data you receive from FullContact.

Introducing locationDeduced

Prior to today, here’s a sample of the location data a Person API response might contain:

"demographics" : {
    "locationGeneral" : "Greater Denver Area"

With the changes we’re introducing today, here’s what you’ll see:

  • locationGeneral will still be present in the response, but as of today a new object called locationDeduced will also show up under demographics.
  • locationDeduced is a collection of normalized and enriched versions of the values contained in locationGeneral.
  • normalizedLocation is simply a normalized version of the locationGeneral.
  • deducedLocation is a normalized and enriched version of locationGeneral.
  • For each deducedLocation data element, you will be able to see what was deduced.
  • For the overall deduced location, you will see a confidence (called likelihood) in the result.

An example where locationGeneral is simply “Boulder, CO”:

"demographics" : {
    "locationGeneral" : "Boulder CO",
    "locationDeduced" : {
      "normalizedLocation" : "Boulder, Colorado",
      "deducedLocation" : "Boulder, Colorado, United States",
      "city" : {
        "deduced" : false,
        "name" : "Boulder"
      "state" : {
        "deduced" : false,
        "name" : "Colorado",
        "code" : "CO"
      "country" : {
        "deduced" : true,
        "name" : "United States",
        "code" : "US"
      "continent" : {
        "deduced" : true,
        "name" : "North America"
      "county" : {
        "deduced" : true,
        "name" : "Boulder",
        "code" : "Boulder"
      "likelihood" : 1.0,

For ambiguous general locations where a threshold in likelihood is not reached, locationDeduced will not be returned.

"demographics" : {
    "locationGeneral" : "Salem"

As an example of how this change can improve your app, let’s take a look at targeting and segmentation.

Previously, if one of your app’s customers wanted to find all of their contacts in the Lakewood, CO area, you would have had to analyze individual strings of data and work to determine all the variations of “Lakewood, CO” or nearby.

With the new locationDeduced data, you can easily build out functionality that allows your customers to segment and target more accurately.

Other Changes: Cleaner Location Data

If you rely on the locationGeneral field in our Person API, you’ve also probably noticed that the values that people enter for their location on the internet vary widely. So with the Person API improvements released today, we’ve tried to give you a location that is more actionable and cleaner, too.

Previously, you may have seen data in the locationGeneral field that was clearly not a location (like the inevitable person from “Planet Earth”, etc). As of today, those sorts of locations will now be excluded from both locationGeneral and locationDeduced.

This change should do away with junk data and give you cleaner location information to work with overall.

For those already using the Person API, this is a non-breaking change. The new data will start showing up in your Person API responses today! Let us know what you think.

Are you new to FullContact? Want to add location-enriched customer profiles to your app? Sign Up for a new API key to get started today.

Quickly build contact management features into your app.

Get Started for FreeNo Credit Card Required

Recent Posts