bshaffer / php-echonest-api

PHP classes for the Echo Nest API

PHP Echo Nest API

A simple, Object Oriented API wrapper for the EchoNest Api written with PHP5. This library is modeled after the php-github-api library built by ornicar

Uses EchoNest API v4.

Requires

• PHP 5.2 or 5.3.
• php curl but it is possible to write another transport layer..

If the method you need does not exist yet, dont hesitate to request it with an issue!

Autoload

The first step to use php-echonest-api is to register its autoloader:

require_once '/path/to/lib/EchoNest/Autoloader.php';
EchoNest_Autoloader::register();

Replace the /path/to/lib/ path with the path you used for php-echonest-api installation.

php-echonest-api follows the PEAR convention names for its classes, which means you can easily integrate php-echonest-api classes loading in your own autoloader.

Instanciate a new EchoNest Client

$echonest = new EchoNest_Client();

From this object you can now access all of the different EchoNest APIs (listed below)

Authenticate a user

Authenticate using your EchoNest API Key. You can obtain one at EchoNest by Registering an Account

$echonest->authenticate($apiKey);

Deauthenticate a user

Cancels authentication.

$echonest->deAuthenticate();

Next requests will not be authenticated

Artists

For searching artists, getting artist information and music. Wraps EchoNest Artist API.

$artistApi = $echonest->getArtistApi();

Search for artists by name

$results = $echonest->getArtistApi()->search(array('name' => 'Radiohead'));
print_r($results);

  Array
  (
      [0] => Array
          (
              [name] => Radiohead
              [id] => ARH6W4X1187B99274F
          )

  )

Returns an array of results as described in http://developer.echonest.com/docs/v4/artist.html#search

Get information about an artist

$bios = $echonest->getArtistApi()->setName('Radiohead')->getBiographies();

Once you set an artists name or id on an artist API, the API will remember that artist and use them for future function calls

$artistApi = $echonest->getArtistApi();
$artistApi->setName('Radiohead');
$bios   = $artistApi->getBiographies();
$audio  = $artistApi->getAudio();
$images = $artistApi->getImages();

Each function comes with a variety of options. Please view the documentation in this project or on http://echonest.com to see all the options available

Songs

Api calls for getting data about songs. Wraps EchoNest Song API.

$songApi = $echonest->getSongApi();

Please view the documentation in this project or on http://echonest.com to see all the options available

Playlists

Api calls for generating playlists. Wraps EchoNest Playlist API.

$playlistApi = $echonest->getPlaylistApi();

Please view the documentation in this project or on http://echonest.com to see all the options available

Catalogs

API calls for managing personal catalogs. Wraps EchoNest Catalog API.

$catalogApi = $echonest->getCatalogApi();

Please view the documentation in this project or on http://echonest.com to see all the options available

Tracks

Methods for analyzing or getting info about tracks. Wraps EchoNest Track API.

$trackApi = $echonest->getTrackApi();

Please view the documentation in this project or on http://echonest.com to see all the options available

The Response

The API tries to return to you the information you typically need, and spare you information such as status codes, messages, etc, if the response was successful. Below is an example of a fully rendered response.

  Array
  (
      [status] => Array
          (
              [version] => 4.2
              [code] => 0
              [message] => Success
          )

      [artists] => Array
          (
              [0] => Array
                  (
                      [name] => Radiohead
                      [id] => ARH6W4X1187B99274F
                  )

          )

  )

Often times, the status information is not needed. However, if you would like the API to return the full response (this is often needed when dealing with pagers, as the "total" and "start" parameters are passed outside of the "artists" array, for example), set the raw option to true for your API.

// pass options to getter
$response = $echonest->getArtistApi(array('raw' => true))->search(array('name' => 'Radiohead'));

// set options manually
$artistApi = $echonest->getArtistApi();
$artistApi->setOption('raw', true);
$response = $artistApi->search(array('name' => 'Radiohead'));

If you think this is dumb, let me know and I will consider making raw the default.

Sandbox

Set up the sandbox api to begin with

$sandboxApi = $echonest->getSandboxApi()->setOAuthConfig(array(
  "consumer_key" => $consumer_key,
  "consumer_secret" => $consumer_secret
))->setSandbox($sandbox_key);

Fetch an array of all available assets

$assets = $sandboxApi->assets($start, $per_page = 100);

Access an individual asset

$sandboxApi->access($id)

Access an array of assets

$sandboxApi->access($array)

To Do

Better documentation and test coverage will be coming soon

php-echonest-api's Issues

The getSimilar Method Not Passing Parameters

The getSimilar() method in the Artist class does not pass the parameters for the request. Should be:

$response = $this->getForArtist('artist/similar', array(
'results' => $results,
'start' => $start,
'bucket' => $bucket,
'max_familiarity' => $max_familiarity,
'min_familiarity' => $min_familiarity,
'max_hotttnesss' => $max_hotttness,
'min_hotttnesss' => $min_hotttness,
'reverse' => $reverse,
'limit' => $limit,
'seed_catalog' => $seed_catalog
));

Useless switch cases and incorrect messaging in http client

HttpClient.php

/**
* Get a JSON response and transform it to a PHP array
*
* @return array the response
*/
protected function decodeResponse($response)
{
switch ($this->options['format'])
{
case 'json':
return json_decode($response, true);

        case 'jsonp':
            throw new LogicException("format 'jsonp' not yet supported by this library");

        case 'xml':
            throw new LogicException("format 'xml' not yet supported by this library");

        case 'xspf':
            throw new LogicException("format 'xspf' not yet supported by this library");
    }

    throw new LogicException(__CLASS__.' only supports json, json, xml, and xspf formats, '.$this->options['format'].' given.');
}

This should be refactored sometime as the documentation is all wrong and the exception handling is also wrong, leading to confusing errors at runtime. perhaps just use a separate method for each type as you add them, right now it's kind of YAGNI. At this point, there's no reason to offer other formats, which would save you a bunch of lines of useless code for handling unsupported formats.

Invalid Route in Method "song::identify"

Replace "song/indentify" with "song/identify" in method "identify" within "song"-api. Otherwise you get "403: Forbidden" when calling the echonest api.

J

missing argument in Api\Artist.php method getTopTerms

Parameters are missing in this file for this method ($start, $bucket, $limit)

Enable proxy option?

This might be too specialized, but I think adding a feature so people can specify a proxy server ala CURLOPT_PROXY would be a great idea, especially in situations where it would be advantageous to cache certain requests in a webcache like squid or varnish.

I'm going to write a EchoNest_HttpClient_ProxyCurl class to test it out, unless you have any objections.

Thanks!

Erro in parameters using getList() method in Catalog class

The call 'catalog/feed' on line 156 should be 'catalog/list' .

Get name of song from streaming

Hi, i´m trying to get the name of song from streaming. But no working.
Looks this post: http://developer.echonest.com/forums/thread/272#post3359

I couldn´t find way to get the post method work with option:

url = "http://api.soundcloud.com/tracks/"+str(track_id)+"/stream?consumer_key="+key
cmd = 'curl -X POST "http://developer.echonest.com/api/v4/track/upload" -d "api_key='+ECHO_NEST_API_KEY+'&wait=false&url='+urllib.quote(url)+'"'

thanks

Use output buffering in "curl"-lib of your code

Use output buffering in "protected function doCurlCall" in file curl.php to prevent instant output which is not necessary because of return values available!
If this is changed, a developer can decide whether to output the row response from echonest or to process it any further.

"CURLOPT_FOLLOWLOCATION" preventing the response from being returned

Hello,
In some cases when the php safe mode is enabled or an open_basedir is set on the server, the curl_setopt_array cannot set the CURLOPT_FOLLOWLOCATION option.
It also prevents the CURLOPT_RETURNTRANSFER option from being set as it's defined after in the following array:
$curlOptions += array( CURLOPT_URL => $url, CURLOPT_PORT => $this->options['http_port'], CURLOPT_USERAGENT => $this->options['user_agent'], CURLOPT_FOLLOWLOCATION => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => $this->options['timeout'] );

In my use case I just commented out the CURLOPT_FOLLOWLOCATION line and it seems to work very well.
I am not sure if it will be ever needed with echonest responses.

Please help me to register autoloader

Hi sorry i'm bad in PHP, me open autoloader.php file and see
/ * Registers EchoNest_Autoloader as an SPL autoloader. */
is here me insert my API key ?
Please help me send me exemple for place to write my API key with fake key ;)
Thanks

Is Local File Upload Supported?

I could easily be doing it wrong, because I know the process is different for local files than urls.

Here is a minimized function call of what I'm attempting to do:
$results = $results->upload('../Libraries/54 The Con.m4a', true, 'm4a',$_FILES);

Currently this call just fails with no error message. My best guess is that passing $_FILES is not the correct way to pass the track, but I can't think of any way to pass it otherwise.

I tried unrolling it to the request() function, and I thought from the variable name" $url" it may be assuming a url is being passed. PHP isn't my strongest language though.

api id not recognised?

Hello,

Thanks for your assistance before. I have been trying to get track info from an mp3 at a certain location, which I upload first. But I get the following error code (my ID is correct btw). Perhaps it makes more sense to you?

Fatal error: Uncaught exception 'EchoNest_HttpClient_Exception' with message '1|Invalid key: Unknown' in /home/suneesto/addons/drupalfun.com/dance/php-echonest-api-master/lib/EchoNest/HttpClient.php:110 Stack trace: #0 /home/suneesto/addons/drupalfun.com/dance/php-echonest-api-master/lib/EchoNest/HttpClient.php(78): EchoNest_HttpClient->request('track/upload', Array, 'POST', Array) #1 /home/suneesto/addons/drupalfun.com/dance/php-echonest-api-master/lib/EchoNest/Client.php(97): EchoNest_HttpClient->post('track/upload', Array, Array) #2 /home/suneesto/addons/drupalfun.com/dance/php-echonest-api-master/lib/EchoNest/Api/Track.php(105): EchoNest_Client->post('track/upload', Array) #3 /home/suneesto/addons/drupalfun.com/dance/uploader.php(24): EchoNest_Api_Track->upload('http://drupalfu...', true, 'mp3', NULL, NULL) #4 {main} thrown in /home/suneesto/addons/drupalfun.com/dance/php-echonest-api-master/lib/EchoNest/HttpClient.php on line 110

This is my code:

require_once 'php-echonest-api-master/lib/EchoNest/Autoloader.php';
EchoNest_Autoloader::register();
$echonest = new EchoNest_Client();
$apikey = 'XXXmycorrectkey';
$echonest->authenticate($apiKey);

$url='http://drupalfun.com/dance/fastcar.mp3';
$trackApi = $echonest->getTrackApi()->upload($url, $wait = true, $filetype = mp3, $bucket = null, $track = null);

PHP Fatal Error in Initialization in some PHP Versions

Filed by Nick Hodren:

    Been getting this error when trying to initialize the object. Got a quick fix?

    Fatal error: Declaration of EchoNest_HttpClient_Curl::doRequest() must be compatible with that of     
    EchoNest_HttpClient::doRequest() in/var/www/vhosts/hipscout.com/httpdocs/lib/EchoNest/HttpClient/Curl.php on line 9

missing genre to search genres

Hi, It would be helpful to have a search for genres on the API.
http://developer.echonest.com/docs/v4/genre.html

Thanks, very nice API ;)