View OpenAPI Spec

Getting started

GET /v1/historical_data/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

Count historical business records in Texas with a phone number:

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

Value Count

Count job title values across historical business records in Texas:

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

Unique Count

Count distinct businesses represented in the Texas historical records:

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

Frequencies

Count the number of records per state:

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

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.

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.