Although I’d normally write this article in Romanian I expect a wider audience for it, so I will post it in English.

Snippet

If you don’t want to read the entire article here are some shortcuts:

Dance-Tunes.com

Dance Tunes Logo

Dance-Tunes is a music online store, located in the Netherlands, where one can buy their favorite … dance tunes, of course. Organised in eight main genres (Downtempo, Dance, Techno/Minimal, Hardcore, Breaks, Electro/House, Hardstyle/Jump and Trance) Dance-Tunes has an extensive database of tunes, artists and labels.

The Public API

On the 22nd of February 2010, Dance-Tunes released their 1.0 version of the API. The main purpose of the API is to help create rich internet applications that are based on the information of tunes, artists, labels or charts. Developers are encouraged to use the public Dance-Tunes API to get creative and use the extensive library of labels, artists and tracks in their sites or applications.

Dance-Tunes has created a special page for developers where one can find all information about the public API. Each individual API call is explained and examples are given to show the correct structure of the calls and response. One can request an API key by logging in using the Dance-Tunes account details. The API key will be sent to the developer’s email address. One can download the API documentation in pdf format for printing and off-line viewing.

The PHP Client

The Dance-Tunes PHP API Client that I am releasing today, was written with intention of integrating into a Zend Framework application. As of this it follows the PHP File Formatting, Naming Conventions and Coding Style recommended by the Zend Framework Team.

It uses the Zend_Http and Zend_Exception packages from the Zend Framework classes. It can be used either with an entire Zend Framework application or as is. The dependencies can be load by themselves (just the 2 packages), or the Dancetunes class can be modified in order to be used in a simple PHP project. One can replace the use of Zend_Http package with the use of the cURL library and the Zend_Exception with the PHP base Exception.

Usage

Each of the documented function in the Dance-Tunes API has a corespondent wrapper method in the Dancetunes class that accepts the exact amount of parameters that the API requires, except the command and the session(params cmd and session) which are built in. For each session key, as the documentation specifies, a timestamp is updated on each request, and the session key is deleted if no request is performed for 6 hours. So, as a best practice, it is recommended to cache the session key locally for immediate access to the resources on other requests.

$dancetunes = new Dancetunes(DT_API_KEY);

if (!($sessionKey = $cache->load('sessionkey')))
{
    $dancetunes->setUserName(DT_USERNAME);
    $dancetunes->setPassword(DT_PASSWORD);
    
    $sessionKey = $dancetunes->authenticate();
    $cache->save($sessionKey, 'sessionkey');
}
$dancetunes->setSessionKey($sessionKey);

/* Get the first 10 releases */
$releases = $dancetunes->getNewReleases(11, 10, 1, 10);

/* Get a preview */
$audio = $dancetunes->getPreview( 123456 );
/* saving the audio content to disc */
file_put_contents('123456-tune-preview.mp3', $audio);

Responses

Dance-Tunes API will respond either with an XML string or with binary data (for artwork and preview). For the case of XML response I have created a Dancetunes_Vo class that takes a XML string and converts it into an array. Also for each response type I have created an individual class that extends the Dancetunes_Vo class and implements some particular methods for a specific result. For example the Dancetunes_NewReleases class will be the result of the Dancetunes::getNewReleases method and has a method for returning just the tunes info from the response, and another one to return the number of total possible tunes that can be returned on a specific request.

class Dancetunes_NewReleases extends Dancetunes_Vo {
    
    public function getTracks() {
        return $this->_array ['new_releases'] ['tune'];
    }
    
    public function getCount() {
        return $this->_array ['new_releases'] ['total_count'];
    }
}

These classes can be modified or extended in order to deal in a specific way with the XML response.


License

The package is released as an open source project under The New BSD License.

Copyright (c) 2010, George Enciu, ColorSoft System SRL, Romania

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of the ColorSoft System SRL nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Change Log

2010-04-06
  • Version 0.1 BETA released
2010-05-15
  • Added a version written in simple PHP
  • Still in 0.1 Beta

Download

All the code and download files can be found at the Google Code Project

Trackback

7 comments until now

  1. [...] more from the original source: In PHP we Trust »… :mp3, [...]

  2. [...] We urge PHP developers and enthusiasts to go and check out the full article here! [...]

  3. Thanks for this, i used it in a project of mine. ^:)^

    However i found it hard to make it work with the zend_ packages. I managed to make it work, but i think i used too many zend files for it. Maybe you could add some info about how to include only the two classes which are needed.

    thanks!

  4. HI Bjorn,

    Thank you for your interest in the library. I have modified the class and uploaded it in the download section on the Dance Tunes Library Google Code page. Let me know if that works for you and also let me know what’s your app about when it’s done

    Best wishes!

  5. Thanks for the update. I already got it working with the zend files, but next time i will use the basic php solution.

    you can find the “app” here:
    http://www.starbeach.tv/dance-tunes

  6. I’ve been looking for a way to implement a link with a preview to all my releases on Dance-Tunes. It seems like your php script is capable of this, but I am really a php noob and can’t get it to work.
    My website which I am building right now is made in Joomla. Is it possible to integrate you r script in Joomla and let it search for all my releases and return the picture of the coverart and preview and buy now button? I hope you can help me a little bit out, cause there really is no other information available on the net. I googled a lot, but couldn’t find anything else and the information of the Dance-Tunes API is not really a help.

    Cheers,

    Benito

  7. Hi Benito,

    The library that I have proposed can do such thing as it is a general purpose library that eases the access to the API from PHP. Either Joomla or any other CMS you can write any scripts that integrates this library.

    About your particular problem, to make this a nice web 2.0 script you’ll need more than PHP: some JavaScript, some Flash maybe (for the player). I am not used to Joomla system as I have never worked with that CMS, so I will not be able to give you any advice in how to integrate any script in Joomla. However I can give you tips on how to make the dance-tunes script work.

    Let me know if I can be of any assistence.
    George

Add your comment now