/ 
WWW-EchoNest-v0.0.2
River stage zero No dependents
/ WWW::EchoNest::Catalog

NAME

WWW::EchoNest::Catalog

SYNOPSIS

Create catalogs of artists and songs for a given API Key. For example, Catalog names can be provided as arguments to some of the Playlist methods, to return only songs that are by artists in a given catalog.
Please go to <http://developer.echonest.com/docs/v4/catalog.html> for more information about the way the Echo Nest Catalog API works.

METHODS

new

Returns a new WWW::EchoNest::Catalog instance.

NOTE:
  WWW::EchoNest also provides the get_catalog() convenience function
  to create new instances of WWW::EchoNest::Catalog.

ARGUMENTS:
  id        => a catalog id
  name      => a catalog name
  type      => 'song' or 'artist' -- specifies the catalog type

RETURNS:
  A new instance of WWW::EchoNest::Catalog.

EXAMPLE:
  use WWW::EchoNest::Catalog;
  $catalog = WWW::EchoNest::Catalog->new({ name => 'my_songs', type => 'songs' });
  print 'id : ', $catalog->get_id, "\n";
  
  ######## Results will differ ########
  #
  # id : CAPSBIZ131500C102A

  # or...

  use WWW::EchoNest qw( :all );
  # Note:
  # - <type> defaults to song, so all we need is a name
  # - this method also could have been called with the HASH ref above
  $catalog = get_catalog('my_songs');
  print 'id : ', $catalog->get_id, "\n";
  
  ######## Results may differ ########
  #
  # id : CAPSBIZ131500C102A

add_song

Add some Song objects to add to the catalog.

ARGUMENTS:
  Some WWW::EchoNest::Song objects.

RETURNS:
  A reference to an array of tickets to be used with the 'status' method.

EXAMPLE:
  use WWW::EchoNest qw( :all );
  my $imagine_song      = get_song('SOFNJLR1312FDFABE5');
  my $satisfaction_song = get_song('SOMEEYZ12A8C1430B5');
  my @song_list = ( $imagine_song, $satisfaction_song );
  my $catalog = get_catalog('classic_songs');
  my $tickets_ref = $catalog->add_song( @song_list );
  my %status_for = map { $_ => $catalog->status($_) } @$tickets_ref;

  use Data::Dumper;
  for (keys %status_for) {
      print "ticket: $_\n";
      print 'status: ' . $status_for{$_}{'ticket_status'};
  };
  
  ######## Results may differ ########
  #
  # ticket : <insert_ticket_number_here>
  # status : complete

add_artist

Add some Artist objects to add to the catalog.

ARGUMENTS:
  Some WWW::EchoNest::Artist objects.

RETURNS:
  A reference to an array of tickets to be used with the 'status' method.

EXAMPLE:
  use WWW::EchoNest qw( :all );
  my $beatles = get_artist('The Beatles');
  my $stones  = get_artist('The Rolling Stones');
  my $catalog = get_catalog( { name => 'classic_artists', type => 'artist' } );
  my $tickets_ref = $catalog->add_artist( $beatles, $stones );
  my %status_for = map { $_ => $catalog->status($_) } @$tickets_ref;

  use Data::Dumper;
  for (keys %status_for) {
      print "ticket: $_\n";
      print 'status: ' . $status_for{$_}{'ticket_status'};
  };
  
  ######## Results may differ ########
  #
  # ticket : <insert_ticket_number_here>
  # status : complete

status

Check the status of a catalog update.

ARGUMENTS:
  ticket => A string representing a ticket ID.

RETURNS:
  A hash ref that contains info about a ticket's status.

EXAMPLE:
  use WWW::EchoNest qw( :all );
  my $catalog = catalog( { name => 'my_songs', type => 'songs' } );
  # Make an update, and store the ticket id as $ticket_id
  use Data::Dumper;
  print 'status : ', pretty_json( $catalog->status($ticket_id) ), "\n";
  
  ######## Results may differ ########
  #
  # status: {
  #     ticket_status => 'complete',
  #     update_info => [
  #     ]
  # };

get_profile

Get basic information about a catalog.

ARGUMENTS:
  none

RETURNS:
  A hash ref to a description of a catalog.

EXAMPLE:
  use WWW::EchoNest qw( :all );
  # Create a catalog and store it as $catalog...
  # Do some stuff with the catalog, like making updates...
  print 'profile: ', pretty_json( $catalog->get_profile ), "\n";
  
  ######## Results may differ ########
  #
  # profile: {
  #     'id'                => 'CAMSSDQ1303D86C20D',
  #     'name'              => 'catalog_foo_by_song',
  #     'pending_tickets'   => [],
  #     'resolved'          => 2,
  #     'total'             => 2,
  #     'type'              => 'song'
  # };

read_items

Returns data from the catalog. Expands the requested buckets.

ARGUMENTS:
  buckets   => A list of strings specifying which buckets to retrieve
  results   => An integer number of results to return (defaults to 15)
  start     => An integer starting value for the result set
  
  See <http://developer.echonest.com/docs/v4/catalog.html#read> for more info about possible values for 'buckets'.


RETURNS:
  An array ref of objects in the catalog.

EXAMPLE:
  use WWW::EchoNest qw( :all );
  # Create a catalog and store it as $catalog...
  # Do some stuff with the catalog, like making updates...
  my $items = $catalog->read_items( { results => 1 } );
  print 'items: ', pretty_json( $items ), "\n";
  
  ######## Results may differ ########
  #
  # items: {
  # }

get_feed

Returns feed (news, blogs, reviews, audio, video) for the catalog artists;
response depends on requested buckets

ARGUMENTS:
  buckets   => A list of strings specifying which buckets to retrieve
  results   => An integer number of results to return (defaults to 15)
  start     => An integer starting value for the result set

  See <http://developer.echonest.com/docs/v4/catalog.html#read> for more info about possible values for 'buckets'.


RETURNS:
  A reference to an array of news, blogs, reviews, audio or video document hash refs.

EXAMPLE:
  use WWW::EchoNest qw( :all );
  # Create a catalog and store it as $catalog...
  # Do some stuff with the catalog, like making updates...
  my $feeds = $catalog->get_feed( { results => 1 } );
  print 'feeds: ', pretty_json( $feed ), "\n";

  ######## Results will differ ########
  #
  # Insert printout here!
  #
  #

delete

Deletes the entire catalog.

ARGUMENTS:
  none

RETURNS:
  The deleted catalog's id.

EXAMPLE:
  use WWW::EchoNest qw( :all );
  # Create a catalog and store it as $catalog...
  my $deleted_id = $catalog->delete();
  print "Deleted catalog $catalog_id\n";

  ######## Results will differ ########
  #
  # Deleted catalog CAMSSDQ1303D86C20D
  #

FUNCTIONS

list_catalogs

Returns a list of all catalogs for a given API key.

ARGUMENTS:
  results => An integer number of results to return (defaults to 30)
  start   => An integer starting value for the result set

RETURNS:
  A reference to an array of references to Catalog objects.

EXAMPLE:
  use WWW::EchoNest qw( :all );
  # Create some catalogs...
  my $catalog_list = list_catalogs( { results => 1 } );
  print 'Catalogs: ', pretty_json( $catalog_list ), "\n";

  ######## Results will differ ########
  #
  # Catalogs: {
  # }
  #

AUTHOR

Brian Sorahan, <bsorahan@gmail.com>

SUPPORT

Join the Google group: <http://groups.google.com/group/www-echonest>

ACKNOWLEDGEMENTS

Thanks to all the folks at The Echo Nest for providing access to their powerful API.

LICENSE

Copyright 2011 Brian Sorahan.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.