Trends, data feeds & data processing

Last updated 9 days ago

Setting up a new data feed in Trends

If you have subscribed to our Trends service, you can request the addition of a new data feed/source by reaching out to your Business representative at Labelcamp team providing technical details or documentation, a contact in the relevant DSP team and the nature of your contract (i.e. Merlin, direct, etc.). Your request will then be reviewed our team, considering its contractual frame and technical feasibility.

If approved, you will be asked to provide your company’s credentials to access the DSP’s data API or the server directory where your data reports are uploaded.

You may also be requested to perform certain actions with your CMS account of this DSP to allow the retrieval of data by the Labelcamp’s system.

Data ingestion and processing

Daily consumption data are displayed in Trends with a limited delay period, covering the download of the DSP data reports (whose time of release may vary from one source to another), its ingestion and processing in our analytics database before being made available in the Trends user interface.

Additional delays and gaps in data can occasionally occur for various reasons beyond Labelcamp’s control (e.g. data not released by the source, unexpected variation of the format of data export, etc.).

You can flag any issue of this sort by reaching out to Labelcamp’s team at help@labelcamp.io so we can investigate the issue.

Data JSON export

A distributor can get a daily export of its Trends data in a Google Cloud Storage bucket. Please reach out to your business contact for more information.

The export is made of two distinct files:

Trends file: consumption events (streams, downloads, copy scans, content productions).
Engagement file: engagement events, currently saves, for the DSPs that report them.

File description

Files are exported daily in json new line format (more information here: https://jsonlines.org/).

Each day, a new export is available and available in a Google Cloud storage bucket (more information here: https://cloud.google.com/products/storage).

Files are named as is :

gs://<bucket>/<distributor>trends_extract<timestamp>.json_<partnumber>
gs://<bucket>/<distributor>trends_engagement_extract<timestamp>.json_<partnumber>

partnumber - Depending on the size of the export, the files can be splitted in many parts. Customer should take care of importing all parts available.

timestamp - the timestamp refers to the day the events were indexed in our db. Events inside are always older than the timestamp so you should only refer to transaction_date to know when an event occured.

Trends file: content description

field	description
eq_track_quantity	Nb of tracks consumed for this event (ie. 10 for an album of 5 tracks with 2 quantities)
quantity	Nb of events
product_age	Age of the release at the date of the event (in days)
artists	Array of artists names
played_percent	Percent of the track played
played_seconds	Playback time of the track in seconds
gender	Gender ID
birth_year	Birth year of the listener
user_id	DSP ID of the listener
transaction_date	Date of the event
creator	Creator ID
source	Source ID
playlist_xid	DSP ID of the playlist
retail_id	Retail ID
retail_name	Retail name
company_id	Company ID
company_name	Company Name
label_id	Label ID
label_name	Label Name
product_id	Product ID
product_name	Product Name
product_upc_code	Product UPC code
track_id	Track ID
track_name	Track name
track_subtitle	Track subtitle
track_artists	Track performers as a string
isrc_code	ISRC Code
video_name	Video name
territory_id	Territory ID
territory_name	Territory Name
code_alpha_2	Territory alpha code (2 letters)
product_genre_name	Genre name
product_subgenre_name	Subgenre name
product_genre_id	Genre ID
product_subgenre_id	Subgenre ID
gender_name	Gender name (Male, Female)
creator_name	Type of context (Automated, Editorial, User)
source_name	Context name (Artist or Album, Library, Playlist, Radio, Search)
playlist_name	Playlist name
playlist_curator	Playlist curator name
use_type	Type of usage for the event (stream, download, copy_scan, content_production)
city_name	Name of the listener's city
raw_dsp_data	Full verbatim row from the DSP source file as received, serialized to JSON before any transformation or enrichment. May overlap with other columns in the record.

Sample

{
  "eq_track_quantity": "1",
  "quantity": "1",
  "product_age": "191289600",
  "artists": [
    "Lorem Ipsum"
  ],
  "played_percent": 1,
  "played_seconds": "249",
  "gender": "1",
  "birth_year": "1976",
  "user_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "transaction_date": "2026-03-22",
  "creator": "3",
  "source": "4",
  "retail_id": "10001",
  "company_id": "100001",
  "label_id": "200001",
  "use_type": "stream",
  "product_id": "300001",
  "track_id": "400001",
  "territory_id": "150",
  "product_genre_id": "6",
  "product_subgenre_id": "38321",
  "raw_dsp_data": {
    "audio_format": "Vorbis 96 kbps",
    "cached": false,
    "completion_flag": true,
    "content_type_flag": "audio",
    "country": "MX",
    "device_type": "cell phone",
    "discovery_flag": true,
    "is_canvas_viewed": false,
    "is_lyrics_viewed": false,
    "is_promoted_context": false,
    "length": 249,
    "message": "APIStreamData",
    "os": "Android",
    "repeat_play": false,
    "shuffle": true,
    "source": "others_playlist",
    "source_uri": "",
    "timestamp": "20260322T16:28:00",
    "track_id": "f00000000000000000000000000000aa",
    "user_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "utc_timestamp_offset": "-05:00",
    "version": 4
  },
  "retail_name": "Spotify",
  "company_name": "Lorem Company A",
  "label_name": "Lorem Label A",
  "product_name": "Lorem Album A",
  "product_upc_code": "5000000000001",
  "track_name": "Lorem Track A",
  "track_subtitle": "Lorem",
  "track_artists": "Lorem Ipsum",
  "isrc_code": "LRXX0000001",
  "territory_name": "Mexico",
  "code_alpha_2": "MX",
  "product_genre_name": "World",
  "product_subgenre_name": "Latin",
  "gender_name": "Male",
  "creator_name": "Automated",
  "source_name": "Playlist"
}

{
  "eq_track_quantity": "1",
  "quantity": "1",
  "product_age": "221184000",
  "artists": [
    "Dolor Sit Amet"
  ],
  "transaction_date": "2026-03-23",
  "creator": "1",
  "source": "3",
  "retail_id": "10002",
  "company_id": "100002",
  "label_id": "200002",
  "use_type": "stream",
  "product_id": "300002",
  "track_id": "400002",
  "territory_id": "223",
  "product_genre_id": "4",
  "product_subgenre_id": "38304",
  "raw_dsp_data": {
    "Apple_Identifier": 1000000001,
    "Audio_Format": "Compressed Audio",
    "Channel_Partner": null,
    "Container_ID": null,
    "Container_Name": null,
    "Container_Sub_Type": 1,
    "Container_Type": 2,
    "Datestamp": "2026-03-23",
    "Device_Type": 1,
    "End_Reason_Type": 0,
    "Ingest_Datestamp": "2026-03-23",
    "Offline": 0,
    "Source_of_Stream": 1,
    "Storefront_Name": "US",
    "Streams": 1,
    "Subscription_Mode": "PAID",
    "Subscription_Type": "Apple One Premier Monthly",
    "Time_Bucket": 5
  },
  "retail_name": "Apple Music",
  "company_name": "Lorem Company B",
  "label_name": "Lorem Label B",
  "product_name": "Lorem Album B",
  "product_upc_code": "5000000000002",
  "track_name": "Lorem Track B",
  "track_subtitle": "Lorem",
  "track_artists": "Dolor Sit Amet",
  "isrc_code": "LRXX0000002",
  "territory_name": "United States",
  "code_alpha_2": "US",
  "product_genre_name": "Electronic",
  "product_subgenre_name": "Electronic",
  "creator_name": "User",
  "source_name": "Library"
}

{
  "eq_track_quantity": "1",
  "quantity": "1",
  "product_age": "224035200",
  "artists": [
    "Consectetur Adipiscing"
  ],
  "played_percent": 1,
  "played_seconds": "246",
  "gender": "1",
  "birth_year": "1973",
  "user_id": "b3c4d5e6f7a8b3c4d5e6f7a8b3c4d5e6f7a8b3c4d5e6f7a8b3c4d5e6f7a8b3c4",
  "transaction_date": "2026-03-23",
  "creator": "1",
  "source": "4",
  "retail_id": "10003",
  "company_id": "100003",
  "label_id": "200003",
  "use_type": "stream",
  "product_id": "300003",
  "track_id": "400003",
  "territory_id": "29",
  "product_genre_id": "6",
  "product_subgenre_id": "38294",
  "raw_dsp_data": {
    "Album": "Lorem Album C",
    "Artist": "Consectetur Adipiscing",
    "Birth_year": 1973,
    "Cached_play": 0,
    "Context_type": "playlist",
    "Country": "BR",
    "Device_type": "mobile",
    "END_REPORT": "23-03-2026",
    "Gender": "M",
    "ISRC": "LRXX0000003",
    "Label": "Lorem Label C",
    "Nb_of_Plays": 1,
    "OS": "android",
    "Play_percent": 100,
    "Playlist_Id": "9000000001",
    "Playlist_name": "Lorem Playlist C",
    "Provider": "Lorem distributor (MERLIN)",
    "Royalties": 0,
    "START_REPORT": "23-03-2026",
    "Service": "BPP",
    "Service_name": "TIM BR Premium+ Bundle. 1 device",
    "Title": "Lorem Track C",
    "Track_duration": 246,
    "UPC": 5000000000003,
    "User_id": "b3c4d5e6f7a8b3c4d5e6f7a8b3c4d5e6f7a8b3c4d5e6f7a8b3c4d5e6f7a8b3c4",
    "provider_id": 55
  },
  "retail_name": "Deezer",
  "company_name": "Lorem Company C",
  "label_name": "Lorem Label C",
  "product_name": "Lorem Album C",
  "product_upc_code": "5000000000003",
  "track_name": "Lorem Track C",
  "track_subtitle": "",
  "track_artists": "Consectetur Adipiscing",
  "isrc_code": "LRXX0000003",
  "territory_name": "Brazil",
  "code_alpha_2": "BR",
  "product_genre_name": "World",
  "product_subgenre_name": "Brazilian",
  "gender_name": "Male",
  "creator_name": "User",
  "source_name": "Playlist"
}

Engagement JSON export

Alongside the Trends export, a second daily file contains engagement data, which today means saves: users adding a track to their library or to a playlist. Saves are not reported by every DSP, so this export only covers the sources that provide them.

Engagement file: content description

engagement_type_id	Type of engagement. 1 = save
quantity	Nb of engagement
eq_track_quantity	Nb of tracks engaged for this row (same as quantity for track saves)
transaction_date	Date of the engagement
import_date	Date the engagement was imported in our database
product_age	Age of the release at the date of the engagement (in seconds)
artists	Array of artists names
retail_id	Retail ID
retail_name	Retail name
company_id	Company ID
company_name	Company name
label_id	Label ID
label_name	Label name
product_id	Product ID
product_name	Product name
product_upc_code	Product UPC code
track_id	Track ID
track_name	Track name
track_subtitle	Track subtitle
track_artists	Track performers as a string
isrc_code	ISRC code
video_id	Video ID
video_name	Video name
territory_id	Territory ID
territory_name	Territory Name
code_alpha_2	Terriroty alpha code (2 letters)
product_genre_id	Genre ID
product_genre_name	Genre name
product_subgenre_id	Subgenre ID
product_subgenre_name	Subgenre name
raw_dsp_data	Full verbatim record from the DSP source as received, serialized to JSON before any transformation or enrichment. A DSP record can cover several territories: each territory becomes one row in the export, and every one of these rows carries the whole record. Use territory_id / code_alpha_2 for the territory of the row.

Spotify saves: each save is counted once per user and per track, whether the track was added to the library or to a playlist. Spotify does not report removals, so these are gross figures and can be higher than the saves shown in Spotify for Artists, which splits library saves and playlist adds into separate charts.

Sample

{
  "company_id": "100001",
  "track_id": "400001",
  "product_id": "300001",
  "label_id": "200001",
  "video_id": null,
  "territory_id": "29",
  "quantity": "1",
  "eq_track_quantity": "1",
  "engagement_type_id": "1",
  "artists": [
    "Lorem Ipsum"
  ],
  "transaction_date": "2026-09-26",
  "import_date": "2026-09-27",
  "raw_dsp_data": {
    "date": "2026-09-26",
    "saves": {
      "country": {
        "BR": { "product": { "premium": 1 }, "total": 1 }
      },
      "total": 1
    },
    "trackv2": {
      "href": "spotify:track:0000000000000000000001",
      "isrc": "LRXX0000001"
    }
  },
  "retail_id": "10001",
  "product_genre_id": "28",
  "product_subgenre_id": "38336",
  "product_age": "153619200",
  "retail_name": "Spotify",
  "company_name": "Lorem Company A",
  "label_name": "Lorem Label A",
  "product_name": "Lorem Album A",
  "product_upc_code": "5000000000001",
  "track_name": "Lorem Track A",
  "track_subtitle": null,
  "track_artists": "Lorem Ipsum",
  "isrc_code": "LRXX0000001",
  "video_name": null,
  "territory_name": "Brazil",
  "code_alpha_2": "BR",
  "product_genre_name": "Singer/Songwriter / Folk",
  "product_subgenre_name": "Singer/Songwriter"
}

{
  "company_id": "100002",
  "track_id": "400002",
  "product_id": "300002",
  "label_id": "200002",
  "video_id": null,
  "territory_id": "223",
  "territory_id": "223",
  "quantity": "7",
  "eq_track_quantity": "7",
  "engagement_type_id": "1",
  "artists": [
    "Dolor Sit Amet"
  ],
  "transaction_date": "2026-09-26",
  "import_date": "2026-09-27",
  "raw_dsp_data": {
    "date": "2026-09-26",
    "saves": {
      "country": {
        "GB": { "product": {}, "total": 0 },
        "US": { "product": { "free": 7 }, "total": 7 }
      },
      "total": 7
    },
    "trackv2": {
      "href": "spotify:track:0000000000000000000002",
      "isrc": "LRXX0000002"
    }
  },
  "retail_id": "10001",
  "product_genre_id": "3",
  "product_subgenre_id": "38287",
  "product_age": "33955200",
  "retail_name": "Spotify",
  "company_name": "Lorem Company B",
  "label_name": "Lorem Label B",
  "product_name": "Lorem Album B",
  "product_upc_code": "5000000000002",
  "track_name": "Lorem Track B",
  "track_subtitle": null,
  "track_artists": "Dolor Sit Amet",
  "isrc_code": "LRXX0000002",
  "video_name": null,
  "territory_name": "United States",
  "code_alpha_2": "US",
  "product_genre_name": "Alternative/Indie",
  "product_subgenre_name": "Alternative"
}

Retention

Files are stored for 90 days on the bucket.

Please get in touch with your usual business representative if you wish to subscribe to this additional service.

Was this helpful?

Still need help? Ask the team