NAME WWW::ThisIsMyJam - Synchronous and asynchronous interfaces to This Is My Jam SYNOPSIS use WWW::ThisIsMyJam; my $jam = WWW::ThisIsMyJam->new; $jam->person('jamoftheday'); Description This module provides access to Jam data through the new, official API in synchronous or asynchronous mode. The asynchronous mode requires you have AnyEvent and AnyEvent::HTTP available. However, since it's just *supported* and not *necessary*, it is not declared as a prerequisite. Methods This Is My Jam provides an ultra simple, JSON-based API. First, we'll cover public utility methods and then the categorized Jam functions. Standard new( ) Creates a new WWW::ThisIsMyJam object. # typical usage my $jam = WWW::ThisIsMyJam->new; # it would be pointless to change these, but it's possible my $jam = WWW::ThisIsMyJam->new( apiversion => 1, basename => 'http://api.thisismyjam.com' ); Person Person methods cover a single user. user( person ) A user's overview data includes all information about the requested person along with their current jam (if any). All methods require at least a username. # Fetch info for the Jam of the Day account my $overview = $timj->user( 'jamoftheday' ); # Use callbacks for a specific user $timj->user( 'jamoftheday', { cb => sub { my ( $overview ) = @_; ... } }); likes( person ) Returns a list of liked jams. Takes the optional parameter 'show', which specifies whether to include only current or past (expired) jams. # Get jams I like $timj->likes( 'jamoftheday' ); # Only get active jams $timj->likes({ person => 'jamoftheday', show => 'current' }); # Only get expired jams $timj->likes({ person => 'jamoftheday', show => 'past' }); jams( person ) Returns a list of the person's jams. Optional parameter 'show' can be set to only show past (expired) jams. # Get all of a user's jams $timj->jams({ person => 'jamoftheday' }); # Only get (expired) jams from the past $timj->jams({ person => 'jamoftheday', show => 'past' }); following( person ) Returns a list of people that a particular person is following. Optional parameter 'order' can be set to sort the users: "order => 'followedDate'" orders by date followed; "order => 'affinity'" currently orders by number of likes from the requested person; "order => 'name'" orders by name alphabetically. While omitted from the official documentation, observation indicates that 'affinity' is the default order. # Get users the person if following $timj->following({ person => 'jamoftheday' }); # Get users the person is following sorted by name $timj->following({ person => 'jamoftheday', order => 'name' }); followers( person ) Returns a list of people that a particular person is followed by. Optional parameter 'order' can be set to sort the users: "order => 'followedDate'" orders by date followed; "order => 'affinity'" currently orders by number of likes from the requested person; "order => 'name'" orders by name alphabetically. While omitted from the official documentation, observation indicates that 'affinity' is the default order. # Get users the person if following $timj->followers({ person => 'jamoftheday' }); # Get users the person is following sorted by name $timj->followers({ person => 'jamoftheday', order => 'name' }); follow( person ) Follow the specified user. Requires authentication. # Follow someone $timj->follow({ person => 'jamoftheday' }); unfollow( person ) Unfollow the specified user. Requires authentication. # Unfollow someone $timj->unfollow({ person => 'jamoftheday' }); Jam Jam methods return metadata about a single or list of jams. jam( id ) Retrieves information on a single jam by ID. # Get info about a jam. (Jam of the Day from March 6th, 2013) $timj->jam( { id => '4zugtyg' }); likers( id ) Returns a list of the people who liked a particular jam. # Get a list of people who liked the Jam of the Day from March 6th, 2013 $timj->likers( { id => '4zugtyg' }); Note: "likers" isn't a word. I may change the name of this method before v1.0.0. comments( id ) Returns a list of the comments that have been added to a jam. # What you say? $timj->comments({ id => '4zugtyg' }); like( id ) Like a jam. You can only like jams that are currently active. Requires authentication. $timj->like({ id => '4zugtyg' }); unlike( id ) Unlike a jam. You can only unlike jams that are currently active. Requires authentication. $timj->like({ id => '4zugtyg' }); post_comment( id, comment ) Post a new comment on a jam. Requires authentication. # Add nothing to the conversation $timj->post_comment({ id => '4zugtyg', comment => '+1' }); rejammers( id ) Returns a list of people who rejammed this jam. # Find out *true* fans of this jam $timj->rejammers({ id => '4zugtyg' }); Comments get_comment( id ) Retrieve a single comment by ID. # What's the story, morning glory? $timj->delete_comment({ id => 'q0hdq3' }); delete_comment( id ) Delete a single comment. Only the author of the comment and the person who posted the jam can delete it. Requires authentication. # Quiet, you! $timj->delete_comment({ id => 'q0hdq3' }); Explore popular_jams( ) Returns a list of today's most loved jams. $timj->popular_jams(); trending_jams( ) Returns a list of songs getting a lot of recent attention. $timj->trending_jams(); rare_jams( ) Returns a list of tracks we don't hear that often. $timj->rare_jams(); random_jams( ) Returns a random list of current jams. $timj->random_jams(); newbie_jams( ) Returns a list of jams from people who have just joined This Is My Jam. $timj->newbie_jams(); related_jams( username ) A list of jams related to username's current jam. # Grab jams related to the current Jam of the Day $timj->related_jams({ username => 'jamoftheday' }); Yes, I know the person vs. username inconsistency. Blame This Is My Jam's API designers or forget it and just use the short method call: # Same as above but less confusing $timj->related_jams( 'jamoftheday' ); Search Search methods return lists of related material. With great power... search_jams( by, q ) Searching by artist will return jams by or similar to the requested artist. Genre search is powered by Last.fm tag search. # Find jams similar to those by The Knife $timj->search_jams({ by => 'artist', q => 'the knife' }); # Find electronica jams $timj->search_jams({ by => 'genre', q => 'electro' }); search_people( by, q ) You can either search for people by name, artist and track. Searching by name returns people with the search string in their username, full name or Twitter name. Searching by artist returns people who have posted tracks by artists (fuzzy) matching the search string. Searching by track returns people who have posted a particular track (strict, case-insensitive matching). # Find users with the word 'jam' in their name, username, twitter handle $timj->search_people({ by => 'name' , q => 'jam' }); # Find users who jam out to music by The Beach Boys $timj->search_people({ by => 'artist', q => 'beach boys' }); # Find users who jam out to 'Video Games' by Lana del Rey $timj->search_people({ by => 'track', q => 'Lana del Rey|Video games' }); Miscellaneous verify( ) Returns information about the currently authenticated user. # Eh? $timj->verify(); API Methods and Arguments Most This Is My Jam API methods take parameters. All WWW::ThisIsMyJam API methods will accept a HASH ref of named parameters as specified in the This Is My Jam API documentation. For convenience, many WWW::ThisIsMyJam methods accept simple positional arguments. The positional parameter passing style is optional; you can always use the named parameters in a HASH reference if you prefer. You may pass any number of required parameters as positional parameters. You *must* pass them in the order specified in the documentation for each method. Optional parameters must be passed as named parameters in a HASH reference. The HASH reference containing the named parameters must be the final parameter to the method call. Any required parameters not passed as positional parameters, must be included in the named parameter HASH reference. For example, the method "following" has one required parameter, "person". You can call "following" with a HASH ref argument: $timj->following({ person => 'jamoftheday' }); Or, you can use the convenient, positional parameter form: $timj->following('jamoftheday'); The "following" method also has an optional parameter: "order". You must use the HASH ref form: $timj->following({ person => 'jamoftheday', order => 'name' }); You may use the convenient positional form for the required "person" parameter with the optional parameters specified in the named parameter HASH reference: $timj->following('jamoftheday', { order => 'name' }); Convenience form is provided for the required parameters of all API methods. So, these two calls are equivalent: $timj->search_jams({ by => 'artist', q => 'Stone Roses' }); $timj->search_jams('artist', 'Stone Roses'); This scheme is ripped directly from Net::Twitter. Paging Some methods return partial results a page at a time, currently 60 items per page. For these, there is an optional "page" parameter. The first page is returned by passing "page => 1", the second page by passing "page => 2", etc. If no "page" parameter is passed, the first page is returned. Each paged response contains a "list" HASH ref with a "hasMore" key. On the last page, "hasMore" will be "false". Here's an example that demonstrates how to obtain all of a user's previous jams in a loop: my @jams; for (my $page = 1;; ++$page) { my $r = $timj->jams({person => 'jamoftheday', page => $page}); push @jams, @{$r->{jams}}; last unless $r->{list}{hasMore}; } Asynchronus Callbacks The supported asynchronous mode requires an additional parameter "cb". This must be a CODE ref and works like so: $timj->verify({ cb => sub { ... } }); $timj->jams( 'jamoftheday', { cb => sub { ... } }); $timj->like({ id => '4zugtyg', cb => sub { ... } }); This is ripped directly from Net::xkcd. Authentication In order to perform actions on behalf of a user such as liking a jam or following people, a user first needs to give permission to your app. Once that's been done, you can make authenticated calls. This Is My Jam uses OAuth 1.0 for authentication. Before v1.0.0, WWW::ThisIsMyJam will support OAuth. Dependencies * Try::Tiny * HTTP::Tiny * JSON * Carp * URI * URI::QueryParam * Moo * Type::Tiny Optional Dependencies * AnyEvent * AnyEvent::HTTP See Also * Net::Twitter * Net::xkcd * This Is My Jam API Documentation Bug Reports If email is better for you, my address is mentioned below but I would rather have bugs sent through the issue tracker found at http://github.com/sanko/www-thisismyjam/issues. Author Sanko Robinson - http://sankorobinson.com/ CPAN ID: SANKO License and Legal Copyright (C) 2013 by Sanko Robinson This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0 . See the LICENSE file included with this distribution or notes on the Artistic License 2.0 for clarification. When separated from the distribution, all original POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License . See the clarification of the CCA-SA3.0 .