View OpenAPI Spec

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://qa.api.data-axle.com/v1/places/insights -X GET -d '{
  "contract": "a86ef85a2ec",
  "filter": {
    "relation": "equals",
    "attribute": "state",
    "value": "CA"
  },
  "insights": {
    "field": "restaurant.cuisines",
    "calculations": ["fill_count"]
  }
}'

Note:: The contract parameter is required if your account has multiple contracts. Omit it if your account has only one contract.

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://qa.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://qa.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://qa.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://qa.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. Frequencies can be nested up to three levels deep.

For example, count records by state, then by primary SIC code within each state, then by city within each SIC code:

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

Each state frequency contains its own primary_sic_code_id frequencies, and each SIC code frequency contains its own city frequencies:

{
  "count": 16028792,
  "insights": {
    "field": "state",
    "frequencies": [
      {
        "value": "CA",
        "label": "California",
        "count": 1781000,
        "insights": {
          "field": "primary_sic_code_id",
          "frequencies": [
            {
              "value": "581208",
              "label": "Restaurants",
              "count": 68420,
              "insights": {
                "field": "city",
                "frequencies": [
                  { "value": "Los Angeles", "count": 9875 },
                  { "value": "San Francisco", "count": 4310 },
                  ...
                ]
              }
            },
            ...
          ]
        }
      },
      ...
    ]
  }
}

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

Intervals

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

curl https://qa.api.data-axle.com/v1/places/insights -X GET -d '{
  "insights": {
    "field": "opened_for_business_on",
    "calculations": ["frequencies"],
    "frequency_options": {
      "interval": "day"
    }
  }
}'

{
  "count": 16028792,
  "insights": {
    "field": "opened_for_business_on",
    "frequencies": [
      {
        "lower": "2024-12-02",
        "upper": "2024-12-02",
        "count": 1
      },
      {
        "lower": "2024-12-03",
        "upper": "2024-12-03",
        "count": 1
      },
      {
        "lower": "2024-12-04",
        "upper": "2024-12-04",
        "count": 1
      },
      {
        "lower": "2024-12-05",
        "upper": "2024-12-05",
        "count": 1
      }
    ]
  }
}

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