NAME

Flickr::Simple2 - A XML::Simple based Perl Flickr API.

SYNOPSIS

use Flickr::Simple2;
my $flickr =
  Flickr::Simple2->new({
      api_key => $cfg->param('Flickr.API_KEY'),
      api_secret => $cfg->param('Flickr.API_SHARED_SECRET'),
      auth_token => $cfg->param('Flickr.auth_token')
  });

DESCRIPTION

A XML::Simple based Perl Flickr API.

EXPORT

None by default.

METHODS

new

my $flickr = Flickr::Simple2->new({ api_key => $cfg->param('Flickr.API_KEY'), api_secret => $cfg->param('Flickr.API_SHARED_SECRET'), auth_token => $cfg->param('Flickr.auth_token') });

api_key is your Flickr API key given by Flickr api_secret is your Flickr API secret key given by Flickr.  It is used to sign certain Flickr API methods

auth_token is optional for public/safe access to photos but is required for nonsafe/private photos or any Flickr API method requiring authentication

request

An internal Flickr::Simple2 method used to communicate with the Flickr REST service. It uses XML::Simple for parsing of the XML data.

echo

$echo_ref = $flickr->echo({ wild => "and crazy guy"});

A simple method to send a message to Flickr and receive it back as a hash reference.

Requires: hash reference containing valid name/value pairs, api_key
Returns: hash reference containing the response from Flickr

raise_error

$self->raise_error($response, 'echo', 1);

An internal method that sets the simple error object hash reference.  The hash ref will be undefined if no error exists.

clear_error

$self->raise_error($response, 'echo', 1);

An internal method that clears the simple error object hash reference.  The hash ref will be undefined if no error exists.

flickr_sign

$self->flickr_sign({ method => 'flickr.auth.getFrob'});

An internal method to sign the Flickr API method call with your Flickr API secret key.

Requires: arguments to sign, flickr_api and flickr_api_secret
Returns: String containing the signed arguments

get_auth_frob

my $frob = $flickr->get_auth_frob();

A method to retrieve a Flickr frob, used for authentication.

Requires: api_key and api_secret
Returns: String containing the frob

get_auth_url

my $auth_url = $flickr->get_auth_url($frob, 'read');

A method to retrieve the url (webpage) for a Flickr user to authorize your application to use their account.

Requires: frob, permissions (read/write), api_key and api_secret
Returns: String containing the URL

get_auth_token

my $auth_token = $flickr->get_auth_token($frob);

A method to retrieve a Flickr authorization token.  Called after a user authorizes your application with the url returned from get_auth_url().

Requires: frob, api_key and api_secret
Returns: String containing the authorization token

check_auth_token

my $auth = $flickr->check_auth_token()

A method to validate a Flickr auth_token.

Requires: auth_token, api_key and api_secret
Returns: true (1) if auth_token is valid else undef

get_user_byEmail

my $user_nsid = $flickr->get_user_byEmail('jason_froebe@yahoo.com');

Retrieves the NSID of a Flickr user when given an email address

Requires: email address, api_key
Returns: String containing the NSID of the user

get_user_byUsername

my $user_nsid = $flickr->get_user_byUserName('jason_froebe');

Retrieves the NSID of a Flickr user when given a Flickr username

Requires: Flickr username, api_key
Returns: String containing the NSID of the user

get_user_byURL

my $user_nsid = $flickr->get_user_byURL('http://www.flickr.com/photos/jfroebe/3214186886/');

Retrieves the NSID of a Flickr user when given any URL (from Flickr website) associated with the user

Requires:  URL, api_key
Returns: String containing the NSID of the user

get_user_info

my $user_info = $flickr->get_user_info($user_nsid)

Retrieves extensive information regarding a Flickr user

Requires: NSID, api_key
Returns: Hash reference containing information about the user

get_license_info

Retrieves the types of licenses used at Flickr

Requires: api_key
Returns: Hash reference containing the license information

get_photo_exif

$self->get_photo_exif($photo_id, $photo_secret);

Retrieve the EXIF tags about a particular photo.  Primarily used by get_photo_detail but can be used separately

Requires: photo id, photo secret and api_key
Returns: Hash reference containing the EXIF tags

get_photo_detail

my $photo_detail = $flickr->get_photo_detail($photo_id, $public_photos->{photo}->{$photo_id}->{secret});

Retrieves extensive information regarding a particular photo.

Requires: photo id, photo secret, api_key
Optional: api_secret for none safe/public photos
Returns: Hash reference containing photo information

get_photos_page

my $photos_iterator = $self->get_photos_page($user, $params_ref);

Retrieves a "page" of photos from Flickr. Flickr groups photos in pages similar to their website.  

Returns: a hash reference for the current page of photos

get_public_photos

my $public_photos = $flickr->get_public_photos($user->{nsid}, { per_page => 3 });

Retrieves a list of a Flickr user's public photos (simple info) 

Requires: NSID, hash reference containing the number of photos (per page) to retrieve at a time
Optional: Within the hash reference:  safe_search, extras and page of photos to return

From Flickr API:
   safe_search (Optional)
       Safe search setting:
   
           * 1 for safe.
           * 2 for moderate.
           * 3 for restricted.
   
       (Please note: Un-authed calls can only see Safe content.)
   extras (Optional)
       A comma-delimited list of extra information to fetch for each returned record. Currently supported fields are: license, date_upload, date_taken, owner_name, icon_server, original_format, last_update, geo, tags, machine_tags, o_dims, views, media.
   per_page (Optional)
       Number of photos to return per page. If this argument is omitted, it defaults to 100. The maximum allowed value is 500.
   page (Optional)
       The page of results to return. If this argument is omitted, it defaults to 1.

Returns: Hash reference containing photos and simple photo details (photo secret for example)

build_photo_urls

my $photo_urls_ref = $self->build_photo_urls($photo_id, $response->{photos}->{photo}->{$photo_id} )

From Flickr API:
   http://farm{farm-id}.static.flickr.com/{server-id}/{id}_{secret}.jpg
   http://farm{farm-id}.static.flickr.com/{server-id}/{id}_{secret}_[mstb].jpg
   http://farm{farm-id}.static.flickr.com/{server-id}/{id}_{o-secret}_o.(jpg|gif|png)
       s	small square 75x75
       t	thumbnail, 100 on longest side
       m	small, 240 on longest side
       -	medium, 500 on longest side
       b	large, 1024 on longest side (only exists for very large original images)
       o	original image, either a jpg, gif or png, depending on source format

An internal method that builds the various size photo URLs for a particular photo.  Called primarily from get_public_photos.  Does not guarantee that the photo URLs are valid.

Requires: photo id, reference containing details of the photo, api_key
Returns: Hash reference containing the photo URLs

get_photo_sizes

Retrieves photo size information regarding a particular photo.

Requires: photo id, api_key
Returns: Hash reference containing URLs and other information regarding the sizes of the photo

get_photo_sizes

Retrieves a list of photosets & pools a particular photo belongs to.

Requires: photo id, api_key
Returns: Hash reference regarding the contexts of the photo

get_photo_tags

$self->get_photo_tags($tags_ref);

Sanitizes the tags structure that is part of the flickr.photos.getInfo response.  Used by get_photo_detail subroutine.

Requires tags structure returned by flickr.photos.getInfo 
Returns a hash ref with tag_name => "tagged by NSID" structure.

get_photoset_list

Retrieves a list of photosets for a Flickr user

Requires: user_id, api_key
Returns: Hash reference containing a list and limited info of photosets for a user.

get_photoset_photos

my $photoset_photos = $flickr->get_photoset_photos($user, { photoset_id => $photoset_id, per_page => 3 });

Retrieves a list of a Flickr user's photoset photos (simple info) 

Requires: NSID, hash reference containing the number of photos (per page) to retrieve at a time
Optional: Within the hash reference:  safe_search, extras and page of photos to return

From Flickr API:
   safe_search (Optional)
       Safe search setting:
   
           * 1 for safe.
           * 2 for moderate.
           * 3 for restricted.
   
       (Please note: Un-authed calls can only see Safe content.)
   extras (Optional)
       A comma-delimited list of extra information to fetch for each returned record. Currently supported fields are: license, date_upload, date_taken, owner_name, icon_server, original_format, last_update, geo, tags, machine_tags, o_dims, views, media.
   per_page (Optional)
       Number of photos to return per page. If this argument is omitted, it defaults to 100. The maximum allowed value is 500.
   page (Optional)
       The page of results to return. If this argument is omitted, it defaults to 1.

Returns: Hash reference containing photos and simple photo details (photo secret for example)

get_photoset_info

Retrieves information regarding a particular photo set

Requires: photoset_id, api_key
Returns: Hash reference containing information regarding a photo set.

get_your_photos_not_in_set

my $photos = $flickr->get_your_photos_not_in_set({ per_page => 3 });

Retrieves a list of YOUR photos not currently in a photoset (simple info) 

Requires: 
Optional: Within the hash reference:  safe_search, extras and page of photos to return

From Flickr API:
   safe_search (Optional)
       Safe search setting:
   
           * 1 for safe.
           * 2 for moderate.
           * 3 for restricted.
   
       (Please note: Un-authed calls can only see Safe content.)
   extras (Optional)
       A comma-delimited list of extra information to fetch for each returned record. Currently supported fields are: license, date_upload, date_taken, owner_name, icon_server, original_format, last_update, geo, tags, machine_tags, o_dims, views, media.
   per_page (Optional)
       Number of photos to return per page. If this argument is omitted, it defaults to 100. The maximum allowed value is 500.
   page (Optional)
       The page of results to return. If this argument is omitted, it defaults to 1.

Returns: Hash reference containing photos and simple photo details (photo secret for example)

AUTHOR

Jason L. Froebe, <jason@froebe.net>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.08.0 or, at your option, any later version of Perl 5 you may have available.

To install Flickr::Simple2, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Flickr::Simple2

CPAN shell

perl -MCPAN -e shell
install Flickr::Simple2

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

EXPORT

METHODS

new

request

echo

raise_error

clear_error

flickr_sign

get_auth_frob

get_auth_url

get_auth_token

check_auth_token

get_user_byEmail

get_user_byUsername

get_user_byURL

get_user_info

get_license_info

get_photo_exif

get_photo_detail

get_photos_page

get_public_photos

build_photo_urls

get_photo_sizes

get_photo_sizes

get_photo_tags

get_photoset_list

get_photoset_photos

get_photoset_info

get_your_photos_not_in_set

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions