Overview
This document serves as a guide to assist Music Analytics API users with onboarding and authorizing new users, privacy requirements, and endpoint descriptions. Check out some frequently asked questions for more information.
What’s New In This Version
July 2025
Container Sub-Types for Apple Music Mood Stations have been added to all Audience endpoints of the Music Analytics API. There is no change to your Music Analytics API version.
June 2025
Group By date dimension has been added to all Audience endpoints in the Music Analytics API. There is no change to your Music Analytics API version.
February 2025
Container Type has been added to the Music Analytics API and the “Flagged Streams” report, updating the version of the “Flagged Streams” report to v3. There is no change to your Music Analytics API version.
November 2023
The new Apple Music “Flagged Streams” and “In Review Content” Reports related to stream manipulation are now available and accessible through their new endpoints
Onboarding New Users
Add new users to the Music Analytics API by taking the following steps:
Click Users and Access in iTunes Connect.
Click Keys.
To add a new user, click the plus sign (+).
When the Generate API Key dialog appears, enter the user’s name (for example, Johnny Appleseed) and choose between Admin or Technical in the Access field. At this time, there is no difference between the two roles.
Click Generate. The new user will appear in the Active list.
If the API Key hasn’t been downloaded, click the Download API Key link, store it in a safe location, and back up as needed.
NOTE: Unique to the user or shared group (like a generic team email), you can only download an API Key one time. If a user key has been lost or compromised, the user should be removed and added as a new user again.
Once you’ve generated or downloaded your API Key, return to the Keys page to find an Issuer ID. This 36-character alphanumeric sequence is unique to the content provider and is required for users to log in to the Music Analytics API.
Authorization
Once a user is added to the Music Analytics API tool, ensure they appear in the Keys Active list and have access to the following upon executing:
The musicanalytics-utils-0.2.0.jar file
NOTE: Before using this script, make sure you have Java 8.0 or later, and the Java Development Kit (JDK) installed.
A separate private key file (for example, AuthKey_1234567890.p8)
Issuer ID (Located above the Active list, this 36-character alphanumeric sequence is unique to the content provider and is required for users to log in to the Music Analytics API.)
Once you have all of the items above, use a command prompt program (for example, Terminal in macOS or equivalent third-party program), navigate to the file directory, and complete the following steps:
Execute the musicanalytics-utils-0.2.0.jar file by typing: java -jar musicanalytics- utils-0.2.0.jar -c {insert value for Issuer ID} -f {insert file name for your private key file}. You will receive a JSON Web Token (JWT), a string of 270 case-sensitive characters that will require testing.
NOTE : The JWT will only be available for 20 minutes. If the JWT expires, complete step 1 again to renew the token.
Test the JWT by generating a curl request (for example, curl -H “Authorization: Bearer {insert full JWT} “) https://musicanalytics.apple.com/v4/queries.
If successful, you will receive a 200 HTTP status code that will enable users to access the Music Analytics API.
To better understand the Music Analytics API, we suggest reviewing examples of requests and responses, as well as the API schema. You can issue authenticated GET requests to see these. More information is available in Endpoint Descriptions.
Privacy Requirements
The Music Analytics API provides results once listeners or play counts cross the minimum thresholds. Attempts to de-anonymize data from the product are strictly prohibited and may result in suspension or revocation of access.
Endpoint Descriptions
Every endpoint will have a GET and POST function. The base URL for every function is https://musicanalytics.apple.com/v4/queries/.
Only authorized users will receive and have access to the GET or POST function results.
GET functions provide the schema of returned fields and applicable ranges that can be used.
POST functions provide live results based on the criteria you select.
If a user receives a response other than a 200 HTTP status code, they are likely not authorized and should perform the authentication steps above.
Upon successful authorization to the Music Analytics API, we highly suggest performing GET requests on all available query paths. The response will include available dimensions, example queries, and more.
Audience Engagement
GET/POST: https://musicanalytics.apple.com/v4/queries/audience-engagement
Allows queries for specific containers where listeners discovered content.
This buckets aggregated counts of unique listeners and plays for a specified artist, album, or song alongside optional fields of where and how the listener engaged with the content on Apple Music. Examples include End Reason Type, Source of Stream, Container Sub-Type, and more.
Audience Overlap
GET/POST: https://musicanalytics.apple.com/v4/queries/audience-overlap
Provides counts of listeners and plays by dimension, and allows queries for specific containers where listeners discovered content. It cohorts listeners, analyzes an artist, album, or song, and compares their listenership against two periods of time.
Field Name | Common Field Name | Definition | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
primary_audience_lc | Primary Audience Listener Count | The total cohorted count of listeners who meet the criteria specified in time period 1 | |||||||||
primary_difference_lc | Primary Difference Listener Count | The total cohorted count of listeners who meet the criteria specified in time period 1 and do not meet the criteria specified in time period 2 | |||||||||
captured_lc | Captured Listener Count | The total cohorted count of listeners who meet the criteria specified in time period 1 and meet the criteria specified in time period 2 | |||||||||
secondary_audience_lc | Secondary Audience Listener Count | The total cohorted count of listeners who meet the criteria specified in time period 2 | |||||||||
primary_audience_pc | Primary Audience Play Count | The total count of plays from the Primary Audience Listener Count pertaining to time period 1 | |||||||||
primary_difference_pc | Primary Difference Play Count | The total count of plays from the Primary Difference Listener Count pertaining to time period 1 | |||||||||
primary_captured_pc | Primary Captured Play Count | The total count of plays from the Captured Listener Count pertaining to time period 1 | |||||||||
secondary_captured_pc | Secondary Captured Play Count | The total count of plays from the Captured Listener Count pertaining to time period 2 | |||||||||
secondary_audience_pc | Secondary Audience Play Count | The total count of plays from the Secondary Audience Listener Count pertaining to time period 2 | |||||||||
City
GET/POST: https://musicanalytics.apple.com/v4/city
Provides a reference of consumer_city (IDs) to consumer_city_name mappings. It also gives users the ability to filter by a specific consumer_city ID to obtain the consumer_city_name of the input values.
Flagged Streams
GET: https://musicanalytics.apple.com/reports/flagged-streams/v3
Provides standard reporting fields for all content streams that have been flagged.
In Review Content
GET: https://musicanalytics.apple.com/reports/in-review-content/v2
Provides standard reporting fields for albums currently flagged for review.
Excluded Streams
GET: https://musicanalytics.apple.com/reports/excluded-streams/v2
Provides a monthly summary of all content that has been excluded from royalty-bearing reporting and calculations.