Qobuz Official API documentation
Latest commit 1b0f311 Nov 14, 2017 @cnguyen-qobuz cnguyen-qobuz Update search.md
Permalink
Failed to load latest commit information.
consoles Dear API, you deserve a better documentation. KR. Nov 28, 2012
endpoints Update search.md Nov 14, 2017
README.md encadré du content-type Jun 14, 2017

README.md

Qobuz API Documentation (ver. 0.2)

Overview

This documentation is a global approach of Qobuz Application Programming Interface (API). It shows our technical philosophy destinated to third party partners who want to interact with Qobuz online music services.

Qobuz is a Paris (France) based online music service providing a high quality (lossless) music store (per track/album download) and a streaming music service (on a subscription basis). Qobuz is the only lossless (FLAC 16-bit / 44.1 kHz) streaming service and also have the largest high resolution 24-bit (up to 192 kHz) music catalogue which makes it the best online music source in the world. The whole catalogue is today available in France, Belgium, Luxembourg, Switzerland, United Kingdom, Ireland, Netherlands, Germany and Austria.

Please bear in mind that this document is a draft. If you would like to get more information, please contact api@qobuz.com

Apps & UX Guidelines

You will find our brand new Apps & UX Guidelines For Partners documentation here : http://static.qobuz.com/apps/api/Qobuz-AppsGuidelines-V1.0.pdf

API Endpoint

http://www.qobuz.com/api.{format}/{version}/
  • Available formats : json, xml
  • Current version number : 0.2

API use and application authentification

In order to use our API, you need to authenticate your application by sending an application ID parameter expressed as app_id along with method specific arguments to the root endpoint for all API calls. Please contact api@qobuz.com to request your application credentials (app_id and app_secret values). Don't forget to provide us with your Qobuz login or email.

Example

http://www.qobuz.com/api.json/0.2/status/test?app_id=100000000

Disclaimer : Please note that your app_id and app_secret are strictly personal and should not be given to any other parties without the explicit consent of Qobuz.

You must make sure that the email address associated with your developer account (ie the account associated with the app_id and app_secret given) is always valid at any time and that the developer can be reached at this address. Failure to do so will result in the immediate suspension of the app_id and app_secret associated.

Any use of the API implies your full acceptance of their Terms of Use (http://www.qobuz.com/apps/api/QobuzAPI-TermsofUse.pdf).

User authentification

  1. Any valid user/login request will return a user_auth_token field.
  2. Send this token expressed as user_auth_token along with method specific arguments to the root endpoint for API calls requiring user authentication.

Please do not store any user password in your application but the user_auth_token instead. It will remain valid for any method until the user revoke your application.

Licensing Rights

Due to licensing rights, API responses containing album and tracks objects will defer depending on several criterias:

  • Your location (your detected country using your IP address if request is anonymous, or the country assigned to your user account if the request is authenticated)
  • Your streaming credentials (ie, only Qobuz Hi-Fi subscribers will be allowed to stream Harmonia Mundi catalog)
  • Your previous purchases (ie, any album purchased will be allowed to stream whatever the streaming rights are)

Signed requests authentification

Some API calls need to be signed by sending both request_ts and request_sig parameters along with method specific arguments to the API endpoint.

Please do not sign requests which are not specifically requiring authentication (at the moment only the track/getFileUrl method is concerned).

  • request_ts - The UNIX timestamp in seconds of the request.
  • request_sig - MD5 hash of the string built by concatening the object, the method, the parameters (excluding app_id and user_auth_token) ordered alphabetically by parameter name using a scheme, the request timestamp (request_ts) and you application shared secret (app_secret).

How-to

Build the request_sig parameter for the following request:

    http://www.qobuz.com/api.json/0.2/track/getFileUrl?track_id=2275757&format_id=5&app_id=100000000
  1. Concatenate the object and method of the request

     trackgetFileUrl
    
  2. Append the parameters ordered alphabetically by parameter name and concatened into one string using a {name}{value} scheme. You must not include the app_id and user_auth_token parameters.

     trackgetFileUrlformat_id5track_id2275757
    
  3. Append the UNIX timestamp in seconds of the request

     trackgetFileUrlformat_id5track_id22757571339428162
    
  4. Append your application app_secret (Please contact api@qobuz.com to ask for application credentials)

     trackgetFileUrlformat_id5track_id22757571339428162500a84db81e461e049382a908f63e1e3
    
  5. Generate an MD5 hash of the resulting string

     631e452a4420ba29769afda03bed43b0
    

Finally, you API call with the resulting request_ts and request_sig parameters will be:

    http://www.qobuz.com/api.json/0.2/track/getFileUrl?track_id=2275757&format_id=5&app_id=100000000&request_ts=1339428162&request_sig=18927637bb903865e581490005b756b1

Pagination

Every methods returning albums, tracks, playlists, artists and subscribers collections accept pagination:

  1. All collections are limited to 50 items by default. This can be overridden by passing a limit parameter. You can paginate through a collections by passing an offset parameter and incrementing it by the limit for each request.
  2. Methods will return paginated collections structured this way:
    • items
    • offset
    • limit
    • total

Encoding

Use UTF-8 encoding when sending arguments to API methods.

Server-side Caching

In order to benefit from server-side caching, you have to make sure URLs don’t change between requests. To that end, you should:

  • Sort query string parameters by alphabetic order
  • Send the user_auth_token and app_id parameters as HTTP headers, respectively X-User-Auth-Token and X-App-Id

Album cover sizes

You have 4 possible Urls for album covers:

  • large: currently width image size at 600px
  • small: currently width image size at 230px
  • thumbnail: currently width image size at 50px
  • back: the back cover if available otherwise null value

Examples:

Note: Hostname, protocol and sizes are likely to change

Hi-Res in API

Hi-Res Availability

We have added some information that identifies whether a product is available in Hi-Res directly in the API. It is important to know that Qobuz offers different Hi-Res formats.

Here, you will find the exhaustive list of the different Hi-Res formats available on Qobuz:

The following formats are Identifiable by format_id=7:

  • 24-bit 44.1 khz
  • 24-bit 48.0 kHz
  • 24-bits 88.2 kHz
  • 24-bits 96 kHz

The following formats are Identifiable by format_id=27:

  • 24 bits 176.4 khz
  • 24 bits 192 kHz

The Hi-Res availability in the Qobuz API is associated with Album and Track titles with the following field:

  • hires: true / false

To get more information about a track or an album, there are two fieds named :

  • maximum_sampling_rate
  • maximum_bit_depth

which are attached to entities 'track' and 'album'.

Whichever of the methods used, if it returns the entities 'track' and 'album', you will always find the two fields mentioned before which allow you to know the maximum quality available for a product (album or track).

Products (Album, Track) purchased in Hi-Res are noted in the API here:

  • http://www.qobuz.com/api.json/0.2/purchase/getUserPurchases with field: -hires_purchased : true/false

Hi-Res API accessibility

To stream a product on Qobuz in Hi-Res quality, user has to meet one of the two following conditions :

  • Having subscribed Qobuz Hi-Fi Sublime and purchased this product in Hi-Res quality.

    You will find the following flag under purchase/getUserPurchases for each product: hires_purchased: true/false You will find the following flag under user/login method and in credentialparameters : hires_purchases_streaming = true

  • OR Having suscribed Qobuz Hi-Fi Sublime +.

    You will find the following flag under user/login method and in credentialparameters: hires_streaming=true = true

(users with other than these subscriptions will have the following flags: hires_purchases_streaming = false and hires_streaming = false)

To be able to import or download in Hi-Res quality on Qobuz, you are only required to have purchased the product (album or track) in Hi-Res quality, regardless of the user subscription.

Reporting of audio streams

Each time an audio stream is started for a track , the application is bound to report the effective time the audio stream is played. This is done using api calls:

Call to API is to be done using POST method, with Content-Type: application/json. Body has to be JSON compliant. If application is playing audio files in offline mode based on a cache, it still needs to report each time an audio file is played. Api calls can be stored and sending delayed.

Error codes

API responses throwing errors will have an HTTP error code and a body with a human-readable description of the error

  • 200 - OK - Everything worked as expected.
  • 400 - Bad Request - Error that resulted from the provided information (e.g. a required parameter was missing).
  • 401 - Unauthorized - Error that resulted from the user authentication.
  • 402 - Request Failed - Parameters were valid but request failed.
  • 404 - Not Found - The requested item doesn't exist.
  • 50x - Server errors - something went wrong on Qobuz's end.

Methods

album

article

artist

catalog

collection

comment

favorite

genre

label

playlist

purchase

status

track

user


Clients

Official clients

Third-parties clients

Links

Contact