The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
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.