WWW::Lovefilm::API - Interface for LOVEFiLM's API
Version 0.13
This module is to provide your perl applications with easy access to the LOVEFiLM's API (http://developer.lovefilm.com/). The Lovefilm API allows access to movie and user information, including queues, rating, rental history, and more.
use WWW::Lovefilm::API; use XML::Simple; use Data::Dumper; use URI::Escape; use JSON; my %auth = Your::Custom::getAuthFromCache(); my $lovefilm = WWW::Lovefilm::API->new({ consumer_key => $auth{consumer_key}, consumer_secret => $auth{consumer_secret}, access_token => $auth{access_token}, access_secret => $auth{access_secret}, user_id => $auth{user_id}, content_filter => sub { decode_json(shift) }, # optional }); if( ! $auth{user_id} ){ my %data = $lovefilm->RequestToken(); my $token = $data{token}; my $encoded = uri_escape('?myuser=123'); # params will be sent back to us my $this_url = $q->url(); my $url = $data{login_url} . '?oauth_token=' . $data{token}. ";oauth_callback=$this_url" . $encoded; # -- REDIRECT USER TO $url HERE -- my $token_secret = $q->param('token'); my %more_data = $lovefilm->RequestAccessToken( oauth_token => $data{token}, # got from RequestToken() token_secret => $token_secret, ); # %more_data till now hold access_token and access_secret } $lovefilm->REST->Users; $lovefilm->Get() or die $lovefilm->content_error; print Dumper $lovefilm->content; # Basic info on this user $lovefilm->REST->Users->at_home(); # What discs do they have at home $lovefilm->Get() or die $lovefilm->content_error; print Dumper $lovefilm->content; $lovefilm->REST->Catalog->Title; $lovefilm->Get( term => 'batman', start_index => 1, # 1 based index items_per_page => 20, ); my $data = $lovefilm->content;
And for resources that do not require a lovefilm account:
use WWW::Lovefilm::API; use XML::Simple; my $lovefilm = WWW::Lovefilm::API->new({ consumer_key consumer_secret content_filter => sub { XMLin(@_) }, }); $lovefilm->REST->Catalog->Title; $lovefilm->Get( term => 'zzyzx' ); printf "%d Results.\n", $lovefilm->content->{total_results}; printf "Title: %s\n", $_->{title}->{clean} for values %{ $lovefilm->content->{catalog_title} };
The first step to using this module is to register at http://developer.lovefilm.com -- you will need to register your application, for which you'll receive a consumer_key and consumer_secret keypair.
Any applications written with the Lovefilm API must adhere to the Terms of Use (http://developer.lovefilm.com/docs/additional_information/Terms_of_Use) and Branding Requirements (http://developer.lovefilm.com/docs/Additional_Information/Brand_Guidelines).
This module provides access to the REST API via perl syntactical sugar. For example, to find a user's queue, the REST url is of the form users/userID/queues :
http://openapi.lovefilm.com/users/T1tareQFowlmc8aiTEXBcQ5aed9h_Z8zdmSX1SnrKoOCA-/queues/
Using this module, the syntax would be (note that the Post or Delete methods can be used instead of Get, depending upon the API action being taken):
$lovefilm->REST->Users->Queues; $lovefilm->Get(%$params) or die $lovefilm->content_error; print $lovefilm->content;
Other examples include:
$lovefilm->REST->Users; $lovefilm->REST->Users->At_Home; $lovefilm->REST->users->at_home; # Case independant $lovefilm->REST->Catalog->Title('78324'); $lovefilm->REST->Users->rented;
Please note:
All of the possibilities (and parameter details) are outlined here: http://developer.lovefilm.com/docs/REST_API_Reference
There is a helper method "rest2sugar" included that will provide the proper syntax given a url. This is handy for translating the example urls in the REST API Reference.
The following describe the authentication that's happening under the hood and were used heavily in writing this module:
http://sites.google.com/site/oauthgoog/2leggedoauth/2opensocialrestapi
Net::OAuth
The examples/ directory in the distribution has several examples to use as starting points.
There is a vars.inc file in the directory -- most of these example read that for customer key/secret, etc, so fill that file out first to enter your specific values.
Examples include:
Takes a lovefilm account login/password and (for a customer key) obtains an access token, secret, and user_id.
Gets a user's lovefilm profile and prints the name.
Takes a search string and returns the results from a catalog search.
$ perl search.pl firefly 4 results: Firefly Dreams (2009-05-11) Firefly - The Complete Series (2004-04-19) Grave Of The Fireflies (2004-08-23) Fireflies in the Garden (2009-09-28)
Retrieves the entire Lovefilm catalog and saves it to catalog.xml in the current directory -- uses LWP handlers as an example of modifying the "ua" attribute.
Converts the xmlfile fetched by catalog.pl to a SQLite database. Also contains an example DBIx::Class setup for working with the generated database.
A simple CGI script that shows the end to end process in a browser of a user being redirected to LOVEFiLM, granting the script access, then being redirected back and showing what films the user has at home.
Also see the "TEST SUITE" source code for more examples.
This is the constructor. Takes a hashref of "ATTRIBUTES". Inherited from Class::Accessor.
Most important options to pass are the "consumer_key" and "consumer_secret".
This is used to change the resource that is being accessed. Some examples:
# The user-friendly way: $lovefilm->REST->Users->Feeds; # Including numeric parts: $lovefilm->REST->Catalog->Title('60021896'); # Load a pre-formed url (e.g. a title_ref from a previous query) $lovefilm->REST('http://openapi.lovefilm.com/users/T1tareQFowlmc8aiTEXBcQ5aed9h_Z8zdmSX1SnrKoOCA-/queues/disc?feed_token=T1u.tZSbY9311F5W0C5eVQXaJ49.KBapZdwjuCiUBzhoJ_.lTGnmES6JfOZbrxsFzf&oauth_consumer_key=v9s778n692e9qvd83wfj9t8c&');
This is used to login as a lovefilm user in order to get an access token.
my ($access_token, $access_secret, $user_id) = $lovefilm->RequestAccess( $user, $pass );
Makes a call to LOVEFiLM to get a token. It returns a hash with the following information required when you redirect the user to the LOVEFiLM website
This method is to be called after the user has been redirected back to your site after granting your app access.
It would be nice is the user_id was returned with the access token, but its not. This method makes an additional call for you to get it as it's rather important.
User agent to use under the hood. Defaults to LWP::UserAgent->new(). Can be altered anytime, e.g.
$lovefilm->ua->timeout(500);
The content returned by the REST calls is POX (plain old XML). Setting this attribute to a code ref will cause the content to be "piped" through it.
use XML::Simple; $lovefilm->content_filter( sub { XMLin(@_) } ); # Parse the XML into a perl data structure
If this is set to a scalar, it will be treated as a filename to store the result to, instead of it going to memory. This is especially useful for retrieving the (large) full catalog -- see "catalog.pl".
$lovefilm->content_filter('catalog.xml'); $lovefilm->REST->Catalog->Titles->Index; $lovefilm->Get(); # print `ls -lart catalog.xml`
Read-Only. This returns the content from the REST calls. Natively, this is a scalar of POX (plain old XML). If a "content_filter" is set, the "original_content" is filtered through that, and the result is returned as the value of the content attribute (and is cached in the "_filtered_content" attribute.
Read-Only. This will return a scalar which is simply a dereference of "content_ref".
Scalar reference to the original content.
Read-Only. If an error occurs, this will hold the error message/information.
Read-Only.
Takes scalar reference.
Used to cache the return value of filtering the content through the content_filter.
Most of the test suite in the t/ directory requires a customer key/secret and access token/secret. You can supply these via enviromental variables:
# *nix export WWW_LOVEFILM_API__CONSUMER_KEY="qweqweqwew" export WWW_LOVEFILM_API__CONSUMER_SECRET="asdasd" export WWW_LOVEFILM_API__LOGIN_USER="you@example.com" export WWW_LOVEFILM_API__LOGIN_PASS="qpoiuy" export WWW_LOVEFILM_API__ACCESS_TOKEN="trreqweyueretrewere" export WWW_LOVEFILM_API__ACCESS_SECRET="mnmbmbdsf" REM DOS SET WWW_LOVEFILM_API__CONSUMER_KEY=qweqweqwew SET WWW_LOVEFILM_API__CONSUMER_SECRET=asdasd SET WWW_LOVEFILM_API__LOGIN_USER=you@example.com SET WWW_LOVEFILM_API__LOGIN_PASS=qpoiuy SET WWW_LOVEFILM_API__ACCESS_TOKEN=trreqweyueretrewere SET WWW_LOVEFILM_API__ACCESS_SECRET=mnmbmbdsf
And then, from the extracted distribution directory, either run the whole test suite:
perl Makefile.PL make test
or just execute specific tests:
prove -v -Ilib t/api.t prove -v -Ilib t/access_token.t
Are you using WWW::Lovefilm::API in your application? Please email me with your application name and url or email, and i will be happy to list it here.
David Westbrook (CPAN: davidrw), <dwestbrook at gmail.com> Paul Mooney (CPAN: pmooney), <paul.cpan at phymatics.co.uk>
<dwestbrook at gmail.com>
<paul.cpan at phymatics.co.uk>
Please report any bugs or feature requests to bug-www-lovefilm-api at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Lovefilm-API. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-www-lovefilm-api at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc WWW::Lovefilm::API
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Lovefilm-API
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/WWW-Lovefilm-API
CPAN Ratings
http://cpanratings.perl.org/d/WWW-Lovefilm-API
Search CPAN
http://search.cpan.org/dist/WWW-Lovefilm-API
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
This package is a derivative of WWW::Netflix::API, which was created by David Westbrook.
To install WWW::Lovefilm::API, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::Lovefilm::API
CPAN shell
perl -MCPAN -e shell install WWW::Lovefilm::API
For more information on module installation, please visit the detailed CPAN module installation guide.