NAME

Net::LastFMAPI - LastFM API 2.0

SYNOPSIS

  use Net::LastFMAPI;
  my $perl_data = lastfm("artist.getSimilar", artist => "Robbie Basho");

  # sets up a session/gets authorisation when needed for write actions:
  my $res = lastfm(
      "track.scrobble",
      artist => "Robbie Basho",
      track => "Wounded Knee Soliloquy",
      timestamp => time(),
  );
  $success = $res->{scrobbles}->{'@attr'}->{accepted} == 1;

  my $xml = lastfm(...); # with config value: xml => 1
  my $xml = lastfm(..., format => "xml");
  $success = $xml =~ m{<scrobbles accepted="1"};

  # paginated data can be iterated through per row
  my $iter = lastfm_iter("artist.getTopTracks", artist => "John Fahey");
  while (my $row = $iter->()) {
      say $row->{playcount} .": ". $row->{name};
      my $whole_response = $Net::LastFMAPI::last_response;
  }

  # wantarray? tries to extract the rows of data for you
  my @rows = lastfm(...);

  # see also:
  # bin/cmd.pl album.getInfo artist=Laddio Bolocko album=As If In Real Time
  # bin/scrobble.pl Artist - Track
  # bin/portablog-scrobbler.pl

DESCRIPTION

Makes requests to http://ws.audioscrobbler.com/2.0/ and returns the result.

Takes care of POSTing to write methods, doing authorisation when needed.

Dies if something went obviously wrong.

Can return xml if you like, defaults to returning perl data (requesting json). Beware of "@attr" and empty elements turned into whitespace strings instead of empty arrays, single elements turned into a hash instead of an array of one hash.

SESSION KEY AND AUTHORISATION

  lastfm_config(
      session_key => $key,
  );

The session key will be sought when an authorised request is needed. See CONFIG.

If it is not configured or saved then on-screen instructions should be followed to authorise in a web browser with whoever is logged in to last.fm. See http://www.last.fm/api/desktopauth.

It is saved in the file File::HomeDir::my_home()/.net-lastfmapi-sessionkey by default. This is probably fine.

Consider altering the subroutines talk_authentication, load_save_sessionkey, or simply configuring (see CONFIG) before needing it.

CACHING

  lastfm_config(
      # to enable caching
      cache => 1,
      # default:
      cache_dir => File::HomeDir::my_home()."/.net-lastfmapi-cache/",
  );

Good for development.

RETURNING ROWS

  my @artists = lastfm("artist.getSimilar", ...);

Call lastfm in list context. Attempts to extract for you the rows inside the response. The whole response is in $Net::LastFMAPI::last_response. See also PAGINATION

RETURN XML

  lastfm_config(xml => 1);
  # or
  lastfm(..., format => "xml"):

This will return an xml string to you. You can also set format => "xml" for a particular request. Default format is JSON, as getting perl data is much from the lastfm method is more casual.

PAGINATION

  my $iter = lastfm_iter(...);
  while (my $row = $iter->()) {
      ...
  }

Will attempt to extract rows from a response, passing you one at a time, keeping going into the next page, and the next...

CONFIG

  lastfm_config(
      # associates the request with a user
      # got with their permission initially
      session_key => $key,

      # these are explained elsewhere in this pod
      xml => 1,
      cache => 1,
      cache_dir => $path,


      # for your own api account see http://www.last.fm/api/account
      # you can use this module's (default) api account fine
      api_key => $your_api_key,
      secret => $your_secret,

      # LWP::UserAgent-sorta thing
      ua => $ua,

      # default File::HomeDir::my_home()/.net-lastfmapi-sessionkey
      sk_savefile => $path,
  );

cache and cache_dir are likely most popular, see CACHING.

This module can handle the session_key fine, see "SESSION KEY AND AUTHORISATION".

api_key and secret are for representing this module on the page where the user authorises their account in the process of acquiring a new session_key. You might want to have your own identity in there.

SEE ALSO

Net::LastFM doesn't handle sessions for you, won't POST to write methods

I had no luck with the 1.2 API modules: WebService::LastFM, Music::Audioscrobbler::Submit, Net::LastFM::Submission

BUGS/CODE

https://github.com/st3vil/Net-LastFMAPI

AUTHOR

Steev Eeeriumn <drsteve@cpan.org>

COPYRIGHT

   Copyright (c) 2011, Steev Eeeriumn. All Rights Reserved.
 This module is free software. It may be used, redistributed
and/or modified under the terms of the Perl Artistic License
     (see http://www.perl.com/perl/misc/Artistic.html)

cpanm Net::LastFMAPI

perl -MCPAN -e shell
install Net::LastFMAPI