Where should you start?

Explore our catalogue or learn about our streaming API documentation, jump to our API usage and brand guidelines or check the full Open API Terms & Conditions

Like what you see?

SIGN UP TO OUR API

  • Our API at a glance

    If you’re looking to create new music websites and applications, or to integrate music into existing services, we offer the perfect solution. Using our API, you can use and license the 7digital technology platform, which includes millions of tracks that can be delivered as downloads or streams, in a variety of formats.  From web to mobile, our ecosystem supports multiple operating systems and platforms, including Android, WebOS, HTML5, Linux, Bada and QNX.

    Our Public API is completely free and open to everyone subject to 7digital API Usage Guidelines.  To get started please sign up for an API key and review our API documentation for more technical detail.

    Access to API methods marked as PREMIUM requires a prior approval. Please get in touch with us for access to these.

    Catalogue API

    Catalogue browsing

     

    Retrieves all artist's releases and top tracks, release details and tracks appearing on release.  You can also browse all available artists alphabetically, or list most recent or upcoming releases.

    Search

     

    Search artists by name, releases by title, or UPC code and tracks by title or ISRC code.

    Recommendations

     

    Find similar artists for a given artist or get release recommendations for a given release.

    Charts

     

    7digital charts of best selling artists, albums and tracks.

    Tags (genres)

     

    Browse artists by tag or list most popular and latest release by tag.

    Previews

     

    30-60 second preview clips can be played via the API for all tracks.

    Cover art & artist pictures

     

    High quality (up to 800 pixels) cover art is available for all releases in our catalogue and artist pictures are available for all major artists.

    Content filtering

    PREMIUM

    Allows filtering out content (e.g. based on licensor or availability for streaming) directly on 7digital API servers.

    CSV catalogue feed

    PREMIUM

    If you prefer to handle catalogue browsing in-house or process the metadata "off-line" we have CSV dumps of the whole 7digital catalogue DB available along with daily updates.

    Custom catalogue content

    PREMIUM

    We offer the option to set up custom catalogues with your own content or a specific subset of 7digital's catalogue.

    User management API

    OAuth user authorization

     

    Access to user resources is controlled using the OAuth authororization protocol - upon first access the user will be asked to authorise your application and you will receive a token for this user.  As long as you keep the token, the user doesn't have to repeat this step.

    Payment methods management

     

    7digital hosted secure web page for managing user's payment methods - adding, deleting and listing payment cards.  Upon adding a payment method users can be automatically redirected back to your website or application.

    Custom branded account pages

    PREMIUM

    Both user authorisation and payment management pages can be branded or skinned to match your specifications.

    Client managed user accounts

    PREMIUM

    If you'd like to keep the user accounts of your service separate from 7digital user accounts you can manage users completely within your own system.

    Purchasing & Music locker APIs

    Locker access

     

    Access the details of all tracks in a user's 7digital music locker (a library of all music puchased from any 7digital powered service, stored in a cloud).

    Affiliate purchases

     

    Add buy links to your application that redirect users to a 7digital music store and earn commissions from their purchases.

    Integrated purchasing

    PREMIUM

    Allows users to make purchases directly within  your website or application.

    Basket

    PREMIUM

    7digital hosted basket that can be checked out directly via the API.

    Custom pricing

    PREMIUM

    Allows you to offer catalogue content at prices that suit you best.  They can be higher or lower than 7digital retail prices or even free if you're feeling generous.

    Client handled billing

    PREMIUM

    If you already have payment processing integrated into your system or you wish to use another 3rd party billing platform (e.g. mobile operator billing) we let you be in charge of taking payments for purchases.

    Downloads and Streaming APIs

    Locker downloads

     

    Download any previously purchased track from a user's locker on their behalf.

    ZIP downloads

    PREMIUM

    Give users the option to download all tracks from a recent purchase or all tracks from a release in their locker as a single ZIP file.

    Mobile downloads

    PREMIUM

    Downloads are optimized for consumption on mobile devices.

    Locker streaming

    PREMIUM

    Stream any previously purchased track from a user's locker.

    Radio style streaming

    PREMIUM

    Streaming where the end user has no or limited control over the streamed content.

    On-demand streaming

    PREMIUM

    Users can stream any track from 7digital's catalogue without any restrictions.

    Non-standard bitrates/formats

    PREMIUM

    We can offer media downloads and streams in custom bit-rates and formats.

    Reporting APIs

    Web reports

     

    Web interface with the latest stats of all purchases made through your API account.

    Detailed offline reports

    PREMIUM

    These can be delivered monthly or quarterly.

    Custom sale tagging

    PREMIUM

    All purchases made via the 7digital API can be tagged with up to 10 custom tags and included in the 7digital sales report.

    Charts reporting

     

    7digital is chart registered in 22 countries and all purchases made through the 7digital music store or directly via the API are counted in the official national charts.

    Technical support

    Community support

     

    The latest API documentation, FAQs, client libraries and more can be found in this developer site.  Additional support is offered via the 7digital API developer discussion group which we actively monitor.

    7digital support

    PREMIUM

    Several levels of dedicated technical help are available during the integration phase and beyond, which includes direct 7digital email and phone contact.

    Training

    PREMIUM

    Upon request we can organize 7digital API training sessions.

    API customization

    PREMIUM

    If you miss a particular functionality from our API we offer development of custom API methods.

     

  • Guides to get you started

    The 7digital API will give you access to an extensive music catalogue licensed by major and indie labels, covering every genre imaginable. This walk-through guide will help you with the steps for creating a web page that enables searching of the 7digital catalogue and streaming previews.

    • Access locker and download tracks

      Get started - accessing your 7digital cloud locker

      Any music you purchase from 7digital is stored securely in a cloud-based locker, so that you can access it anywhere. We don't believe in tying you to a particular device or platform which is why, in addition to range of 7digital Apps for different operating systems, we also provide developers with an open Locker API that allows you to access music stored in your locker from your own application.

      Premium API partners can in very similar way to the walkthrough below integrated Purchasing API for a full featured download store. Have a look at all the building blocks you can play with.

      This walk through will guide you through the process of creating a web page that enables retrieving a 7digital users locker and downloading music from it. It should take around 10 to 15 minutes to complete. Before starting you can check out a working example of the result. Link to the full source code be found at the end of this article.

      The Locker API reference documentation will provide you with all the additional details beyond the scope of this basic usage walkthrough.

      Get ready

      Pre-requisites should come down to a text editor, a browser and a connection to the internet. Oh, and don't forget to sign up for a 7digital API key.

      Let's begin by creating an empty html page and referencing the following libraries: jQuery, jQuery-Cookie and OAuthSimple.

      <html>
        <head>
          <title>7digital Locker</title>
          <script src="http://code.jquery.com/jquery-1.9.1.min.js"></script>
          <script src="tools/OAuthSimple/js/OAuthSimple.js"></script>
          <script src="tools/jquery-cookie/jquery.cookie.js"></script>
        </head>
        <body>
        </body>
      </html>

      User authorisation - OAuth handshake

      Before an application can access user's locker the user needs to grant this application a permission to act on his behalf. The 7digital API uses OAuth for delegated authentication (i.e. the user does not share their username or password with the applicaton). This often referred to as 3-legged OAuth since there's 3 parties involved - the user, 7digital and your app.

      The delegated authentication process - OAuth handshake - consists of 3 steps:

      1. getting a request token
      2. user authorising the request token on 7digital
      3. exchanging an authorised request token for an access token

      After successful completion of the handshake your application can start using the acquired access token to access user's resources - in our case the user's locker.

      Get Request Token

      The below will sign and invoke the oauth/requesttoken endpoint to get a new request token.
      It will also store the new request token secret in a cookie. This will be used later when we exchange the authorised request token for an access token.

      function GetRequestToken(){
        var oauthSimpleSigner = OAuthSimple('YOUR_KEY_HERE', 'YOUR_SECRET_HERE');
        var signedUrl = oauthSimpleSigner.sign({
                          action: 'GET',
                          path: 'https://api.7digital.com/1.2/oauth/requesttoken'
                        }).signed_url;

        $.ajax({
            type: "GET",
            dataType: "xml",
            url: signedUrl,
            success: function(data) {
                       var requestTokenSecret = $(data).find("oauth_token_secret").text()
                       $.cookie("7digitalApiRequestTokenSecret", requestTokenSecret);
                     
                       var requestTokenKey = $(data).find("oauth_token").text();
                       RedirectToLoginPageToAuthoriseRequestToken(requestTokenKey);
                     }
            });
          };

      Authorise Request Token

      After retrieving a new request token, the user is redirected to the 7digital accounts login page in order to authorise the newly acquired request token.
      This redirect includes the newly requested token key and a return url set to the current page.

      function RedirectToLoginPageToAuthoriseRequestToken(requestTokenKey) {
        var authoriseRequestTokenUrl = "https://account.7digital.com/<ConsumerKey>/oauth/authorise";
        authoriseRequestTokenUrl = authoriseRequestTokenUrl.replace("<ConsumerKey>", "YOUR_KEY_HERE");
        authoriseRequestTokenUrl = authoriseRequestTokenUrl.concat("?oauth_token=" + requestTokenKey);
        authoriseRequestTokenUrl = authoriseRequestTokenUrl.concat("&oauth_callback=" + window.location.href.split('?')[0]);

        window.location.href = authoriseRequestTokenUrl;
      };

      After authorising the request token, the 7digital accounts login page will redirect the user back.
      The below will detect when that happens, and if the authorisation was successful it will proceed to the final step of the authorisation process.

      $(document).ready(function() {
        var authorisedRequestTokenKey = getURLParameter("oauth_token");
        var authoriseRequestTokenStatus = getURLParameter("status");
             
        if (authorisedRequestTokenKey != 'null' && authoriseRequestTokenStatus != 'null') {
          ExchangeRequestToken(authorisedRequestTokenKey);
        }
      });
         
      function getURLParameter(name) {
        return decodeURI((RegExp(name + '=' + '(.+?)(&|$)').exec(location.search)||[,null])[1]);
      };

      Exchange Request Token

      The final step of the authorisation process is to exchange the authorised request token for an access token.
      The below will sign (with the consumer and the authorised request token credentials) and invoke the oauth/accesstoken endpoint to get an access token.
      It will also store the retrieved access token key and secret in cookies for future uses.

      After successful completion of the authentication process, the below will also initiate the retrieval of the users locker.

      function ExchangeRequestToken(requestTokenKey){
        var signedUrl = (new OAuthSimple()).sign({
      path:'https://api.7digital.com/1.2/oauth/accesstoken',
      parameters:"oauth_token=" + requestTokenKey,
      signatures:{
        'consumer_key':'YOUR_KEY_HERE',
            'shared_secret':'YOUR_SECRET_HERE',
            'access_token':requestTokenKey,
            'access_secret':$.cookie("7digitalApiRequestTokenSecret")}
        }).signed_url;

        $.ajax({
          type: "GET",
          dataType: "xml",
          url: signedUrl,
          success: function(data) {
            var responseInternalErrorMessage = $(data).find("errorMessage").text();
            if (responseInternalErrorMessage) {
              alert("Error exchanging request token for an access token... message: " + responseInternalErrorMessage);
            } else {
              var accessTokenKey = $(data).find("oauth_token").text();
              var accessTokenSecret = $(data).find("oauth_token_secret").text()
              GetUsersLocker(accessTokenKey, accessTokenSecret);
            }
          }
        });
      };

      Reading user's locker

      Next add the following touch to take care of getting a users locker.

      function GetUsersLocker(accessTokenKey, accessTokenSecret){
        var signedUrl = (new OAuthSimple()).sign({
                  path:'https://api.7digital.com/1.2/user/locker',
                  signatures:{
                    'consumer_key':'YOUR_KEY_HERE',
                    'shared_secret':'YOUR_SECRET_HERE',
                    'access_token':accessTokenKey,
                    'access_secret':accessTokenSecret}
                }).signed_url;
       
        $.ajax({
          type: "GET",
          dataType: "xml",
          async: false,
          url: signedUrl,                           
          success: function(data) {
            $("#results").empty();
            $(data).find("lockerRelease").each(function(){
              var releaseId = $(this).find("release").attr("id");
              var releaseTitle = $(this).find("release").find("title").text();
              var releaseArtist = $(this).find("release").find("artist").find("appearsAs").text();
              var releaseImage = $(this).find("release").find("image").text();
             
              $(this).find("lockerTrack").each(function(){
                var trackId = $(this).find("track").attr("id");
                var trackTitle = $(this).find("track").find("title").text();
                var firstFormatDownloadUrl = $(this).find("downloadUrl").first().find("url").text();

                $('<li>'
                    +'<img src="' + releaseImage + '" /><br/>'
                    + '<strong>Title:</strong> <a class="preview" href="' + firstFormatDownloadUrl + '" >' + trackTitle + '</a><br/>'
                    + '<strong>Artist:</strong> ' + releaseArtist + '<br/>'
                    + '<strong>Release:</strong> ' + releaseTitle
                  + '</li>').appendTo('#results');
              });
            });
          }
        });
      };

      Hook it all up!

      To complete this walkthrough, we'll add a "Get Users Locker" button and a results list view.
      You can drop the following snippet of html directly into the body of the page.

      <input type="submit" value="Get Users Locker" id="getUsersLockerButton"/>
      <ul id="results"></ul>

      And hook up the "Get Users Locker" button to run through the OAuth 3-Legged process and retrieve the users locker.

      $(document).ready(function(){
        $("#getUsersLockerButton").click(function(){
          GetRequestToken();
        });
      });

      Where next?

      You can find the full source of the example on Github along with a live demo.

      And make sure you read through the Locker API reference documentation which will provide you with all the additional details beyond the scope of this walkthrough.

    • Explore our catalogue

      The 7digital API will give you access to an extensive music catalogue licensed by major and indie labels covering every genre imaginable. The Catalogue API provides you with an interface to navigate through and explore the catalogue including:

      • searching for artist, releases and tracks
      • browsing music by genres (tags)
      • artist discographies and artists' most popular tracks
      • 7digital charts
      • recommendations and similar artists
      • playing preview clips for
      • high quality official album artwork and artist pictures

      Check out the API overview for a full list of functionality available.

      Getting started: Searching catalogue and streaming previews

      This walk through will guide you through the process of creating a web page that enables searching of the 7digital catalogue and streaming previews. It should take around 5 to 10 minutes and will look like this working example. If you have any troubles following along, please see the full source code listing at the the end of this article.

      Before starting you can check out a working example of the final result.

      The Catalogue API reference documentation will provide you with all the additional details beyond the scope of this basic usage walkthrough.

      The 4 steps required to search and stream are:

      1. Make a request to the track search endpoint with a search term
      2. Select the ID of a track from the response to stream
      3. Make a request to the track preview endpoint with the selected track's ID
      4. Use the URL from the track preview response to stream a preview of the track

       

      There is also an optional section at the bottom of this walk-through that shows how to display the image of the album the selected track belongs to along side a list of all the tracks on the album. This consists of two extra steps:

      1. Take the "releaseId" for the selected track from the initial track search response
      2. Use the releaseId to query the release tracks endpoint

      This process will be wired-up and made interactive with short snippets of JavaScript and HTML5. All you will need for this tutorial, then, is a text editor (sublime text, notepad++, etc), and a recent version of your favourite browser if you want to play MP3 using HTML5.

      Getting started

      Pre-requisites should come down to a text editor, a browser and a connection to the internet. Oh, and don't forget to sign up for a 7digital API key.

      Let's begin by creating an empty html page with JQuery imported:

      <!Doctype html>
      <html>
          <head>
              <title>Searching and streaming with 7digital's API</title>
              <script src="http://code.jquery.com/jquery-1.9.1.min.js"></script>
        </head>
        <body>
        </body>
      </html>

      Add search capability

      Let's focus on searching the 7digital catalogue for now and add preview playback later. A number of search endpoints are available, but track search is perfect for this example - it returns a list of tracks that match a search term.
      To add a search bar, button and results view, drop the following snippet of html directly into the body of the page:

      <input type="text" id="term">
      <input type="submit" value="search" id="search"/>
      <ol id="results"></ol>

      Now add this touch of JavaScript (below the JQuery script) that takes the search term from the search box, makes the track search request and populates the page with the results when the button is clicked:

      <script type="text/javascript">
          $(document).ready(function(){
              // call 7digital's track search api using value from search box as search term
              $("#search").click(function(){
                  $.getJSON("http://api.7digital.com/1.2/track/search",  // ask API to return json (accept header = application/json)
                      {
                          q: $("#term").val(),
                          oauth_consumer_key: "YOUR_KEY_HERE",
                          pageSize: 4
                      })
                   .done(function(json){
                       $("#results").empty(); // clear previous result
                       $.each(json.searchResults.searchResult, function(key, sr) {
                           var track = sr.track;
                           $('<li><a class="preview" href="#" >' + 'Title: ' + track.title + '</a><br/>'
                                              + 'Artist: ' + track.artist.name + '<br/>'
                            + 'Release: ' + track.release.title + '<br/>'
                            + '<input type="hidden" class="trackId" value="' + track.id + '" />'
                            + '</li>')
                           .appendTo('#results');   
                      });
                   });
              });
          });
      </script>

      Most API endpoints support JSON or XML depending on the value supplied in the accept header. The above example uses JSON to request the following url: http://api.7digital.com/1.2/track/search?q=YOUR_SEARCH_TERM_HERE&pageSiz.... If you paste this URL into a browser and replace the search term, you can see the full response format.
      After making the request, the second part of the example (line 11) takes each search result and displays the track, release and artist name as a list item. Notice the track title is a link, whilst there is hidden field containing the track's ID - this will be explained shortly.

      Add previews playback

      To add streaming of previews, some JavaScript will be added to intercept clicks on a track's title, take the track's ID from the hidden field next to it, and make a request to the track preview endpoint. This will return a URL to the mp3 file. In this example it will be streamed using a HTML5 audio tag and touch of JavaScript.
      First add a HTML5 audio tag to the bottom of the page's body (below the results list):

      <audio id="player" style="width:550px; margin: 0 auto; display:block;" type="audio/mp3" controls></audio>

      Then add this JavaScript directly below the search request (the end of the "$("#search").click.." block) inside the same document ready handler. This time the example shows an XML request (the default content-type):

      // when a track is clicked, get the preview URL and start to play it
      $("body").on("click", "a.preview", function(event){ // using on because link dynamically created
          event.preventDefault(); // cancel the normal follow link behaviour
          $.get("http://api.7digital.com/1.2/track/preview",
              {
                  trackId: $(this).siblings(".trackId").val(), // get track id from hidden field next to link in dom
                  redirect: false, // we don't want to be redirected to the file
                  oauth_consumer_key: "YOUR_KEY_HERE"
              })
           .done(function(xml) {
               var url = $(xml).find("url").text();
               $("#player").attr("src", url); // set url of song on player
               $("#player").get(0).load(); // load song on player
               $("#player").get(0).play(); // start player
           });
      });

      When you click on a track title the preview should now start streaming inside the browser. If it doesn't, compare your page with example at the bottom of this page. Also check your browser does support MP3 playback using HTML5 Audio (For browsers with lack of MP3 support, notably Firefox, a fallback to Adobe Flash player will need to be implemented, e.g. using jPlayer, which is beyond the scope of this simple walkthrough)

      Bonus: Display album artwork and list of tracks

      To improve user experience and make related tracks discoverable, the image of the selected track's album will now be displayed with a list of all the other tracks on the album.
      This can be achieved by updating the JavaScript that handles the search button click event to add two hidden fields for each search result - one with the release's ID and one with the a url for the release's image (add them next to the hidden field with the track's ID):

      $('<li><a class="preview" href="#" >' + 'Title: ' + track.title + '</a><br/>'
          + 'Artist: ' + track.artist.name + '<br/>'
          + 'Release: ' + track.release.title + '<br/>'
          + '<input type="hidden" class="trackId" value="' + track.id + '" />'
          + '<input type="hidden" class="releaseId" value="' + track.release.id + '" />'
          + '<input type="hidden" class="releaseImage" value="' + track.release.image + '" />'
          + '</li>'
      )

      Now the release's ID can be used to retrieve the album's track listing by calling the release tracks endpoint when a user streams a preview.

      // when a track is clicked, get the preview URL and start to play it
      $("body").on("click", "a.preview", function(event){ // using on because link dynamically created
          event.preventDefault(); // cancel the normal follow link behaviour
         
          // clear previously-selected track list and image
          $('img.relImg').remove();
          $('div.trackListTrack').remove();
       
          // add the image below the player
          $("audio").after('<img class="relImg" src="' + $(this).siblings(".releaseImage").val() + '" />');
       
          // grab the list of tracks from the release/tracks endpoint
          $.get("http://api.7digital.com/1.2/release/tracks",
              {
                   releaseId: $(this).siblings(".releaseId").val(),
                   shopId: 34,
                   oauth_consumer_key: "YOUR_KEY_HERE",
                   pageSize: 4 // change to suit your needs
               })
               .done(function(xml){
                  // add a link to each track below the album's image
                   $.each($(xml).find("track"), function(key, track){
                      $("img.relImg").after('<div class="trackListTrack" >'
                                           + '<a href="' + $(track).find("url") + '">'
                                           + $(track).find("title").text() + '</a></div>');
                      });
                  });
       
          $.get("http://api.7digital.com/1.2/track/preview",


      Above is the first part of the updated body click handler, notice how the the hidden field containing the release's image is used to add an image, whilst the hidden field containing the release's ID is used to query release tracks.
      All that's special inside the callback passed into the done method (at the bottom) is how a link is created to each track from the response using the "url" and "title" fields available on each "track" element.

      Where next?

      You can find the full source of the example on Github along with a live demo.

      And make sure you read through the Catalogue API reference documentation which will provide you with all the additional details beyond the scope of this walkthrough.

      As well as searching for tracks, you might want to investigate searching for artists using the artist search endpoint, then artist releases or artist toptracks. Alternatively, have a look at the release search and release tracks endpoints to search and explore music albums.

    • Streaming

      In addition to providing high quality downloads 7digital also offers range of streaming services. These typically fall into one of these categories:

      • Locker streaming - allows users to stream previously purchased music directly from their cloud locker without the need to download the audio files first. Check out our walkthrough on accessing a 7digital locker for an example how to get started with the Locker API.
      • On demand, Interactive streaming - our platform supports full interactive on demand streaming where the user has access to our entire catalogue in the cloud, and we hold both label and publishing licenses.  These rights are generally quite expensive, the infrastructure is highly complex, and the business model requires large-scale adoption in order to succeed.
      • Radio streaming - you can use our licensed catalogue to create a radio stream that complies with the limited-interactivity rules of the US Digital Millennium Copyright Act (DMCA). See our getting started example of how to build such a radio.

      But with our API you're certainly not limited just to the above use cases and we can support practically any streaming service (e.g. collaborative radio, music jukeboxes, etc). Please contact us for further information on licensing and technical guidance.

      Take a look at our full streaming API documentation.

    • API implementation best practices

      Building music services is fun and challenging and we've been doing it for over 10 years so we've gotten it down to a science. Based on our experience here are some of the best practices you should follow to build a robust and easy to maintain app:

      Parsing API responses

      Our API is under constant development and new functionality is released regularly. As a result of this new fields might be added to API responses without advance notice. Your app should not be affected by this and we do not consider it to be a breaking change.

      When reading an API response always access the elements by their full hierarchy and name within the response (e.g. using full XPath for XML) as sometimes elements with the same name can appear in the same response under different parent elements. Unless dealing with an array never access elements in the response by their index, for example as in elements[0], instead always access them by name e.g. elements[“name”]. The order of elements can change at any time.

      Example:   

      Original
      <release id="12345">
          <title>Greatest Hits</title>
          <artist>
              <name>Random Band</name>
          </artist>
          <version>Remastered</version>
          <image>http://7dg.tl/x.jpg</image>
      </release>

      Non-breaking change

      <release id="12345">
      <title>Greatest Hits</title>
      <version>Remastered</version>
      <artist>
      <name>Random Band</name>
      <image>http://7dg.tl/y.jpg</image>
      </artist>
      <image>http://7dg.tl/x.jpg</image>
      </release>


      We also recommend you only parse fields you’re making use of in your application and ignore the ones you don’t need. This will minimize the amount of breaking changes that might affect you. Use undocumented fields at your own risk.

      OAuth

      We strongly recommend for you to use standard OAuth libraries (e.g. see http://code.google.com/p/oauth/) rather than implementing your own OAuth clients from scratch. But in case you decide to ignore our advice or you’re using a really obscure language with no OAuth library available you might find our OAuth reference page useful for debugging all those little issues you’re likely to come across: http://7digital.github.io/oauth-reference-page/.

      When linking 7digital accounts to user accounts of your application you do not need to go through the entire OAuth authentication flow each time you need to access an endpoint, that requires 3-legged OAuth. OAuth sets up a trust relationship between you (the API consumer) and a 7digital user, who authorises you to make requests on their behalf. This needs to be set up only once. The access token and secret obtained during this process can be re-used. Though you still need to gracefully handle scenarios when the access token stored by you has been revoked by the user who authorised it.

      Keeping your API credentials secure

      It is your responsibility to ensure your API credentials are not misused. We recommend to keep them secure and store encrypted (especially if they’re stored directly on client side). 7digital reserves the right to revoke API access for any API key that has been compromised. You should make sure you can update your application with a new set of credentials in case your credentials were compromised  (see also “Application upgrades” paragraph below.)

      Due to the fact that API credentials permanently or temporarily stored on client side (e.g. within an app on a mobile device) can never be 100% immune to reverse engineering some API endpoints can only be used in server-to-server integrations (e.g. stream/catalogue, user/devliveritem). This also applies to integrations where user authentication is handled by 3rd party, i.e. using 2-legged OAuth instead of 3-legged.

      Keep your time in sync

      OAuth signed responses require a timestamp provided with each request. When building applications for devices where correct time cannot be guaranteed (e.g. user can change system time on mobile phone) the application needs to maintain it’s own timer and synchronize it either with trusted 3rd party time server or preferably with the time provided by 7digital API servers. You can use the HTTP “Date” header returned with every API response or the “/status” API endpoint.

      Application upgrades

      As the 7digital API evolves we’re often forced to make “breaking” changes to it’s behaviour (e.g. no longer relevant elements might be removed from API responses or entire API methods might be deprecated). You must be able to accommodate such changes by publishing an application update and ensure your users are notified of the need to upgrade. This also applies for apps embedded directly onto devices (e.g. wireless speakers, etc). We provide advance notice and transition periods for any breaking changes.

      Error handling

      Whilst we strive to make our API as robust as possible we do run into issues from time to time. To minimize impact of any downtime always try to catch and handle all 7digital API errors and do so for individual calls in isolation, e.g. if you’re displaying a chart on your homepage and the release/chart endpoint starts failing for some reason it should only affect your chart feature and not bring your entire homepage down. Please see our documentation [http://api.7digital.com/1.2/static/documentation/7digitalpublicapi.html#Error_responses] for explanation of different error code types.

      Local caching

      All API responses will return appropriate HTTP cache headers. Make use of them. Your application will be more responsive if you don’t make unnecessary server calls.

      Placing a proxy server, such as Squid, between your application and the API, will give you caching quite easily and send requests to the server only when the cached item has expired.

      The provided expiry times are generally recommended values adjusted for each API method but you are free to use your own caching strategy should it suit your application better. (E.g. whilst for download stores we wouldn’t recommend caching a list of tracks on an album for more than 15mins as the price of these track can change at any time, if your application doesn’t even display the prices you can cache the response for multiple hours or even days since the actual track listing is very unlikely to ever change)

      Bugs and unexpected behaviour

      If you come across unexpected API responses or discrepancies between documentation and the actual API behaviour don’t work around these. Please get in touch and let us know about the problem and we’ll do our best to fix the issue or advise you on the correct way to resolve.

  • API Developers FAQ

    What are the prices for using your API?

    Our Public API is free for non-commercial use, provided it is in accordance with our API Usage Guidelines.

    For other uses (such as commercial use, streaming, increased rate limits or access to our Premium API) prices vary depending on many factors. Before providing an estimation of cost, our Commercial Team will need to understand your requirements, such as operating territories, reporting requirements, licensing, desired API services and usage rates.

    Please contact our Commercial Team, providing them with a description of the service you are building, and they will be in touch to discuss your requirements.

    How can I gain access to the Premium API?

    Access to the Premium API requires a commercial contract with 7digital. A commercial contract means that you will have to pay money to rights-holders (labels and publishers) and / or us. How much you will have to pay depends on the type of service you wish to build (downloads, streaming, radio, subscription etc), in which territories you want to launch, and on what kind of devices (mobile, desktop etc). Please understand that there are no exceptions to this before you contact our Commercial Team.

    How do I gain access to your streaming services?

    The Streaming API is part of our Premium API. Before we can provide you with access to this functionality you will need either need to negotiate your own music licenses with the relevant record labels/distributors/publishers or you will need to discuss commercial terms and processes for approved use of 7digital's own licensing agreements.

    The musicbiz.org site provides some useful info on music licensing, such as:

    You should get the music licenses in place first, as licensing is typically the most costly part and will also clarify how your service will be able to operate. Once you have negotiated licenses, please tell our Commercial Team about your service and they will they will be in touch to discuss your requirements and pricing.

    Can I use song previews from your API in my app?

    If you are using our free, ‘Public API’ then preview clips must be used solely to promote the purchase of the given track - please have a read of our guidelines. You will have to obtain your own music licenses, if our usage guidelines aren’t met.

    How can I allow people to purchase 7digital tracks straight from my site without having to leave it?

    You can embed the 7digital “Buy Button", which is a widget that allows users to buy items while remaining on your site. For further information, please see our documentation about becoming an affiliate and the the 7digital “Buy Button".

    I am having issues integrating my app with the 7digital API. Who can help me?

    The best place to get your questions answered is our 7digital API Developers Forum.

    If you can't find your answer in the existing posts, then please feel free to post it up and our developers, or a member of our community will endeavour to help.

    I am getting the error "You have exceeded your daily request limit". Help!

    You either have a really popular service there, or you need to have a look at your caching strategy. If you are sure you are using the API as efficiently as possible and still hitting your limit, you will need to contact our Commercial Team to discuss a solution.

    How do I sign a request using OAuth?

    We strongly recommend you use an OAuth library to sign your requests, as it can be difficult to implement yourself. We have prepared some OAuth guidance and a walk through to help you.

    If you are receiving “invalid signature” errors, you can use this reference page to generate an OAuth signature and compare it with the signed requests you are making.

    I am having difficulty using endpoints that require access tokens. What do I do?

    Please read our step-by-step guide on how to obtain an access token.

    Note that if you have an old access token and it contains reserved characters (eg. / + =) you'll need to obtain another access token. New access tokens will not contain reserved characters.

  • OAuth guide

    Obtaining an access token - a step-by-step guide

    To generate an access token you will be using our OAuth Authentication API.

    The steps involved are as follows:

    1. Obtain a request token by making a signed POST to

    http://api.7digital.com/1.2/oauth/requesttoken

    e.g.:
    curl -X POST 'https://api.7digital.com/1.2/oauth/requesttoken' -d 'oauth_consumer_key=YOUR_KEY_HERE&oauth_nonce=950262835&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1426071532&oauth_version=1.0&oauth_signature=qX5UNhYyuqZVx%2BZOXHQbWMpuKvE%3D'

    2. Decode the response content (it is URL encoded) and extract the request token (oauth_token) and request token secret (oauth_token_secret), e.g.:

    oauth_token=ABC1XYZ&oauth_token_secret=oGBr7s1xQ0OBk6L1fddTCQ%3d%3d

    =>
    request token: ABC1XYZ
    request token secret: oGBr7s1xQ0OBk6L1fddTCQ==

    3. Send the user to our micro service site to authorise the request token, e.g.:

     https://account.7digital.com/YOUR_KEY_HERE/oauth/authorise?oauth_token=ABC1XYZ&oauth_callback=http%3A%2F%2Fexample.com%2F

    The user will be shown a login page, where they create a 7digital account or sign in to their existing account, and then authorise your application.

    The oauth_callback parameter specifies your URL that the user will be returned to once they have authenticated the request token (or when authentication fails).

    When the user is redirected to the callback URL, the query string will contain two extra parameters - the request token and the status of the token authorisation. The status will have the value ‘Authorized’ if the request token was authorised by the user, e.g.:

    HTTP/1.1 302 FoundLocation: http://example.com/?oauth_token=ABC1XYZ&status=Authorised

    4. Exchange the request token for an access token by making a signed POST to
    http://api.7digital.com/1.2/oauth/accesstoken
    using the request token and request token secret to sign the request.

    e.g.:
    curl -X POST 'https://api.7digital.com/1.2/oauth/accesstoken' -d
    'oauth_consumer_key=YOUR_KEY_HERE&oauth_nonce=392543666&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1409741291&oauth_token=ABC1XYZ&oauth_version=1.0&oauth_signature=NdtITy3YGNOhf6xm5JfPfDWKRSQ%3D'

     5. Decode the response content (it is URL encoded) and extract the access token (oauth_token) and access token secret (oauth_token_secret), e.g.:

     oauth_token=OkG6sd_eIkem6RgdZklyBQ&oauth_token_secret=WOq-Ek4sdUmPlN6umrroFQ

    =>
    access token: OkG6sd_eIkem6RgdZklyBQ
    access token secret: WOq-Ek4sdUmPlN6umrroFQ

    There you have it - an access token and a secret you can use in requests to endpoints that require an OAuth access token.

    If you still have any questions, concerns, or need some friendly help, please feel free to raise them on our 7digital API Developers Community and someone will get back to you shortly!

  • API Wrappers

    Android
    7digital Android SDK

    Simplifies access to features available in the 7digital API and makes it easy to add music charts and metadata, preview streams, purchasing and more to your Android app
     
     
    7digital Android App Intents

    Instructions how to deep link into the 7digital Android app

     
    iOS
    7digital iOS SDK

    The 7digital iOS SDK helps you to add music features to your app. By integrating the SDK you can download and stream 7digital music within your own app.
     
     
    .Net
    .Net Fluent C# Wrapper

    (See example usage console app project for some more examples.)

     
    Python
    python-7Digital (py7D) by Jason Rubenstein

     
    Ruby
    Ruby Wrapper

    Example app: Random Album Recommender - A simple Ruby on Rails example using the Ruby Wrapper

     
    Javascript / Node.js
    Node.js Wrapper by Raoul Millais

    Example app: 7digital HTML5 Packaged App - A demo album search app using the js api client

     

    PHP
    PHP 7digital-client by Gildas Quéméner

    • 7digital Android SDK

      The 7digital SDK simplifies access to features available in the 7digital API and makes it easy to add music charts and metadata, preview streams, purchasing and more to your Android app.
       

      Download the SDK

      Visit the 7digital Android SDK home page on GitHub to download.


      Documentation

      Full documentation is available at 7digital.github.io/7digital-Android-SDK/apidocs/
       

      Getting Started

      Register as a developer to get a key and secret at api-signup.7digital.com.

      Clone the repository, which includes a sample app.

      Change the appKey and appSecret in the Constants.java file to your own key and secret.

      To use the SDK in your app, include the cloned repository as a module in Android Studio. Make sure to compile the 'sdk' module as a dependency.

      Alternatively, a compiled .aar is available in the Releases tab of the GitHub page.

      Other resources

      For more information about deep linking into the 7digital Android app, see 7digital Android App Intents.

  • Affilliate links

    Creating affiliate links to 7digital on web and mobile

    Linking to 7digital web store

    All 7digital API responses automatically include affiliated "buy" links to our (desktop) web store at 7digital.com. All you need to do is display these links to your users and any purchases made after following these links will be tracked under your 7digital affiliate account.

    E.g. for an artist details API call

    http://api.7digital.com/1.2/artist/details?artistid=1&oauth_consumer_key...

    the response will look like this (see the buy URL highlighted):

    <response status="ok" version="1.2">
      <artist id="1">
        <name>Keane</name>   
        <sortName>Keane</sortName>   
        <url>http://www.7digital.com/artists/keane/?partner=1234</url>
        <image>http://cdn.7static.com/static/img/artistimages/00/000/000/0000000001_150...
      </artist>
    </response>

    Your 7digital Partner ID

    Whilst links to mobile store or apps are not included in the API responses it's easy to create them yourself. Before starting you'll need to know your 7digital partner ID which you can find in your  API registration email received from us after signing up for an API key (if you've signed up after Jun 11 2013).

    Alternatively you can also find out what it is by making any API request using your 7digital API key as described above and look for ?partner=XXXX in the buy links (<url>) generated for you. In our example above your partner ID would be 1234.

    Once you know your partner ID you can choose one from one of the mobile linking options below:

    7digital Buy button

    Check-out the 7digital Buy button instructions page for an easy way to embed music purchasing buttons into your website or mobile app. It provides streamlined checkout experience and is optimized for both desktop and mobile devices.

    7digital Android Affiliate SDK

    The easiest way to link to 7digital on Android is to use our 7digital Android Affiliate SDK available on GitHub.

    This SDK contains a simple library that provides 'shortcuts' to perform common actions on the 7digital Android app.

    7digital Android App Intents

    The 7digital Music app for Android offers an integrated player and MP3 music store. That means you can discover, buy and listen to music anywhere, and sync and play any music you have previously purchased.

    Download the 7digital Android app directly to your phone from Google Play.

    The 7digital Android App supports following intents:

    VIEW_ARTIST - opens artist screen

    Intent i = new Intent();
    i.setClassName("uk.co.sevendigital.android", "uk.co.sevendigital.android.library.shop.SDIExternalActionActivity");
    i.setAction("uk.co.sevendigital.android.intent.action.VIEW_ARTIST");
    i.putExtra("uk.co.sevendigital.android.intent.extra.PARTNER", partnerId);
    i.putExtra("ARTISTID",artistId);
    startActivity(i);

    partnerId is your 7digital partner ID as described above
    artistId is the 7digital artist ID

    VIEW_RELEASE - opens release screen (with optional track highlighting)

    Intent i = new Intent();
    i.setClassName("uk.co.sevendigital.android", "uk.co.sevendigital.android.library.shop.SDIExternalActionActivity");
    i.setAction("uk.co.sevendigital.android.intent.action.VIEW_RELEASE");
    i.putExtra("uk.co.sevendigital.android.intent.extra.PARTNER", partnerId);
    i.putExtra("RELEASEID",releaseId);
    i.putExtra("TRACKID",trackId);
    startActivity(i);

    partnerId is your 7digital partner ID as described above
    releaseId is the 7digital release ID
    trackId - optional parameter - if provided the selected track is highlighted on the release screen

    SEARCH - opens search results screen

    Intent i = new Intent("uk.co.sevendigital.android.intent.action.SEARCH");
    i.putExtra(SearchManager.QUERY, searchQuery);
    i.putExtra("uk.co.sevendigital.android.intent.extra.PARTNER", partnerId);
    startActivity(i);

    partnerId is your 7digital partner ID as described above
    searchQuery is the query string that's being searched for

    For every intent you will need to catch an exception for the case where the 7digital application is not installed.

    Here's an example how you can handle this by replacing startActivity with your own custom start7digitalActivity:

    /**
     *  Start the 7digital application. On failure, go to the Google Play if it is installed.
     *  @param i The Intent used to start the Activity
     */
    protected void start7digitalActivity(Intent i) {
      try {
        startActivity(i);
      } catch (ActivityNotFoundException e) {
        Toast.makeText(this,
          R.string.the_7digital_not_installed_please_install_it_from_google_play_,
          Toast.LENGTH_LONG).show();
        // Take user to market
        String marketQuery = "market://details?id=uk.co.sevendigital.android";
        Intent intent = new Intent(Intent.ACTION_VIEW,Uri.parse(marketQuery));
        try {
          startActivity(intent);
        } catch (ActivityNotFoundException e1) {
          Toast.makeText(this,
            R.string.google_play_not_found_please_install_the_7digital_app_manually_,
            Toast.LENGTH_LONG).show();
        }
      }
    }

    • 7digital Buy button

      We aim to make buying tracks as convenient as possible.

      Our nifty little tool allows our partners to embed a 7digital Buy Button into a website in 3 simple steps.  The button will allow users to purchase a track/release without leaving the website they’re on.

      See it in action right here:



      Or, take a look at our demo blog.

      Please note that the 7digital Buy Button is still under beta. You may notice variations in the look and feel of the checkout process whilst we're working out the best user experience based on customers' feedback. If you do use the buttons on your site, or have any feedback, please reach out with the 7digital API Community.

      Add it to your blog or website

      The 7digital Buy button is very simple to set-up and can be done in 3 easy steps:

      1. Copy & paste the code into the HTML on your site
      2. Replace the CAPITALISED_TEXT with the desired track/release IDs and your partner ID
      3. Include JavaScript library (if necessary*)

      OPTION 1 - Embedded iframe

      Music bloggers will love this simple way of creating a button:

      <iframe src="https://instant.7digital.com/iframe.htm?releaseid=RELEASE_ID&trackid=TRA..." seamless="seamless" frameborder="0" height="40" scrolling="no"></iframe>

      *If you’re using the iframe version you do not need to include the JavaScript library.

      OPTION 2 - CSS class

      This option gives you full control of the look and feel of the button but requires you to be able to include JavaScript libraries (listed below) to all pages where the buy buttons are used.

      Creating a buy button for a track:

      <button class="7d-buynow" data-trackid="TRACK_ID" data-partner="YOUR_PARTNER_ID">BUY</button>

      Creating a buy button for a release (album):

      <button class="7d-buynow" data-releaseid="RELEASE_ID" data-partner="YOUR_PARTNER_ID">BUY</button>

      You must then include the following script tag at the end of your html page:

      <script type="text/javascript" src="https://instant.7digital.com/scripts/dist/7d-buyitnow.min.js"></script>

      Then - any element you click on with the correctly specified class (7d-buynow) will become a 7digital Buy Button.

      More examples

      Couple of more examples can be found on GitHub:

      • Basic buttons
      • Top tracks Chart
      • Top albums Chart
      • Search for tracks
      • Search for releases

       

      All come with a full source code.

      Add it to your desktop or mobile app

      You can also integrate the Buy Button into a native application by opening the following URLs in a webview within the app:

      https://instant.7digital.com/purchase/track/TRACK_ID?partnerId=YOUR_PARTNER_ID

      https://instant.7digital.com/purchase/release/RELEASE_ID?partnerId=YOUR_PARTNER_ID

      For a sample implementation with source code check-out our Android Buy Button demo app on Github. It will show you how the 7digital Buy Button can be added to an Android app to enable users to purchase a track or release without leaving your app.

       

  • Affiliate integration

    The Echo Nest - Rosetta Stone Integration

     

    The Echo Nest has deeply integrated the 7digital API, making it easy for developers to integrate the 2 APIs together. The Echo Nest's API features include:

    • DMCA Compliant personalized playlisting engine
    • Audio fingerprinting
    • Dynamic Data Feeds of Music News, Reviews and Blogs
    • User Taste Profiling and Personalization
    • Music analysis and Remixing

     

    Project Rosetta Stone

    The Echo Nest API supports multiple ID spaces. You can use an ID from a supported ID space in place of an Echo Nest ID in any call that takes an Echo Nest ID. This not only allows you to access Echo Nest API features using 7digital IDs but also translate other 3rd party IDs (e.g. MusicBrainz IDs) into 7digital IDs.

     

    Getting Started

    When making calls to the Echo Nest API, use one of the following buckets: 7digital-US, or 7digital-UK.

    As an example, Radiohead has a 7digital artist ID of 304. To find biographies for Radiohead using The Echo Nest API and the 7digital artist ID, you would issue a query like this:

    http://developer.echonest.com/api/v4/artist/biographies?api_key=FILDTEOIK2HBORODV&id=7digital-US:artist:304


    Note that the id parameter is of the form catalog:entity:id; in this case, 7digital is the catalog; artist is the entity, and 304 is the artist ID in the 7digital catalog.

    You can also retrieve artist information and receive their IDs in the 7digital name space. To do this, you use the bucket=7digital-US parameter on any call that returns artists, songs or tracks. As an example, to find artists similar to Radiohead, with 7digital IDs returned, issue a call like this:

    http://developer.echonest.com/api/v4/artist/similar?api_key=FILDTEOIK2HB...

    Note that the id parameter is of the form catalog:entity:id; in this case, 7digital is the catalog; artist is the entity, and 304 is the artist ID in the 7digital catalog. Example results:

    {
        name: "Manic Street Preachers",
        foreign_ids: [
            {
                catalog: "7digital-US",
                foreign_id: "7digital-US:artist:10651"
            }
        ],
        id: "ARGEJ8B1187B9AE2E7"
    }


    Note that for each artist returned, there is a new foreign_ids block that includes a foreign_id of the form catalog:entity:id, in this case, 7digital-US:artist:10651.

     

  • API usage guidelines
    • Usage limits. Our Public API is limited to a rate of 4000 requests per day
    • Commercial Use. Our Public API is free for non-commercial users. If you would like to use the API in a commercial application, or if you're unsure whether you qualify as a non-commercial user, please contact us.
    • Use cache. If your website or application needs to access the same data repeatedly, please cache the metadata returned by 7digital API responses either directly in your code or by setting up a cached proxy to the API.
    • Storing provided content is not allowed. On client side only (e.g. browser, mobile device) you can also cache artist images, album packshots and preview streams. These can be cached for maximum time of 7 days. Full length streams may not be cached or permanently stored in any scenario. Downloads may not be cached or stored on servers but may be stored in client applications as directed by user request.
    • Do not scrape the API. Our API is designed for real-time use by humans. Please don't attempt to scrape the content in an automated way using scripts (e.g. getting release details for release IDs 1, 2, 3, 4, etc.) as this will negatively affect the performance for other users, and you will be subsequently banned. If you need to process the catalogue data offline, please contact us and we can provide you with FTP access to an XML dump of the whole 7digital catalogue (as part of our Premium service).
    • Don't break the law. Using our API in connection with any illegal services is strictly prohibited.
    • Link to 7digital. Please let your users know that the data is being provided by 7digital. For versions of our logo and guidelines for its use, please download our press kit.
    • Let us know about your application. We love to see what people can do with our API, and your work gives us valuable feedback that influences how we shape our API in the future, and allows us to showcase your app to our users and clients. By giving us a chance to review your integration, we can also provide you with feedback, should we see any technical or legal issues. Let everyone know what you’re working on by posting a URL to http://groups.google.com/group/7digital-api or contacting us directly.
    • It's nice to share! If you've implemented a 7digital API wrapper in your favourite language, or have other pieces of code that you think others might find useful, we’d be grateful if you could share it with everyone. You can post your achievements to our Google group or simply let us know directly and we’ll publish it on the 7digital Developers site.

    Our API is being updated constantly, please also take a look at our API Best Practices where you’ll find pointers on how to build applications that won't break with these incremental changes.

    7digital monitors all API requests and we reserve the right to revoke your API key without notice if you do not follow the guidelines outlined here and the Full Terms and Conditions for use of the Public API.

    Our Commercial API is subject to different Terms and Conditions. Please contact our Commercial Team for details.

  • 7digital brand guidelines

    We love to work with our partners on co-marketing activity and also want to help you market your service the best way possible. 

    We will be posting some guidelines for marketing, merchandising and promotions soon so please check back. In the meantime, there are brand and integration guidelines below to help ensure that you are complying with our T&Cs and using our logos in the correct way. 

    Please contact our Marketing team if you have any questions on this or any great promotional opportunities you want to talk to us about!