Getting started

GET /v1/people/insights

The Insights API returns metrics for a field, across a segment of records. Two inputs are required:

• An insight describing the fields and calculations to collect.
• An optional filter to define the records to consider.

Available Calculations

Filters

The filter parameter reduces results to records matching a specified criteria, using the Filter DSL.

Fill Count

Calculate the number of people with one or more family behaviors in California:

curl https://qa.api.data-axle.com/v1/people/insights -X GET -d '{
  "filter": {
    "relation": "equals",
    "attribute": "state",
    "value": "CA"
  },
  "insights": {
    "field": "family.behaviors",
    "calculations": ["fill_count"]
  }
}'

The response returns a fill_count for family behaviors:

{
  "count": 85862440,
  "insights": {
    "field": "family.behaviors",
    "fill_count": 42467601
  }
}

Value Count

Calculate the total number of family behavior values for records in California:

curl https://qa.api.data-axle.com/v1/people/insights -X GET -d '{
  "filter": {
    "relation": "equals",
    "attribute": "state",
    "value": "CA"
  },
  "insights": {
    "field": "family.behaviors",
    "calculations": ["value_count"]
  }
}'

The response returns a value_count for family behaviors:

{
  "count": 33048317,
  "insights": {
    "field": "family.behaviors",
    "value_count": 2211421713
  }
}

For objects such as interests, use the id field to run the count:

curl https://qa.api.data-axle.com/v1/people/insights -X GET -d '{
  "insights": {
    "field": "interests.id",
    "calculations": ["value_count"]
  }
}'

Unique Count

Calculate the unique first names for people in California:

curl https://qa.api.data-axle.com/v1/people/insights -X GET -d '{
  "filter": {
    "relation": "equals",
    "attribute": "state",
    "value": "CA"
  },
  "insights": {
    "field": "first_name",
    "calculations": ["unique_count"]
  }
}'

The response returns a unique_count for first name:

{
  "count": 33048317,
  "insights": {
    "field": "first_name",
    "unique_count": 732848
  }
}

For objects such as interests, use the id field to run the count:

curl https://qa.api.data-axle.com/v1/people/insights -X GET -d '{
  "insights": {
    "field": "interests.id",
    "calculations": ["value_count"]
  }
}'

Frequencies

Count the number of records per state:

curl https://qa.api.data-axle.com/v1/people/insights -X GET -d '{
  "insights": {
    "field": "state",
    "calculations": ["frequencies"]
  }
}'

The response returns a total count of matching results, along with frequencies for each state:

{
  "count": 1231,
  "insights": {
    "field": "state",
    "frequencies": [
      {
        "value": "CA",
        "label": "California",
        "count": 1781000
      },
      {
        "value": "TX",
        "label": "Texas",
        "count": 1103438
      },
      {
        "value": "FL",
        "label": "Florida",
        "count": 992429
      },
      ...
    ]
  }
}

Nested Frequencies

Use Nested Insights to calculate inner values per frequency:

curl https://qa.api.data-axle.com/v1/people/insights -X GET -d '{
  "insights": {
    "field": "family.estimated_education_level",
    "calculations": ["frequencies"],
    "insights": {
      "field": "credit_card_types",
      "calculations": ["fill_count"]
    }
  }
}'

Within each frequency, a nested insight for credit_card_types is returned:

{
  "count": 28109370,
  "insights": {
    "field": "family.estimated_education_level",
    "frequencies": [
      {
        "value": "associates",
        "count": 6783927,
        "insights": {
          "field": "credit_card_types",
          "fill_count": 638362
        }
      },
      {
        "value": "diploma",
        "count": 5373957,
        "insights": {
          "field": "credit_card_types",
          "fill_count": 582734
        }
      },
      ...
    ]
  }
}

Frequency Options

Change the behavior of frequency insights with frequency_options.

Ranges

Frequencies for numeric fields can be grouped into ranges:

curl https://qa.api.data-axle.com/v1/people/insights -X GET -d '{
  "insights": {
    "field": "mortgage.loan_amount",
    "calculations": ["frequencies"],
    "frequency_options": {
      "ranges": [
        { "from": 1,     "to": 9999 },
        { "from": 10000, "to": 99999 },
        { "from": 100000 }
      ]
    }
  }
}'

{
  "count": 183756037,
  "insights": {
    "field": "mortgage.loan_amount",
    "frequencies": [
      {
        "lower": 1,
        "upper": 9999,
        "count": 74973
      },
      {
        "lower": 10000,
        "upper": 99999,
        "count": 8379694
      },
      {
        "lower": 100000,
        "count": 8847403
      }
    ]
  }
}

Certain fields, such as family.estimated_income, have default ranges if none are provided.

Sifted

Use sifted frequencies to order distinct counts across specific values. Consider the following case for family.behaviors:

curl https://qa.api.data-axle.com/v1/people/insights -X GET -d '{
  "filter": {
    "attribute": "family.behaviors",
    "relation": "in",
    "value": ["golf", "professional_baseball"]
  },
  "insights": {
    "field": "family.behaviors",
    "calculations": ["frequencies"]
  }
}'

Since a person has multiple behaviors, the sum of frequency counts exceeds the record count:

{
  "count": 5921288,
  "insights": {
    "field": "credit_card_types",
    "frequencies": [
      {
        "value": "golf",
        "label": "Golf",
        "count": 4443908
      },
      {
        "value": "professional_baseball",
        "label": "Professional Baseball",
        "count": 4070814
      }
    ]
  }
}

A sifted option controls ordering and considers each record once.

curl https://qa.api.data-axle.com/v1/people/insights -X GET -d '{
  "insights": {
    "field": "family.behaviors",
    "calculations": ["frequencies"],
    "frequency_options": {
      "sifted": [
        "golf",
        "professional_baseball"
      ]
    }
  }
}'

Records matching "golf" are not considered for "professional_baseball" counts:

{
  "count": 5921288,
  "insights": {
    "field": "family.behaviors",
    "frequencies": [
      {
        "value": "golf",
        "label": "Golf",
        "count": 4443908
      },
      {
        "value": "professional_baseball",
        "label": "Professional Baseball",
        "count": 1477380
      }
    ]
  }
}

Perspective

The perspective pivots the top level record. This changes the calculation results for nested objects. When using a perspective with insights, insights must use fields from the same nesting that the perspective uses.

For example, when using the emails perspective, emails.address is a valid insights field, but age is not.

curl https://qa.api.data-axle.com/v1/people/insights -X GET -d '{
  "perspective": "emails",
  "filter": {
    "attribute": "emails.marketable",
    "relation": "equals",
    "value": true
  },
  "insights": {
    "field": "emails.address",
    "calculations": ["fill_count", "unique_count"]
  }
}'