---
updatedAt: 2025-09-30T22:28:25.000Z
agentTools:
  projectIndex: https://docs.luminatedata.com/llms.txt
---

# Data Filters

The Luminate Music API allows the user to perform deeper analysis by filtering the consumption data. These filters can be geography-based (see Market Filters) or activity-focused (see Streaming, Product Sales, and Airplay Format 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](https://docs.luminatedata.com/docs/market-ids#/). The `market_id` and `location_id` must correspond to retrieve the desired data.

**Note**: Market-level data is only available in the following Location IDs: US, CA. The market filters do no impact the ATD values.

```json market_filter=1
{
  "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](https://docs.luminatedata.com/docs/getting-started), the Luminate Music 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.

```json content_type=audio&service_type=on_demand
{
  "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`
* `product_format`
  * `cd`
  * `cassette`
  * `vinyl`
  * `mxcd`
  * `digital`
  * `dvd`
  * `vhs`
  * `laser`
  * `unknown`
* `release_type`
  * `album`
  * `single`
  * `ep`
  * `video`
  * `playlist`
  * `unknown`

**Note**: Product Sales data is only available in the following Location IDs: US, CA. The `release_type` breakout is only available in the `/artists` endpoint.

```json distribution_channel=digital
{
  "metrics": [
    {
      "name": "Sales",
      "value": [
        {
          "name": "Product Sales",
          "value": [
            {
              "name": "total",
              "value": 1126
            },
            {
              "name": "distribution_channel",
              "value": [
                {
                  "name": "digital",
                  "value": 1126
                },
                {
                  "name": "physical",
                  "value": 0
                }
              ]
            },
            {
              "name": "store_strata",
              "value": [
                {
                  "name": "e-commerce",
                  "value": 1036
                },
                {
                  "name": "mass_market",
                  "value": 0
                },
                {
                  "name": "independent",
                  "value": 0
                },
                {
                  "name": "direct_to_consumer",
                  "value": 90
                },
                {
                  "name": "venue",
                  "value": 0
                },
                {
                  "name": "non-traditional",
                  "value": 0
                }
              ]
            },
            {
              "name": "purchase_method",
              "value": [
                {
                  "name": "online",
                  "value": 1126
                },
                {
                  "name": "storefront",
                  "value": 0
                }
              ]
            },
            {
              "name": "product_format",
              "value": [
                {
                  "name": "cd",
                  "value": 0
                },
                {
                  "name": "vinyl",
                  "value": 0
                },
                {
                  "name": "mxcd",
                  "value": 0
                },
                {
                  "name": "cassette",
                  "value": 0
                },
                {
                  "name": "vhs",
                  "value": 0
                },
                {
                  "name": "dvd",
                  "value": 0
                },
                {
                  "name": "laser",
                  "value": 0
                },
                {
                  "name": "digital",
                  "value": 1126
                },
                {
                  "name": "unknown",
                  "value": 0
                }
              ]
            },
            {
              "name": "release_type",
              "value": [
                {
                  "name": "album",
                  "value": 1113
                },
                {
                  "name": "single",
                  "value": 13
                },
                {
                  "name": "ep",
                  "value": 0
                },
                {
                  "name": "video",
                  "value": 0
                },
                {
                  "name": "playlist",
                  "value": 0
                },
                {
                  "name": "unknown",
                  "value": 0
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

# 📻 Airplay Format Filters

The `audience` and `spins` activities nested within the `airplay` metric can be filtered using the `airplay_format_filter` parameter. A list of all Format IDs can be found [here](https://docs.luminatedata.com/docs/airplay-format-ids#/).

Airplay data can be found in the following endpoints:

* `/songs`
* `/musical_release_groups`
* `/artists `

In the example below, all of the airplay activity is filtered by the "Country" format.

**Note**: Airplay data is only available in the following Location IDs: US, CA. The `airplay_format_filter` query parameter will not impact the `atd` values for `spins` and `audience`.

```json format_id=CW
{
  "metrics": [
    {
      "name": "Airplay",
      "value": [
        {
          "name": "Audience",
          "value": [
            {
              "name": "total",
              "value": [
                {
                  "date": "2025-01-01",
                  "value": 3817900
                },
                {
                  "date": "2025-01-02",
                  "value": 4032700
                },
                {
                  "date": "2025-01-03",
                  "value": 4097300
                },
                {
                  "date": "2025-01-04",
                  "value": 4430600
                },
                {
                  "date": "2025-01-05",
                  "value": 4021200
                },
                {
                  "date": "2025-01-06",
                  "value": 4087000
                }
              ]
            }
          ]
        },
        {
          "name": "Spins",
          "value": [
            {
              "name": "total",
              "value": [
                {
                  "date": "2025-01-01",
                  "value": 1045
                },
                {
                  "date": "2025-01-02",
                  "value": 1100
                },
                {
                  "date": "2025-01-03",
                  "value": 1101
                },
                {
                  "date": "2025-01-04",
                  "value": 1112
                },
                {
                  "date": "2025-01-05",
                  "value": 1036
                },
                {
                  "date": "2025-01-06",
                  "value": 1078
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```