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:

  1. Click Users and Access in iTunes Connect.

    iTC Homepage
  2. Click Keys.

    Keys
  3. To add a new user, click the plus sign (+).

    User and Access Keys
  4. 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.

    Generate API Key
    Johnny Appleseed Admin
  5. Click Generate. The new user will appear in the Active list.

    Johnny Appleseed Active
    Download API Key

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.

Keys and Issuer ID

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:

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:

  1. 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.

  2. Test the JWT by generating a curl request (for example, curl -H “Authorization: Bearer {insert full JWT} “) https://musicanalytics.apple.com/v4/queries.

  3. 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.

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.