Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Qobuz Official API documentation
Failed to load latest commit information.
consoles Dear API, you deserve a better documentation. KR.
endpoints Update login.md
README.md Update README.md

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, and Streaming was recently launched in 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://www.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

Our album cover URLs are built using the following pattern:

http://static.qobuz.com/images/covers/[0-9]{2}/[0-9]{2}/[0-9]{13}_{size}.jpg

You are welcome to change the {size} in the URLs returned by our API methods to dynamically resize the covers and fit your needs. Available sizes are: 50, 68, 100, 130, 150, 160, 230, 300, 600 and max

Examples:

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

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 on Qobuz in Hi-Res quality, you must completed two conditions :

  • have purchased a product in Hi-Res quality.

You will the following find noted under purchase/getUserPurchases for each product: hires_purchased: true/false

  • be a Qobuz Hi-Fi Sublime subscriber.

You will the following find noted under user/login method , and in credentialparameters, a field named : hires_purchases_streaming = true

(users with any other type of Qobuz subscription have the field: hires_purchases_streaming = false)

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

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

Something went wrong with that request. Please try again.