Accessing the Songtradr Pre-Cleared Catalogue

This guide will walk you through the various integration steps and options for services accessing the represented catalogue. It will guide you to the relevant API endpoints to help you integrate with the MassiveMusic platform, however please be aware that not all steps will be required and some may not be accessible under your commercial agreement.\

1. Accessing the Catalogue Metadata

1.1 Catalogue Events

The first integration step is to access the standard metadata for the catalogue. You should integrate with the Catalogue Events product, which pushes real time updates to the catalogue. The catalogue can then be stored and maintained within your own infrastructure for management of discovery and curation in your service.

Catalogue events are delivered as they're ingested by MassiveMusic, and therefore each event represents a snapshot of the release details at that time. Subsequent events should 'overwrite' the original event as they represent more recent updates to that release. There is a single event type, a Release Event. Each release event will contain metadata relating to the Artist(s), Release and Track(s) contained within that release, as well as availability data about the release.

Technical details on how to integrate with the Catalogue Events product can be found here.

1.2 Enhanced Metadata

In addition to the standard metadata available via the Catalogue Events product, you should also ingest the enhanced metadata available for the entire catalogue. Each track contains over 40 different enhanced metadata tags, and these are accessed via one of the below endpoints.

Use the following endpoint to request enhanced metadata by MassiveMusic track ID.

GET https://api.7digital.com/track/by-id/{trackId}/metadata/enhanced

PATH PARAMETER

QUERY PARAMETER

Use the following endpoint to request enhanced metadata in bulk by MassiveMusic track ID's.

POST https://api.7digital.com/track/metadata/enhanced/batch

QUERY PARAMETER

FORM DATA

2. Accessing Audio and Artwork

2.1 Downloading Audio

To download full tracks, you'll use the Media Transfer endpoint. Use the trackIDs specified in Events to identify the content you want to request. We recommend running multiple requests in parallel to expedite the download process.

To download tracks to your infrastructure, use the following endpoint:

GET https://stream.svc.7digital.net/media/transfer

QUERY PARAMETER

🚧

Error codes

• 1001 - Error: Missing "parameter name" query parameter. Not all mandatory parameters were specified in the request.
• 1002 - Invalid value for "parameter name": parameter value. Value for parameter in error message is not valid.
• 2001 - Track not found. This track isn't available for streaming in your country.

2.2 Streaming Audio

To stream tracks directly to your end users, you'll use the Stream Catalogue endpoint. Use the trackIDs specified in Events to identify the content you want to request.

Use the following endpoint to stream any track to your users:

GET https://stream.svc.7digital.net/stream/catalogue

QUERY PARAMETER

HEADER

🚧

Error Codes

1001 - Error: Missing “parameter name” query parameter - Not all mandatory parameters were specified in the request.
1002 - Invaild value for “parameter name”: parameter value - Value for parameter in error message is not valid.
2001 - Track not found - This track isn’t available for streaming in your country or shop.
2002 - Pre-release or subscription availability - Either the user does not have a valid subscription account with us, or the track is not available for streaming (note that streaming release dates may differ from download or catalogue streaming release dates).
3201 - Simultaneous stream requests from multiple locations - streaming access temporarily disabled - When the clientId parameter is supplied, multiple devices will not be allowed to stream concurrently (see endpoint description above for more information).

2.3 Downloading Artwork

Artwork can be download in a range of different dimensions. Release level cover art images are available in the following dimensions:

• 33 pixels
• 50 pixels
• 100 pixels
• 180 pixels
• 182 pixels
• 200 pixels
• 350 pixels
• 500 pixels
• 800 pixels
• 1400* pixels
• 3000* pixels

*1400px and 3000px images are only being stored or generated when licensors send these sizes (or higher) to us. We made the change to include these sizes in our artwork offering in February 2025 so in order to provide higher-quality images for legacy catalogue, we may need licensors to re-deliver the images to us where available.

If a requested size is unavailable, a placeholder image will be provided. We recommend implementing fallback logic if you receive a placeholder image so that you fall back through decreasing image sizes until the image is correctly returned.

The size of images returned by any API response can be adjusted to another available size by adding imageSize parameter to the request. Artwork can be access at the below url and by specifying the MassiveMusic release ID and image size in the format described in the example request further below.

http://artwork-cdn.7static.com/static/img/sleeveart/

PATH PARAMETER

http://artwork-cdn.7static.com/static/img/sleeveart/00/389/232/0038923246_350.jpg

3. Reporting usage back to rightsholders

Rightsholders require usage data to be reported back to them, as determined by your licensing agreements. To enable MassiveMusic to manage rightsholder reporting, you must log usage data back to MassiveMusic.

📘

Information about logging activity

• All tracks listened to when the device is offline must be reported as soon as Internet connectivity is restored

There are 2 options for logging usage data back to MassiveMusic. You can either integrate with the logging API and log usage regularly. We recommend logging usage no less often than once every 24 hours. Alternatively you can integrate with the plays logger method, allowing you to deliver a monthly file to an S3 bucket.

POST https://api.7digital.com/1.2/user/catalogue/log

3.1 Logging API

If integrating with the logging API then multiple plays can be batched into a single POST to the subscription/log endpoint and the body can be sent in either XML or JSON formats, subject to acceptable usage.

QUERY PARAMETER

FORM DATA

3.2 Plays Logger

The plays logger is a mechanism that allows you to send usage logs via a PARQUET file to a MassiveMusic S3 bucket. By adhering to these specifications, you'll ensure that your data integrates seamlessly with our system.

Prerequisites

Before getting started with the Logger, please ensure that you have the following:

• Access credentials provided by MassiveMusic (Access Key and Secret Key) to access our S3 bucket.
• Familiarity with the PARQUET file format.
• MassiveMusic Partner ID (to be provided by MassiveMusic)

Log file

To ensure seamless integration, pay attention to three critical aspects of your data:

• Fields (Columns): The naming, case, spelling, and ordering of the columns in your file must match the exact specifications provided below.
• Data Types (Rows): Ensure that the data types in each cell match the specified types listed below.
• Values (Rows): The values in your data must adhere to the acceptable and valid formats detailed in this documentation.

Schema and Column Specifications

Your Parquet file should follow this schema with precise column names and data types:

|-- id: uuid (required)

• A globally unique identifier string, produced programmatically by a FUNCTION.

|-- datetimelogged: string (required)

• Not empty or NULL.
• Date permitted period = time now - 61 days.

|-- userid: string (required)

• Not empty or NULL.

|-- trackid: string (required)

• Not empty or NULL.
• Greater than 0.

|-- releaseid: string (required)

• Not empty or NULL.
• Greater than 0.

|-- formatid: string (required)

• Not empty or NULL.
• Greater than 0.

|-- datetimeplayed: string (required)

• Not empty or NULL.
• Date permitted period = time now - 61 days.

|-- totaltimeplayed: bigint (required)

• Not empty or NULL.
• Greater than or equal to 0.

|-- useragent: string (required)

• Not empty or NULL.
• Maximum 255 characters.

|-- transactionid: string (required)

• Not empty, but can be NULL for all records.
• Greater than or equal to 0.

|-- partnerid: string (required)

• Not empty or NULL.
• Greater than or equal to 0.

|-- shopid: string (required)

• can be NULL for all records

|-- endreason: string (required)

• Not empty or NULL.
• Permitted values: "naturalEnd", "userSkipped", or "other".

|-- country: string (required)

• Not empty or NULL.
• Length = 2.
• Permitted countries: Seehere

Example Row Representation

Here's an example of a row in your log file, adhering to the specified schema and requirements

{
  "id": "e9fcaaa9-854b-44b7-bbd8-6a5072f286e2",
  "datetimelogged": "2024-02-22T18:16:33.9293255Z",
  "userid": "12345-abcd-6789-efghijk",
  "trackid": "145213707",
  "releaseid": "19699577",
  "formatid": "55",
  "datetimeplayed": "2024-02-21T13:13:15.674",
  "totaltimeplayed": 194,
  "useragent": "Mozilla/5.0 (Linux; Android 7.0; SM)”,
  "shopid": null,
  "endreason": "naturalEnd",
  "country": "GB"
}

Delivery to Our S3 Bucket

To deliver the logs to our S3 bucket, please follow these steps:

1. Access Credentials: Use the provided Access Key and Secret Key to authenticate your requests to our S3 bucket.
2. Delivery Path: Specify the designated delivery path within our S3 bucket where the logs should be uploaded.

• PARQUET files containing logs should be written here:
  s3://7digital-glue-data-prod/receipts/radio/(partnerID)/

3. File Naming Convention:
   YYYY-MM-DD_YOURPARTNERIDHERE_NONSUBSTREAM_FILENUMBERINSERIES.parquet
   Example: 2024-01-12_12345_NONSUBSTREAM_000000000001.parquet

4. Frequency: Daily usage

Troubleshooting

If there's an error in one of the files you submit we will notify you.

We will notify you should you be required to resubmit logs, please use the designated delivery paths to submit the revised logs once the error has been fixed.

• PARQUET files containing resubmitted logs should be written here:
  s3://7digital-glue-data-prod/failures/nonsubstream/(partnerID)/YYYY-MM-DD/

File Naming Convention:
YYYY-MM-DD_NUMBERINSERIES.parquet
Example: 2023-06-12_000000000001.parquet