Data Filters

The Luminate API allows the user to perform deeper analysis by filtering the streaming and sales data. These filters can be geography-based (see Market Filters) or activity-focused (see Streaming & Product Sales Filters).

🌆 Market Filters

All of the supported markets in the US & Canada can be used as filters for the consumption data. This is necessary because the aggregate_interval query parameter cannot be used in the same request as the markets parameter, which shows total activity for each market. Instead, the user can request a time frame (e.g. start_date=2024-09-01&end_date=2024-09-07), request daily data (aggregate_interval=day) and filter results using the markets filter (market_filter=1).

In the example above, the response structure does not change when the market_filter parameter is used, but the consumption data will only reflect the activity within Market ID 1 (New York, NY).

A list of all Market IDs can be found here.

Note: The Market ID and Location ID must correspond to retrieve the desired data.

{
  "metrics": [
    {
      "name": "Streams",
      "value": [
        {
          "name": "total",
          "value": [
            {
              "date": "2024-09-01",
              "value": 269331
            },
            {
              "date": "2024-09-02",
              "value": 287959
            },
            {
              "date": "2024-09-03",
              "value": 320724
            },
            {
              "date": "2024-09-04",
              "value": 323525
            },
            {
              "date": "2024-09-05",
              "value": 324413
            },
            {
              "date": "2024-09-06",
              "value": 326716
            },
            {
              "date": "2024-09-07",
              "value": 300545
            }
          ]
        }
      ]
    },
    {
      "name": "Sales",
      "value": [
        {
          "name": "Song Sales",
          "value": [
            {
              "name": "total",
              "value": [
                {
                  "date": "2024-09-01",
                  "value": 38
                },
                {
                  "date": "2024-09-02",
                  "value": 47
                },
                {
                  "date": "2024-09-03",
                  "value": 27
                },
                {
                  "date": "2024-09-04",
                  "value": 24
                },
                {
                  "date": "2024-09-05",
                  "value": 45
                },
                {
                  "date": "2024-09-06",
                  "value": 66
                },
                {
                  "date": "2024-09-07",
                  "value": 62
                }
              ]
            }
          ]
        },
        {
          "name": "Product Sales",
          "value": [
            {
              "name": "total",
              "value": [
                {
                  "date": "2024-09-01",
                  "value": 2
                },
                {
                  "date": "2024-09-02",
                  "value": 13
                },
                {
                  "date": "2024-09-03",
                  "value": 9
                },
                {
                  "date": "2024-09-04",
                  "value": 15
                },
                {
                  "date": "2024-09-05",
                  "value": 6
                },
                {
                  "date": "2024-09-06",
                  "value": 6
                },
                {
                  "date": "2024-09-07",
                  "value": 15
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

🎵 Streaming Filters

As mentioned in the Getting Started documentation, the Luminate API provides access to streaming breakouts, which provide further insight into how the audience listens to the specified ID. Each of the breakouts can be used as a filter to manipulate the streaming data. For example, the user can filter by audio-based streams, (content_type=audio), on-demand steams (service_type=on_demand), or both (content_type=audio&service_type=on_demand). All of the streaming values will then reflect the selected filters.

Below is a list of the streaming filters and their corresponding values:

  • content_type
    • audio
    • video
  • commercial_model
    • premium
    • ad_supported
  • service_type
    • programmed
    • on_demand

Note: Content Type data (audio, video) is only available in the following Location IDs: US, CA, AA.

{
  "metrics": [
    {
      "name": "Streams",
      "value": [
        {
          "name": "total",
          "value": 18036036
        },
        {
          "name": "commercial_model",
          "value": [
            {
              "name": "ad_supported",
              "value": 1419881
            },
            {
              "name": "premium",
              "value": 16616155
            }
          ]
        },
        {
          "name": "content_type",
          "value": [
            {
              "name": "audio",
              "value": 18036036
            },
            {
              "name": "video",
              "value": 0
            }
          ]
        },
        {
          "name": "service_type",
          "value": [
            {
              "name": "on_demand",
              "value": 18036036
            },
            {
              "name": "programmed",
              "value": 0
            }
          ]
        }
      ]
    }
  ]
}

💽 Product Sales Filters

Just like the streaming data, the product sales data can be filtered using the applicable breakouts. For example, the the purchase_method filter can be used to reflect purchases made via the web (purchase_method=online).

Below is a list of the product sales filters and their corresponding values:

  • distribution_channel
    • digital
    • physical
  • purchase_method
    • online
    • storefront
  • store_strata
    • e-commerce
    • mass_market
    • independent
    • direct_to_consumer
    • venue
    • non-traditional

Note: Product Sales data is only available in the following Location IDs: US, CA.

{
  "metrics": [
    {
      "name": "Sales",
      "value": [
        {
          "name": "Product Sales",
          "value": [
            {
              "name": "total",
              "value": 410
            },
            {
              "name": "distribution_channel",
              "value": [
                {
                  "name": "digital",
                  "value": 112
                },
                {
                  "name": "physical",
                  "value": 298
                }
              ]
            },
            {
              "name": "store_strata",
              "value": [
                {
                  "name": "e-commerce",
                  "value": 351
                },
                {
                  "name": "mass_market",
                  "value": 32
                },
                {
                  "name": "independent",
                  "value": 2
                },
                {
                  "name": "direct_to_consumer",
                  "value": 0
                },
                {
                  "name": "venue",
                  "value": 0
                },
                {
                  "name": "non-traditional",
                  "value": 25
                }
              ]
            },
            {
              "name": "purchase_method",
              "value": [
                {
                  "name": "online",
                  "value": 410
                },
                {
                  "name": "storefront",
                  "value": 0
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}