Skip to main content

Delivery

Music Story delivers the metadata as gzipped Newline Delimited JSON files (https://jsonlines.org/).

Full deliveries are delivered once per month in the folder_ out/catalog/full_. They contain all the objects of the Music Story catalog in the following files:

  • CustomerName_Artist_YYYYMMDD.json.gz
  • CustomerName_Matching_Artist_YYYYMMDD.json.gz
  • CustomerName_Album_YYYYMMDD.json.gz
  • CustomerName_Matching_Album_YYYYMMDD.json.gz
  • CustomerName_Recording_YYYYMMDD.json.gz
  • CustomerName_Matching_Recording_YYYYMMDD.json.gz
  • CustomerName_Genre_YYYYMMDD.json.gz
  • CustomerName_Role_YYYYMMDD.json.gz
  • CustomerName_Potentially_Mixed_YYYYMMDD.json.gz
  • CustomerName_Potentially_Duplicate_YYYYMMDD.json.gz
  • CustomerName_Potentially_Multi_Artist_YYYYMMDD.json.gz

Daily deliveries are delivered every day in the folder out/catalog/inc. They contain the objects of the Music Story catalog that have been created or updated since the last delivery in the following files:

  • CustomerName_Artist_YYYYMMDD.json.gz
  • CustomerName_Matching_Artist_YYYYMMDD.json.gz
  • CustomerName_Album_YYYYMMDD.json.gz
  • CustomerName_Matching_Album_YYYYMMDD.json.gz
  • CustomerName_Recording_YYYYMMDD.json.gz
  • CustomerName_Matching_Recording_YYYYMMDD.json.gz
  • CustomerName_Genre_YYYYMMDD.json.gz
  • CustomerName_Role_YYYYMMDD.json.gz
  • CustomerName_Potentially_Mixed_YYYYMMDD.json.gz
  • CustomerName_Potentially_Duplicate_YYYYMMDD.json.gz
  • CustomerName_Potentially_Multi_Artist_YYYYMMDD.json.gz

The daily deliveries are consistent, meaning that if an object’s ID is in one of the files above, the referenced object is also in the delivery.

The daily deliveries also contain the IDs of the objects that have been deleted from the Music Story catalog in the following files:

  • CustomerName_Deleted_Artist_YYYYMMDD.json.gz
  • CustomerName_Deleted_Matching_Artist_YYYYMMDD.json.gz
  • CustomerName_Deleted_Album_YYYYMMDD.json.gz
  • CustomerName_Deleted_Matching_Album_YYYYMMDD.json.gz
  • CustomerName_Deleted_Recording_YYYYMMDD.json.gz
  • CustomerName_Deleted_Matching_Recording_YYYYMMDD.json.gz
  • CustomerName_Deleted_Genre_YYYYMMDD.json.gz
  • CustomerName_Deleted_Role_YYYYMMDD.json.gz
  • CustomerName_Deleted_Artist_Picture_YYYYMMDD.json.gz

Nb: Each .json.gz file is accompanied by a .md5 file containing its MD5 checksum for

file integrity checks.

Delivery methods need to be determined, two options are available : SFTP hosted by Music Story, or storage provided by the customer.

Option 1: SFTP hosted by Music Story

The metadata files are hosted by Music Story, and can be accessed over SFTP (SSH File Transfer Protocol) using public key authentication:

  • Hostname: sftp.music-story.com
  • Port: 2204
  • Root folder: ~/out
  • Username: ftp_customername
  • SSH public key: To be provided by the customer.

The files can be retrieved using various libraries and tools, such as SFTP, curl, etc.

For example:

$ sftp -P 2204 ftp_customername@sftp.music-story.com
Connected to sftp.music-story.com.
sftp> exit
$ sftp -P 2204 ftp_customername@sftp.music-story.com:~/out/<delivery_file> \
<destination_folder>

The metadata files are deleted from the SFTP after a month.

Option 2: Storage provided by customer

The files can be delivered on a dedicated SFTP space on our server or sent directly to many different providers such as :