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://qa.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://qa.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://qa.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://qa.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://qa.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://qa.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
      }
    ]
  }
}

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.