Getting started

GET /v1/b2c_links/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 consumers with one or more job titles in California:

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

The response returns a fill_count for job titles:

 {
   "count": 85862440,
   "insights": {
     "field": "job_titles",
     "fill_count": 42467601
   }
 }

Value Count

Calculate the total number of job title values for records in California:

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

The response returns a value_count for job titles:

{
  "count": 33048317,
  "insights": {
    "field": "job_titles",
    "value_count": 2211421713
  }
}

Unique Count

Calculate the unique first names for consumers in California:

curl https://api.data-axle.com/v1/b2c_links/insights -X GET -d '{
  "filter": {
    "relation": "equals",
    "attribute": "workplace.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
  }
}

Frequencies

Count the number of records per state:

curl https://api.data-axle.com/v1/b2c_links/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:

Frequency Options

Change the behavior of frequency insights with frequency_options.

Ranges

Frequencies for numeric fields can be grouped into ranges:

Sifted

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

curl https://api.data-axle.com/v1/b2c_links/insights -X GET -d '{
  "filter": {
    "attribute": "job_titles",
    "relation": "in",
    "value": ["Manager", "Owner"]
  },
  "insights": {
    "field": "job_titles",
    "calculations": ["frequencies"]
  }
}'

Since a consumer can have multiple job titles, the sum of frequency counts exceeds the record count:

{
  "count": 5921288,
  "insights": {
    "field": "job_titles",
    "frequencies": [
      {
        "value": "Owner",
        "count": 4443908
      },
      {
        "value": "Manager",
        "count": 4070814
      }
    ]
  }
}

A sifted option controls ordering and considers each record once.

curl https://api.data-axle.com/v1/b2c_links/insights -X GET -d '{
  "insights": {
    "field": "job_titles",
    "calculations": ["frequencies"],
    "frequency_options": {
      "sifted": [
        "Owner",
        "Manager"
      ]
    }
  }
}'

Records matching "Owner" are not considered for "Manager" counts:

{
  "count": 5921288,
  "insights": {
    "field": "job_titles",
    "frequencies": [
      {
        "value": "Owner",
        "count": 4443908
      },
      {
        "value": "Manager",
        "count": 1477380
      }
    ]
  }
}

Intervals

Date fields are grouped by month by default. Grouping by day and year is supported with the "interval" option.

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.