/ 
WebService-Pandora-0.4
River stage zero No dependents
/ WebService::Pandora

NAME

WebService::Pandora - Pandora WebService API

SYNOPSIS

use WebService::Pandora;

$websvc = WebService::Pandora->new( username => 'emailaddress',
                                    password => 'password' );

$websvc->login() or die( $websvc->error() );

$result = $websvc->getStationList();

die( $websvc->error() ) if ( !$result );

$stations = $result->{'stations'};

foreach $station ( @$stations ) {

  print "stationToken: $station->{'stationToken'}\n";
}

# get a new list of tracks to play from one of my stations
$result = $websvc->getPlaylist( stationToken => 'token' );

die( $websvc->error() if ( !$result );

$tracks = $result->{'items'};

foreach $track ( @$tracks ) {

  print "trackToken: $track->{'trackToken'}\n";

  # you can download/play the song at this URL
  $url = $track->{'audioUrl'};
}

# this track sucked, thumbs down!
$result = $websvc->addFeedback( trackToken => 'token',
                                isPositive => 0 );

DESCRIPTION

WebService::Pandora is a module to communicate with the Pandora (http://www.pandora.com) JSON API. The API is not officially published, and has a few oddities, but was reverse engineered and documented at http://pan-do-ra-api.wikia.com/wiki/Pan-do-ra_API_Wiki.

CONSTRUCTOR

new

Creates a new WebService::Pandora object with the arguments given. The username and password arguments are currently required. The partner option defaults to WebService::Pandora::Partner::iOS, but any WebService::Pandora::Partner object may be given. The timeout option is passed to the underlying LWP::UserAgent object, and defaults to 10 (seconds).

$websvc = WebService::Pandora->new( username => 'emailaddress',
                                    password => 'password',
                                    timeout => 10,
                                    partner => WebService::Pandora::Partner::iOS->new() );

METHODS

All methods will return a false value if they weren't given the proper arguments, if there was an HTTP communication error, or if the Pandora API returned an error. Use the error() method to get an error message describing the failure.

login

Returns a true or false value if the login was successful. Internally, this will execute both the auth.partherLogin and auth.userLogin API methods. The provided partner, username, and password to the constructor are all used. This must be called before any other methods will succeed.

$success = $websvc->login() or die( $websvc->error() );

error

Returns a string containing a message about why the last method call failed. The error string may come from internally in the module, from a failed HTTP request, or from the Pandora API itself.

getBookmarks

Executes the user.getBookmarks method, returning a hashref containing the artists and songs that the user has bookmarked, or a false value on failure. Must be called after the login() method.

$result = $websvc->getBookmarks() or die( $websvc->error() );

$artists = $result->{'artists'};
$songs = $result->{'songs'};

getStationList

Executes the user.getStationList method, returning a hashref containing all of the stations of the user, or a false value on failure. Must be called after the login() method.

$result = $websvc->getStationList() or die( $websvc->error() );
$stations = $result->{'stations'};

getStationListChecksum

Executes the user.getStationListChecksum method, returning a hashref containing a checksum value, or a false value on failure. I do not know what the point of this method is. Must be called after the login() method.

$result = $websvc->getStationListChecksum() or die( $websvc->error() );
$checksum = $result->{'checksum'};

getStation

Executes the station.getStation method, returning a hashref containing several attributes about the station, identified by the provided stationToken argument, or will return a false value on failure. If the includeExtendedAttributes option is given with a true value, additional attributes, such as all of the songs that have feedback in this station, will be returned as well. Must be called after the login() method.

$result = $websvc->getStation( stationToken => "token",
                               includeExtendedAttributes => 1 ) or die( $websvc->error() );
$name = $websvc->{'stationName'};
stationToken => STRING [required]

The unique token of the station, which can be obtained via the getStationList() method.

includeExtendedAttributes => BOOLEAN [optional]

Whether or not to include additional information about the station. Defaults to false.

getGenreStations

Executes the station.getGenreStations method, returning a hashref containing the information about the predefined stations according to genre, or will return a false value on failure. Must be called after the login() method.

$result = $websvc->getGenreStations() or die( $websvc->error() );
$categories = $result->{'categories'};

getGenreStationsChecksum

Executes the station.getGenreStationsChecksum method, returning a hashref containing a checksum value, or a false value on failure. I do not know what the point of this method is. Must be called after the login() method.

$result = $websvc->getGenreStationsChecksum() or die( $websvc->error() );
$checksum = $result->{'checksum'};

Executes the music.search method, returning a hashref containing the songs and artists that match the provided searchText argument, or a false value on failure. Must be called after the login() method.

$result = $websvc->search( searchText => "query" ) or die( $websvc->error() );

$songs = $result->{'songs'};
$artists = $result->{'artists'};
searchText => STRING [required]

The search query to find matching songs and artists for.

getPlaylist

Executes the station.getPlaylist method, returning a hashref containing the tracks and their URLs for the provided stationToken, which can be used to download or play the song, or a false value on failure. Must be called after the login() method.

You may only execute this method a certain number of times within a particular timeframe, or Pandora will deny the request, and this method will thus return an error.

$result = $websvc->getPlaylist( stationToken => "token" ) or die( $websvc->error() );
$songs = $result->{'items'};
stationToken => STRING [required]

The unique token of the station, which can be obtained via the getStationList() method.

explainTrack

Executes the track.explainTrack method, returning a hashref containing all of the explanations of the traits of the song, provided by the trackToken argument, or will return a false value on failure. Must be called after the login() method.

$result = $websvc->explainTrack( trackToken => 'token' ) or die( $websvc->error() );
trackToken => STRING [required]

The unique token of the track, which can be obtained via the getPlaylist() and other methods.

addArtistBookmark

Executes the bookmark.addArtistBookmark method, returning a hashref containing the information of the artist and the new bookmark, provided by the trackToken argument, or will return a false value on failure. Must be called after the login() method.

$result = $websvc->addArtistBookmark( trackToken => 'token' ) or die( $websvc->error() );
$bookmarkToken = $result->{'bookmarkToken'};
trackToken => STRING [required]

The unique token of the track, which can be obtained via the getPlaylist() and other methods.

addSongBookmark

Executes the bookmark.addSongBookmark method, returning a hashref containing the information of the song and the new bookmark, provided by the trackToken argument, or will return a false value on failure. Must be called after the login() method.

$result = $websvc->addSongBookmark( trackToken => 'token' ) or die( $websvc->error() );
$bookmarkToken = $result->{'bookmarkToken'};
trackToken => STRING [required]

The unique token of the track, which can be obtained via the getPlaylist() and other methods.

addFeedback

Executes the station.addFeedback method, returning a hashref containing the information of the song and the new feedback record, provided by the trackToken argument, or will return a false value on failure. If the given isPositive argument is a true falue, the song will be given a "thumbs up", otherwise a false value will give it a "thumbs down." Must be called after the login() method.

$result = $websvc->addFeedback( trackToken => "token",
                                isPositive => 1 ) or die( $websvc->error() );
$feedbackId = $result->{'feedbackId'};
trackToken => STRING [required]

The unique token of the track, which can be obtained via the getPlaylist() and other methods.

isPositive => BOOLEAN [required]

A true value will give the track a "thumbs up" and a false value will give it a "thumbs down."

sleepSong

Executes the user.sleepSong method, returning a true value if the song was successfully put to sleep, provided by the trackToken argument, or will return a false value on failure. This prevents the song from being played again for 30 days.

$result = $websvc->sleepSong( trackToken => "token" ) or die( $websvc->error() );
trackToken => STRING [required]

The unique token of the track, which can be obtained via the getPlaylist() and other methods.

deleteFeedback

Executes the station.deleteFeedback method, returning a true value if the feedback was successfully deleted, or a false value on failure. Must be called after the login() method.

$result = $websvc->deleteFeedback( feedbackId => "id" ) or die( $websvc->error() );
feedbackId => STRING [required]

The id of the feedback, which can be obtained via the getStation() and other methods.

addMusic

Executes the station.addMusic method, returning a hashref containing the information of the song or artist, provided by the musicToken argument, or will return a false value on failure. The additional music seed is added to the specified station via the stationToken argument. A musicToken can be obtained via the search() method. Must be called after the login() method.

$result = $websvc->addMusic( musicToken => 'token',
                             stationToken => 'token' ) or die( $websvc->error() );
$seedId = $result->{'seedId'};
musicToken => STRING [required]

The unique token of the artist or song, which can be obtained via the search() and other methods.

stationToken => STRING [required]

The unique token of the station, which can be obtained via the getStationList() and other methods.

deleteMusic

Executes the station.deleteMusic method, returning a true value if the music was successfully deleted, or a false value on failure. Must be called after the login() method.

$result = $websvc->deleteMusic( seedId => 'id' ) or die( $websvc->error() );
seedId => STRING [required]

The id of the music seed associated to the station, which can be obtained via the getStation() and other methods.

canSubscribe

Executes the user.canSubscribe method, returning a hashref containing the information about whether the user is able to subscribe to Pandora One or not, or will return a false value on failure. Must be called after the login() method.

$result = $websvc->canSubscribe() or die( $websvc->error() );

$canSubscribe = $result->{'canSubscribe'};
$isSubscriber = $result->{'isSubscriber'};

createStation

Executes the station.createStation method, returning a hashref containing the information about the created station, provided by either the musicToken or the trackToken arguments, or will return a false value on failure. A station can be created by either a track or an artist, which must be specified via the musicType argument. Must be called after the login() method.

$result = $websvc->createStation( musicToken => "token",
                                  musicType => "song" ) or die( $websvc->error() );

$result = $websvc->createStation( trackToken => "token",
                                  musicType => "artist" ) or die( $websvc->error() );
musicType => "song" | "artist" [required]

Specifies whether the station should be based upon the provided song or artist via either the musicToken or trackToken arguments, whichever is given.

musicToken => STRING [optional]

The token, generally obtained via the search() method, of either the song or artist to create a station from. Either this or the trackToken argument must be given.

trackToken => STRING [optional]

The token, generally obtained via the getPlaylist() method, of either the song or artist to create a station from. Either this or the musicToken argument must be given.

renameStation

Executes the station.renameStation method, returning a hashref containing the new information about the station, provided by the stationToken argument, or will return a false value on failure. The new name of the station is provided by the stationName option. Must be called after the login() method.

$result = $websvc->renameStation( stationToken => 'token',
                                  stationName => 'new name' ) or die( $websvc->error() );
$stationName = $result->{'stationName'};
stationToken => STRING [required]

The unique token of the station, which can be obtained via the getStationList() and other methods.

stationName => STRING [required]

The new name of the station.

shareStation

Executes the station.shareStation method, returning a true value if the station, provided by the stationId and stationToken arguments, was shared successfully, or a false value on failure. Must be called after the login() method.

$result = $websvc->shareStation( stationId => 'id',
                                 stationToken => 'token',
                                 emails => ['foo@bar.com', 'baz@buz.com'] )
  or die( $websvc->error() );
stationId => STRING [required]

The unique id of the station, which can be obtained via the getStationList() and other methods.

stationToken => STRING [required]

The unique token of the station, which can be obtained via the getStationList() and other methods.

emails => ARRAY [required]

A list of email addresses to share the station with.

deleteStation

Executes the station.deleteStation method, returning a true value if the station was successfully deleted, or a false value on failure. Must be called after the login() method.

$result = $websvc->deleteStation( stationToken => 'token' ) or die( $websvc->error() );
stationToken => STRING [required]

The unique token of the station, which can be obtained via the getStationList() and other methods.

setQuickMix

Executes the user.setQuickMix method, returning a true value if the quick mix was successfully set, or a false value on failure. Must be called after the login() method.

$result = $websvc->setQuickMix( stationIds => ['id1', 'id2'] ) or die( $websvc->error() );
stationIds => ARRAY [required]

A list of station ids that uniquely identify each station, which can be obtained via the getStationList() and other methods.

transformSharedStation

Executes the station.transformSharedStation method, returning a hashref containing the information about the station, provided by the stationToken argument, or will return a false value on failure. This method will convert a station that someone has shared to you into a station of your own that you are able to modify. Must be called after the login() method.

$result = $websvc->transformSharedStation( stationToken => "token" ) or die( $websvc->error() );
$stationId = $result->{'stationId'};
stationToken => STRING [required]

The unique token of the station, which can be obtained via the getStationList() and other methods.

SEE ALSO

WebService::Pandora::Method WebService::Pandora::Partner

AUTHOR

Mitch McCracken <mrmccrac@gmail.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2013 by Mitch McCracken.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)