Getting started

GET /v1/places/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 businesses with one or more cuisines in California:

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

The response returns a fill_count for cuisines:

{
  "count": 1777157,
  "insights": {
    "field": "restaurant.cuisines",
    "fill_count": 65715
  }
}

Value Count

Calculate the total number of cuisine values for records in California:

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

The response returns a value_count for cuisines:

{
  "count": 1777157,
  "insights": {
    "field": "restaurant.cuisines",
    "value_count": 112204
  }
}

For objects such as contacts and operating_hours, use the id field to run the count:

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

Unique Count

Calculate the unique business names for places in California:

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

The response returns a unique_count for name:

{
  "count": 1777157,
  "insights": {
    "field": "name",
    "unique_count": 1574923
  }
}

Frequencies

Count the number of records per state:

curl https://api.data-axle.com/v1/places/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://api.data-axle.com/v1/places/insights -X GET -d '{
  "insights": {
    "field": "restaurant.cuisines",
    "calculations": ["frequencies"],
    "insights": {
      "field": "parking.valet",
      "calculations": ["fill_count"]
    }
  }
}'

Within each frequency, a nested insight for parking.valet is returned:

{
  "count": 1231,
  "insights": {
    "field": "restaurant.cuisines",
    "frequencies": [
      {
        "value": "american",
        "count": 394,
        "insights": {
          "field": "parking.valet",
          "fill_count": 93
        }
      },
      {
        "value": "chinese",
        "count": 341,
        "insights": {
          "field": "parking.valet",
          "fill_count": 115
        }
      },
      ...
    ]
  }
}

Frequency Options

Change the behavior of frequency insights with frequency_options.

Ranges

Frequencies for numeric fields can be grouped into ranges:

curl https://api.data-axle.com/v1/places/insights -X GET -d '{
  "insights": {
    "field": "location_employee_count",
    "calculations": ["frequencies"],
    "frequency_options": {
      "ranges": [
        { "from": 1,  "to": 50 },
        { "from": 51, "to": 150 },
        { "from": 151 }
      ]
    }
  }
}'

{
  "count": 16028792,
  "insights": {
    "field": "location_employee_count",
    "frequencies": [
      {
        "lower": 1,
        "upper": 50,
        "count": 7548899
      },
      {
        "lower": 51,
        "upper": 150,
        "count": 2716137
      },
      {
        "lower": 51,
        "count": 1453347
      }
    ]
  }
}

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

Sifted

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

curl https://api.data-axle.com/v1/places/insights -X GET -d '{
  "filter": {
    "attribute": "restaurant.cuisines",
    "relation": "in",
    "value": ["japanese", "sushi"]
  },
  "insights": {
    "field": "restaurant.cuisines",
    "calculations": ["frequencies"]
  }
}'

Since each business may have multiple cuisines, the sum of frequency counts exceeds the record count:

{
  "count": 21410,
  "insights": {
    "field": "restaurant.cuisines",
    "frequencies": [
      {
        "value": "japanese",
        "label": "Japanese",
        "count": 14493
      },
      {
        "value": "sushi",
        "label": "Sushi",
        "count": 13035
      }
    ]
  }
}

A sifted option controls ordering and considers each record once.

curl https://api.data-axle.com/v1/places/insights -X GET -d '{
  "insights": {
    "field": "restaurant.cuisines",
    "calculations": ["frequencies"],
    "frequency_options": {
      "sifted": [
        "sushi",
        "japanese"
      ]
    }
  }
}'

Records matching "sushi" are not considered for "japanese" counts:

{
  "count": 21410,
  "insights": {
    "field": "restaurant.cuisines",
    "frequencies": [
      {
        "value": "sushi",
        "label": "Sushi",
        "count": 13035
      },
      {
        "value": "japanese",
        "label": "Japanese",
        "count": 8375
      }
    ]
  }
}

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 contacts perspective, contacts.email is a valid insights field, but zip is not.

curl https://api.data-axle.com/v1/places/insights -X GET -d '{
  "perspective": "contacts",
  "filter": {
    "attribute": "contacts.job_titles",
    "relation": "equals",
    "value": "Chief Executive Officer"
  },
  "insights": {
    "field": "contacts.gender",
    "calculations": ["fill_count", "frequencies"]
  }
}'