WWW::TheEchoNest - Wrapper for The Echo Nest API of music intelligence
version 1.1
See the specific types of calls for details. All types (Artist,Song,etc) inherit from this module and you could call them via those objects.
WWW::TheEchoNest::Artist WWW::TheEchoNest::Codegen WWW::TheEchoNest::Playlist WWW::TheEchoNest::Song WWW::TheEchoNest::TasteProfile WWW::TheEchoNest::Track
WWW::TheEchoNest provides a robust wrapper around The Echo Nest API to provide access to nearly all the current features and provide some flexibility should features change without having to rely on an update to this module.
You must read The Echo Nest documentation. This module attempts to provide as much coverage as possible for their API and the structure resembles the calls url as closely as possible. One excpetion to this is the tasteprofile/dynamic calls that have an additional URL part (dynamic/create, etc), these are represented as dynamic_create, dynamic_next, etc.
http://developer.echonest.com/docs/v4
Have access to a JSON viewer to help develop and debug. The Chrome JSON viewer is very good and provides the exact path of the item within the JSON in the lower left of the screen as you mouse over an element.
WWW::TheEchoNest
Moose
IO::CaptureOutput
Scalar::Util
HTTP::Headers
XML::Simple
JSON::Path
JSON::XS
WWW::Mechanize
URI::Escape
Digest::MD5::File
You may see these mentioned in the examples in the Artist, Song, etc.
When this is set to 1 debugging statements will be displayed.
$artist->debug(1);
One item that will be displayed is the URL that was constructed. This can help you track down cases where your parameters were dropped.
Returns a specific item or array of items from the JSON result of the last action.
$song->search( title => 'Stairway to Heaven', artist => 'Led Zeppelin' ); my $track_id = $song->get( 'songs[0].tracks[0].id' );
JSON::Path is the underlying library that actually parses the JSON.
This can also be called in an array context so you can get all of the items.
$playlist->basic( artist => 'Weezer', type => 'artist-radio' ); my @songs = $catalog->get( 'songs[*]' );
my $status_code_as_string = $artist->get_status_code();
or
my $status_code_as_number = $artist->get_status_code(1);
Refer to The Echo Nest documentation for information on possible response codes.
The Echo Nest restricts calls to their API via a rate limit. To acces your current rate limit use the rate_limit method. It will return a numerical value that represents the number of requests per minute you are allowed to make.
$artist->rate_limit();
Will return the number of calls remaining in your rate limit
$artist->rate_limit_remaining();
Will return the number of calls you have made to the rate limit
$artist->rate_limit_used();
Will return any item you specify from the http header. You generally only need to use the rate_ calls, but if something changes in the API response this method would allow you to access it.
$artist->get_header_item('X-Rate-Limit');
There is an attempt to enforce that required items are passed for each call this method can help you determine what the current setting is for a particular call.
my @grp = $song->get_request_parameter( 'song/search' , 'limit' );
It returns an array of the contents, will be 1 or 2 elements, the first is if the item is required and the second is if it has a limit of how many of them can be passed per request.
In order to allow you to create your own restrictions or add items that become available after this module was created you can use the set_ method below
Allows you to add a new request parameter or enforce a restriction. For example you might want to enfore an artist_id is always passed into song/search
$artist->set_request_parameter( 'song/search' , [ 'artist_id' , 1 ] );
or to add a new item
$artist->set_request_parameter( 'song/newfeature' , [ 'limit' , 1 ] );
This same process is what disallows/prevents parameters that aren't already in the list from being sent. See debug below for more info.
When this is set all calls will return a perl data structure rather than the JSON
$artist->auto_json_decode(1);
NOTE: You can still access the JSON via the last_result() method
When this is set all calls will return a perl data structure rather than XML
You must also set the result_format to 'xml' for this to work
$artist->auto_xml_decode(1);
NOTE: You can still access the XML via the last_result() method
Will give you the actual output from the call to the API. The format will match the result_format you specified for the request. The default output is JSON.
print $artist->last_result();
Will provide information on possible errors encounterd on your method call. This is a plain text string with content like:
"invalid json passed into tasteprofile/update"
print $artist->last_error();
These typically never need to be used directly, but are provided here in case you feel the need to look under the hood.
These are not documented as of the .02 release since they aren't normally needed possibly in future releases these will be documented more.
Provides access to attribute errors that are set when a call fails due to missing parameters or mispellings
$obj->attribute_error();
Can provide you with a base url if feed the proper paramters.
$obj->build_url_base();
$obj->format_results();
$obj->is_valid_id();
$obj->part_of_seed_limit();
$obj->request_with_minimum();
$obj->request_with_no_minimum();
$obj->sanity_check_id();
$obj->seed_count_met();
$obj->send_get_request();
$obj->send_post_request();
$obj->get_file_extension();
$obj->get_resource_md5();
$obj->is_valid_json();
Brian Sorahan is the authoer of WWW::EchoNest and some ideas and a couple chunks of code served as a guideline. It has many convience methods that may make it a better choice for some use cases.
Aaron Johnson <aaronjjohnson@gmail.com>
This software is copyright (c) 2014 by Aaron Johnson.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install WWW::TheEchoNest, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::TheEchoNest
CPAN shell
perl -MCPAN -e shell install WWW::TheEchoNest
For more information on module installation, please visit the detailed CPAN module installation guide.