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
}
]
}
]
}
]
}
]
}
Updated about 2 months ago