NAME

Flickr::API - Perl interface to the Flickr API

SYNOPSIS

Using OAuth to call amethod not requiring authentication

use Flickr::API;my $api = Flickr::API->new({      'consumer_key'    => 'your_api_key',      'consumer_secret' => 'your_app_secret',  });my $response = $api->execute_method('flickr.test.echo', {      'foo' => 'bar',      'baz' => 'quux',  });my $config_file = $HOME/saved-flickr.st;$api->export_storable_config($config_file);

Non-OAuth method callingmethod not requiring authentication

use Flickr::API;# key deprecated in favor of api_key# secret deprecated in favor of api_secret#my $api = Flickr::API->new({      'api_key'    => 'your_api_key',      'api_secret' => 'your_app_secret',  });my $response = $api->execute_method('flickr.test.echo', {      'foo' => 'bar',      'baz' => 'quux',  });

Alternatively, Using OAuth for non-authenticatedrequest

use Flickr::API;use Flickr::API::Request;my $api = Flickr::API->new({'consumer_key' => 'your_api_key','consumer_secret' => 'your_app_secret'});my $request = Flickr::API::Request->new({      'method' => 'flickr.test.echo',      'args' => {},  });my $response = $api->execute_request($request);

Authenticate an OAuth API Object starting with saved configuration

use Flickr::API;use Term::ReadLine;my $config_file = "$ENV{HOME}/saved-flickr.st";my $term   = Term::ReadLine->new('Testing Flickr::API');$term->ornaments(0);my $api = Flickr::API->import_storable_config($config_file);my $rt_rc =  $api->oauth_request_token( { 'callback' => 'https://127.0.0.1/' } );my %request_token;if ( $rt_rc eq 'ok' ) {    my $uri = $api->oauth_authorize_uri({ 'perms' => 'read' });    my $prompt = "\n\n$uri\n\n" .        "Copy the above url to a browser, and authenticate with Flickr\n" .        "Press [ENTER] once you get the redirect: ";    my $input = $term->readline($prompt);    $prompt = "\n\nCopy the redirect URL from your browser and enter it\nHere: ";    $input = $term->readline($prompt);    chomp($input);    my ($callback_returned,$token_received) = split(/\?/,$input);    my (@parms) = split(/\&/,$token_received);    foreach my $pair (@parms) {        my ($key,$val) = split(/=/,$pair);        $key =~ s/oauth_//;        $request_token{$key}=$val;    }}my $ac_rc = $api->oauth_access_token(\%request_token);if ( $ac_rc eq 'ok' ) {    $api->export_storable_config($config_file);    my $response = $api->execute_method('flickr.auth.oauth.checkToken');    my $hash_ref = $response->as_hash();    $response    = $api->execute_method('flickr.prefs.getPrivacy');    my $rsp_node = $response->as_tree();}

The OAuth authorization uri will look something like:

https://api.flickr.com/services/oauth/authorize?oauth_token=12345678901234567-890abcdefedcba98&perms=read

The callback is called with a token and verifier such as:

https://127.0.0.1/?oauth_token=12345678901234567-890abcdefedcba98&oauth_verifier=cafe12345678feed

DESCRIPTION

An interface for using the Flickr API.

Flickr::API is a subclass ofLWP::UserAgent, so all of the various proxy, request limits, caching, etc are available.Flickr::API can instantiate using either the Flickr Authentication (deprecated) or the OAuth Authentication. OAuth is handled usingNet::OAuth.

SUBROUTINES/METHODS

new({ opt => 'value', ... })

Returns as newFlickr::API object. The options are as follows:

eitherapi_key for the Flickr auth orconsumer_key for OAuth

Your API key (one or the other form is required)

eitherapi_secret for the Flickr auth orconsumer_secret for OAuth

Your API key's secret (the one matching the api_key/consumer_key is required)

rest_uri &auth_uri

Override the URIs used for contacting the API.

lwpobj

Base theFlickr::API on this object, instead of creating a new instance ofLWP::UserAgent. This is useful for using the features of e.g.LWP::UserAgent::Cached.

unicode

This flag controls whether Flickr::API expects you to pass UTF-8 bytes (unicode=0, the default) or actual unicode strings (unicode=1) in the request.

nonce,timestamp,request_method,signature_method,request_url

These values are used byNet::OAuth to assemble and sign OAuthconsumer request Flickr API calls. The defaults are usually fine.

callback

The callback is used in oauth authentication. When Flickr authorizes you, it returns the access token and access token secret in a callback URL. This defaults to https://127.0.0.1/

token andtoken_secret

These values are used byNet::OAuth to assemble and sign OAuthprotected resource request Flickr API calls.

execute_method($method, $args)

Constructs aFlickr::API::Request object and executes it, returning aFlickr::API::Response object.

execute_request($request)

Executes aFlickr::API::Request object, returning aFlickr::API::Response object. Calls are signed if a secret was specified when creating theFlickr::API object.

request_auth_url($perms,$frob)

Returns aURI object representing the URL that an application must redirect a user to for approving an authentication token.

$perms must beread,write, ordelete.

For web-based applications$frob is an optional parameter.

Returns undef if a secret was not specified when creating theFlickr::API object.

export_config([$type,$params])

Returns a hash of all or part of the persistent parts of the Flickr::API object with additional behaviors for Flickr::API objects using OAuth.

oauth message type: one ofConsumer,Protected Resource,Request Token,Authorize User orAccess Token

This is one of the the message type thatNet::OAuth handles. Message type is optional.

oauth parameter set:message orAPI or undef.

Net::OAuth will return message params, api params or all params depending on what is requested. All params is the default.

If the Flickr::API object identifies as Flickr original authentication, return a hashref

$VAR1 = {          'frob' => '12332112332112300-feedabcde123456c-1234567',          'api_key' => 'cafefeedbeef13579246801234567890',          'api_secret' => 'beef321432154321',          'token' => '97531086421234567-cafe123456789abc'        };

or the subset thereof depending on what has been used by the API. If the older form of key/secret was used, the constructor will change these to the api_key/api_secret forms.

If the API object identifies as OAuth authentication, andmessage type is specified, then export_config will return a hash of the OAuth parameters for the specifiedNet::OAuth message type. Further, if parameter is specified, then export_config returns either either the set ofmessage parameters orapi parameters for the message type. If parameter is not specified then both parameter type are returned. For example:

my %config = $api->export_config('protected resource');

or

my %config = $api->export_config('protected resource','message');

When export_config is called without arguments, then it returns the OAuth portion of theFlickr::API object. If present theNet::OAuthRequest Token andAccess Token objects are also included.

VAR1 = {          'access_token' => bless( {                                     'extra_params' => {                                                         'fullname' => 'Louis',                                                         'user_nsid' => '12345678@N00',                                                         'username' => 'meanameicallmyself'                                                       },                                     'from_hash' => 1,                                     'token' => '12345678901234567-cafe123098765432',                                     'token_secret' => 'eebeef000fedbca1'                                   }, 'Net::OAuth::AccessTokenResponse' ),          'callback' => 'https://127.0.0.1',          'consumer_key' => 'cafefeedbeef13579246801234567890',          'consumer_secret' => 'fedcba9876543210',          'nonce' => '917fa882fa7babd5a1b7702e7d19502a',          'request_method' => 'GET',          'request_url' => 'https://api.flickr.com/services/rest/',          'signature_method' => 'HMAC-SHA1',          'timestamp' => 1436129308,          'token' => '12345678901234567-cafe123098765432',          'token_secret' => 'eebeef000fedbca1',          'version' => '1.0'        };my %config = $api->export_config();

This method can be used to extract and save the API parameters for future use.

export_storable_config(filename)

This method wraps export_config with a file open and storable store_fd to add some persistence to a Flickr::API object.

import_storable_config(filename)

This method retrieves a storable config of a Flickr::API object and revivifies the object.

get_oauth_request_type()

Returns the oauth request type in the Flickr::API object. Some Flickr methods will require aprotected resource request type and others a simpleconsumer request type.

oauth_request_token(\%args)

Assembles, signs, and makes the OAuthRequest Token call, and if sucessful stores theNet::OAuthRequest Token in theFlickr::API object.

The required parameters are:

consumer_key

Your API Key

consumer_secret

Your API Key's secret

request_method

The URI Method: GET or POST

request_url

Defaults to:https://api.flickr.com/services/oauth/request_token

flickr_access_token

The required parameters are:

key

oauth_access_token(\%args)

Assembles, signs, and makes the OAuthAccess Token call, and if sucessful stores theNet::OAuthAccess Token in theFlickr::API object.

The required parameters are:

consumer_key

Your API Key

consumer_secret

Your API Key's secret

request_method

The URI Method: GET or POST

request_url

Defaults to:https://api.flickr.com/services/oauth/access_token

token_secret

The request token secret from theNet::OAuthRequest Token object returned from theoauth_request_token call.

oauth_authorize_uri(\%args)

Returns aURI object representing the URL that an application must redirect a user to for approving a request token.

perms

Permission the application is requesting, one ofread, write, or delete, defaults toread.

is_oauth

Returns1 if theFlickr::API object is OAuth flavored,0 otherwise.

AUTHOR

Cal Henderson, <cal@iamcal.com>

Auth API patches provided by Aaron Straup Cope

Subclassing patch from AHP

OAuth patches and additions Louis B. Moore <lbmoore@cpan.org>

LICENSE AND COPYRIGHT

Copyright (C) 2004-2013, Cal Henderson, <cal@iamcal.com>

OAuth patches and additions Copyright (C) 2014-2016 Louis B. Moore <lbmoore@cpan.org>

This program is released under the Artistic License 2.0 by The Perl Foundation.

SEE ALSO

Flickr::API::Request,Flickr::API::Response,Net::OAuth,XML::Parser::Lite,Flickr,http://www.flickr.com/services/api/https://www.flickr.com/services/api/auth.oauth.htmlhttps://github.com/iamcal/perl-Flickr-API