.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Flickr::API 3pm"
.TH Flickr::API 3pm 2024-03-02 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Flickr::API \- Perl interface to the Flickr API
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.SS "Using OAuth to call a \fBmethod\fP not requiring authentication"
.IX Subsection "Using OAuth to call a method not requiring authentication"
.Vb 1
\&  use Flickr::API;
\&
\&  my $api = Flickr::API\->new({
\&        \*(Aqconsumer_key\*(Aq    => \*(Aqyour_api_key\*(Aq,
\&        \*(Aqconsumer_secret\*(Aq => \*(Aqyour_app_secret\*(Aq,
\&    });
\&
\&  my $response = $api\->execute_method(\*(Aqflickr.test.echo\*(Aq, {
\&        \*(Aqfoo\*(Aq => \*(Aqbar\*(Aq,
\&        \*(Aqbaz\*(Aq => \*(Aqquux\*(Aq,
\&    });
\&
\&
\&  my $config_file = $HOME/saved\-flickr.st;
\&  $api\->export_storable_config($config_file);
.Ve
.SS "Non-OAuth method calling \fBmethod\fP not requiring authentication"
.IX Subsection "Non-OAuth method calling method not requiring authentication"
.Vb 1
\&  use Flickr::API;
\&
\&  # key deprecated in favor of api_key
\&  # secret deprecated in favor of api_secret
\&  #
\&  my $api = Flickr::API\->new({
\&        \*(Aqapi_key\*(Aq    => \*(Aqyour_api_key\*(Aq,
\&        \*(Aqapi_secret\*(Aq => \*(Aqyour_app_secret\*(Aq,
\&    });
\&
\&  my $response = $api\->execute_method(\*(Aqflickr.test.echo\*(Aq, {
\&        \*(Aqfoo\*(Aq => \*(Aqbar\*(Aq,
\&        \*(Aqbaz\*(Aq => \*(Aqquux\*(Aq,
\&    });
.Ve
.SS "Alternatively, Using OAuth for non-authenticated \fBrequest\fP"
.IX Subsection "Alternatively, Using OAuth for non-authenticated request"
.Vb 2
\&  use Flickr::API;
\&  use Flickr::API::Request;
\&
\&  my $api = Flickr::API\->new({\*(Aqconsumer_key\*(Aq => \*(Aqyour_api_key\*(Aq,\*(Aqconsumer_secret\*(Aq => \*(Aqyour_app_secret\*(Aq});
\&
\&  my $request = Flickr::API::Request\->new({
\&        \*(Aqmethod\*(Aq => \*(Aqflickr.test.echo\*(Aq,
\&        \*(Aqargs\*(Aq => {},
\&    });
\&
\&  my $response = $api\->execute_request($request);
.Ve
.SS "Authenticate an OAuth API Object starting with saved configuration"
.IX Subsection "Authenticate an OAuth API Object starting with saved configuration"
.Vb 2
\&  use Flickr::API;
\&  use Term::ReadLine;
\&
\&  my $config_file = "$ENV{HOME}/saved\-flickr.st";
\&  my $term   = Term::ReadLine\->new(\*(AqTesting Flickr::API\*(Aq);
\&  $term\->ornaments(0);
\&
\&  my $api = Flickr::API\->import_storable_config($config_file);
\&
\&  my $rt_rc =  $api\->oauth_request_token( { \*(Aqcallback\*(Aq => \*(Aqhttps://127.0.0.1/\*(Aq } );
\&
\&  my %request_token;
\&  if ( $rt_rc eq \*(Aqok\*(Aq ) {
\&
\&      my $uri = $api\->oauth_authorize_uri({ \*(Aqperms\*(Aq => \*(Aqread\*(Aq });
\&
\&      my $prompt = "\en\en$uri\en\en" .
\&          "Copy the above url to a browser, and authenticate with Flickr\en" .
\&          "Press [ENTER] once you get the redirect: ";
\&      my $input = $term\->readline($prompt);
\&
\&      $prompt = "\en\enCopy the redirect URL from your browser and enter it\enHere: ";
\&      $input = $term\->readline($prompt);
\&
\&      chomp($input);
\&
\&      my ($callback_returned,$token_received) = split(/\e?/,$input);
\&      my (@parms) = split(/\e&/,$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(\e%request_token);
\&  if ( $ac_rc eq \*(Aqok\*(Aq ) {
\&
\&      $api\->export_storable_config($config_file);
\&
\&      my $response = $api\->execute_method(\*(Aqflickr.auth.oauth.checkToken\*(Aq);
\&      my $hash_ref = $response\->as_hash();
\&
\&      $response    = $api\->execute_method(\*(Aqflickr.prefs.getPrivacy\*(Aq);
\&      my $rsp_node = $response\->as_tree();
\&  }
.Ve
.SS "The OAuth authorization uri will look something like:"
.IX Subsection "The OAuth authorization uri will look something like:"
.Vb 1
\&  https://api.flickr.com/services/oauth/authorize?oauth_token=12345678901234567\-890abcdefedcba98&perms=read
.Ve
.SS "The callback is called with a token and verifier such as:"
.IX Subsection "The callback is called with a token and verifier such as:"
.Vb 1
\&  https://127.0.0.1/?oauth_token=12345678901234567\-890abcdefedcba98&oauth_verifier=cafe12345678feed
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
An interface for using the Flickr API.
.PP
\&\f(CW\*(C`Flickr::API\*(C'\fR is a subclass of LWP::UserAgent, so all of the various
proxy, request limits, caching, etc are available. \f(CW\*(C`Flickr::API\*(C'\fR can
instantiate using either the Flickr Authentication (deprecated) or the
OAuth Authentication. OAuth is handled using Net::OAuth.
.SH SUBROUTINES/METHODS
.IX Header "SUBROUTINES/METHODS"
.ie n .IP """new({ opt => \*(Aqvalue\*(Aq, ... })""" 4
.el .IP "\f(CWnew({ opt => \*(Aqvalue\*(Aq, ... })\fR" 4
.IX Item "new({ opt => value, ... })"
Returns as new Flickr::API object. The options are as follows:
.RS 4
.ie n .IP "either ""api_key"" for the Flickr auth or ""consumer_key"" for OAuth" 4
.el .IP "either \f(CWapi_key\fR for the Flickr auth or \f(CWconsumer_key\fR for OAuth" 4
.IX Item "either api_key for the Flickr auth or consumer_key for OAuth"
Your API key (one or the other form is required)
.ie n .IP "either ""api_secret"" for the Flickr auth or ""consumer_secret"" for OAuth" 4
.el .IP "either \f(CWapi_secret\fR for the Flickr auth or \f(CWconsumer_secret\fR for OAuth" 4
.IX Item "either api_secret for the Flickr auth or consumer_secret for OAuth"
Your API key's secret (the one matching the api_key/consumer_key is required)
.ie n .IP """rest_uri"" & ""auth_uri""" 4
.el .IP "\f(CWrest_uri\fR & \f(CWauth_uri\fR" 4
.IX Item "rest_uri & auth_uri"
Override the URIs used for contacting the API.
.ie n .IP """lwpobj""" 4
.el .IP \f(CWlwpobj\fR 4
.IX Item "lwpobj"
Base the \f(CW\*(C`Flickr::API\*(C'\fR on this object, instead of creating a new instance of LWP::UserAgent.
This is useful for using the features of e.g. LWP::UserAgent::Cached.
.ie n .IP """unicode""" 4
.el .IP \f(CWunicode\fR 4
.IX Item "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.
.ie n .IP """nonce"", ""timestamp"", ""request_method"", ""signature_method"", ""request_url""" 4
.el .IP "\f(CWnonce\fR, \f(CWtimestamp\fR, \f(CWrequest_method\fR, \f(CWsignature_method\fR, \f(CWrequest_url\fR" 4
.IX Item "nonce, timestamp, request_method, signature_method, request_url"
These values are used by Net::OAuth to assemble and sign OAuth \fIconsumer\fR request
Flickr API calls. The defaults are usually fine.
.ie n .IP """callback""" 4
.el .IP \f(CWcallback\fR 4
.IX Item "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/
.ie n .IP """token"" and ""token_secret""" 4
.el .IP "\f(CWtoken\fR and \f(CWtoken_secret\fR" 4
.IX Item "token and token_secret"
These values are used by Net::OAuth to assemble and sign OAuth \fIprotected resource\fR request
Flickr API calls.
.RE
.RS 4
.RE
.ie n .IP """execute_method($method, $args)""" 4
.el .IP "\f(CWexecute_method($method, $args)\fR" 4
.IX Item "execute_method($method, $args)"
Constructs a Flickr::API::Request object and executes it, returning a Flickr::API::Response object.
.ie n .IP execute_request($request) 4
.el .IP \f(CWexecute_request($request)\fR 4
.IX Item "execute_request($request)"
Executes a Flickr::API::Request object, returning a Flickr::API::Response object. Calls are signed
if a secret was specified when creating the Flickr::API object.
.ie n .IP """request_auth_url($perms,$frob)""" 4
.el .IP \f(CWrequest_auth_url($perms,$frob)\fR 4
.IX Item "request_auth_url($perms,$frob)"
Returns a URI object representing the URL that an application must redirect a user to for approving
an authentication token.
.Sp
\&\f(CW$perms\fR must be \fBread\fR, \fBwrite\fR, or \fBdelete\fR.
.Sp
For web-based applications \fR\f(CI$frob\fR\fI\fR is an optional parameter.
.Sp
Returns undef if a secret was not specified when creating the \f(CW\*(C`Flickr::API\*(C'\fR object.
.ie n .IP """export_config([$type,$params])""" 4
.el .IP \f(CWexport_config([$type,$params])\fR 4
.IX Item "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.
.RS 4
.ie n .IP "oauth message type: one of ""Consumer"", ""Protected Resource"", ""Request Token"", ""Authorize User"" or ""Access Token""" 4
.el .IP "oauth message type: one of \f(CWConsumer\fR, \f(CWProtected Resource\fR, \f(CWRequest Token\fR, \f(CWAuthorize User\fR or \f(CWAccess Token\fR" 4
.IX Item "oauth message type: one of Consumer, Protected Resource, Request Token, Authorize User or Access Token"
This is one of the the message type that Net::OAuth handles. Message type is optional.
.ie n .IP "oauth parameter set: ""message"" or ""API"" or undef." 4
.el .IP "oauth parameter set: \f(CWmessage\fR or \f(CWAPI\fR or undef." 4
.IX Item "oauth parameter set: message or API or undef."
Net::OAuth will return message params, api params or all params depending on what is requested.
All params is the default.
.RE
.RS 4
.Sp
If the Flickr::API object identifies as Flickr original authentication, return a
hashref
.Sp
.Vb 6
\&  $VAR1 = {
\&            \*(Aqfrob\*(Aq => \*(Aq12332112332112300\-feedabcde123456c\-1234567\*(Aq,
\&            \*(Aqapi_key\*(Aq => \*(Aqcafefeedbeef13579246801234567890\*(Aq,
\&            \*(Aqapi_secret\*(Aq => \*(Aqbeef321432154321\*(Aq,
\&            \*(Aqtoken\*(Aq => \*(Aq97531086421234567\-cafe123456789abc\*(Aq
\&          };
.Ve
.Sp
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.
.Sp
If the API object identifies as OAuth authentication, and \f(CW\*(C`message type\*(C'\fR is
specified, then export_config will return a hash of the OAuth parameters for
the specified Net::OAuth message type. Further, if parameter is specified,
then export_config returns either either the set of \fBmessage\fR parameters or
\&\fBapi\fR parameters for the message type. If parameter is not specified then both
parameter type are returned. For example:
.Sp
.Vb 1
\&  my %config = $api\->export_config(\*(Aqprotected resource\*(Aq);
.Ve
.Sp
or
.Sp
.Vb 1
\&  my %config = $api\->export_config(\*(Aqprotected resource\*(Aq,\*(Aqmessage\*(Aq);
.Ve
.Sp
When export_config is called without arguments, then it returns the OAuth
portion of the Flickr::API object. If present the Net::OAuth \fIRequest Token\fR
and \fIAccess Token\fR objects are also included.
.Sp
.Vb 10
\&  VAR1 = {
\&            \*(Aqaccess_token\*(Aq => bless( {
\&                                       \*(Aqextra_params\*(Aq => {
\&                                                           \*(Aqfullname\*(Aq => \*(AqLouis\*(Aq,
\&                                                           \*(Aquser_nsid\*(Aq => \*(Aq12345678@N00\*(Aq,
\&                                                           \*(Aqusername\*(Aq => \*(Aqmeanameicallmyself\*(Aq
\&                                                         },
\&                                       \*(Aqfrom_hash\*(Aq => 1,
\&                                       \*(Aqtoken\*(Aq => \*(Aq12345678901234567\-cafe123098765432\*(Aq,
\&                                       \*(Aqtoken_secret\*(Aq => \*(Aqeebeef000fedbca1\*(Aq
\&                                     }, \*(AqNet::OAuth::AccessTokenResponse\*(Aq ),
\&            \*(Aqcallback\*(Aq => \*(Aqhttps://127.0.0.1\*(Aq,
\&            \*(Aqconsumer_key\*(Aq => \*(Aqcafefeedbeef13579246801234567890\*(Aq,
\&            \*(Aqconsumer_secret\*(Aq => \*(Aqfedcba9876543210\*(Aq,
\&            \*(Aqnonce\*(Aq => \*(Aq917fa882fa7babd5a1b7702e7d19502a\*(Aq,
\&            \*(Aqrequest_method\*(Aq => \*(AqGET\*(Aq,
\&            \*(Aqrequest_url\*(Aq => \*(Aqhttps://api.flickr.com/services/rest/\*(Aq,
\&            \*(Aqsignature_method\*(Aq => \*(AqHMAC\-SHA1\*(Aq,
\&            \*(Aqtimestamp\*(Aq => 1436129308,
\&            \*(Aqtoken\*(Aq => \*(Aq12345678901234567\-cafe123098765432\*(Aq,
\&            \*(Aqtoken_secret\*(Aq => \*(Aqeebeef000fedbca1\*(Aq,
\&            \*(Aqversion\*(Aq => \*(Aq1.0\*(Aq
\&          };
\&
\&  my %config = $api\->export_config();
.Ve
.RE
.PP
This method can be used to extract and save the API parameters for
future use.
.ie n .IP export_storable_config(filename) 4
.el .IP \f(CWexport_storable_config(filename)\fR 4
.IX Item "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.
.ie n .IP import_storable_config(filename) 4
.el .IP \f(CWimport_storable_config(filename)\fR 4
.IX Item "import_storable_config(filename)"
This method retrieves a storable config of a Flickr::API object
and revivifies the object.
.ie n .IP get_oauth_request_type() 4
.el .IP \f(CWget_oauth_request_type()\fR 4
.IX Item "get_oauth_request_type()"
Returns the oauth request type in the Flickr::API object. Some Flickr methods
will require a \f(CW\*(C`protected resource\*(C'\fR request type and others a simple \f(CW\*(C`consumer\*(C'\fR
request type.
.ie n .IP oauth_request_token(\e%args) 4
.el .IP \f(CWoauth_request_token(\e%args)\fR 4
.IX Item "oauth_request_token(%args)"
Assembles, signs, and makes the OAuth \fBRequest Token\fR call, and if successful
stores the Net::OAuth \fIRequest Token\fR in the Flickr::API object.
.Sp
The required parameters are:
.RS 4
.ie n .IP """consumer_key""" 4
.el .IP \f(CWconsumer_key\fR 4
.IX Item "consumer_key"
Your API Key
.ie n .IP """consumer_secret""" 4
.el .IP \f(CWconsumer_secret\fR 4
.IX Item "consumer_secret"
Your API Key's secret
.ie n .IP """request_method""" 4
.el .IP \f(CWrequest_method\fR 4
.IX Item "request_method"
The URI Method: GET or POST
.ie n .IP """request_url""" 4
.el .IP \f(CWrequest_url\fR 4
.IX Item "request_url"
Defaults to: <https://api.flickr.com/services/oauth/request_token>
.RE
.RS 4
.RE
.ie n .IP """flickr_access_token""" 4
.el .IP \f(CWflickr_access_token\fR 4
.IX Item "flickr_access_token"
The required parameters are:
.RS 4
.ie n .IP """key""" 4
.el .IP \f(CWkey\fR 4
.IX Item "key"
.RE
.RS 4
.RE
.PD 0
.ie n .IP oauth_access_token(\e%args) 4
.el .IP \f(CWoauth_access_token(\e%args)\fR 4
.IX Item "oauth_access_token(%args)"
.PD
Assembles, signs, and makes the OAuth \fBAccess Token\fR call, and if successful
stores the Net::OAuth \fIAccess Token\fR in the Flickr::API object.
.Sp
The required parameters are:
.RS 4
.ie n .IP """consumer_key""" 4
.el .IP \f(CWconsumer_key\fR 4
.IX Item "consumer_key"
Your API Key
.ie n .IP """consumer_secret""" 4
.el .IP \f(CWconsumer_secret\fR 4
.IX Item "consumer_secret"
Your API Key's secret
.ie n .IP """request_method""" 4
.el .IP \f(CWrequest_method\fR 4
.IX Item "request_method"
The URI Method: GET or POST
.ie n .IP """request_url""" 4
.el .IP \f(CWrequest_url\fR 4
.IX Item "request_url"
Defaults to: <https://api.flickr.com/services/oauth/access_token>
.ie n .IP """token_secret""" 4
.el .IP \f(CWtoken_secret\fR 4
.IX Item "token_secret"
The request token secret from the Net::OAuth \fIRequest Token\fR object
returned from the \fIoauth_request_token\fR call.
.RE
.RS 4
.RE
.ie n .IP oauth_authorize_uri(\e%args) 4
.el .IP \f(CWoauth_authorize_uri(\e%args)\fR 4
.IX Item "oauth_authorize_uri(%args)"
Returns a URI object representing the URL that an application must redirect a user to for approving
a request token.
.RS 4
.ie n .IP """perms""" 4
.el .IP \f(CWperms\fR 4
.IX Item "perms"
Permission the application is requesting, one of \fBread, write, or delete\fR, defaults to \fBread\fR.
.RE
.RS 4
.RE
.ie n .IP """is_oauth""" 4
.el .IP \f(CWis_oauth\fR 4
.IX Item "is_oauth"
Returns \fB1\fR if the Flickr::API object is OAuth flavored, \fB0\fR otherwise.
.SH AUTHOR
.IX Header "AUTHOR"
Cal Henderson, <cal@iamcal.com>
.PP
Auth API patches provided by Aaron Straup Cope
.PP
Subclassing patch from AHP
.PP
OAuth patches and additions Louis B. Moore <lbmoore@cpan.org>
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (C) 2004\-2013, Cal Henderson, <cal@iamcal.com>
.PP
OAuth patches and additions
Copyright (C) 2014\-2016 Louis B. Moore <lbmoore@cpan.org>
.PP
This program is released under the Artistic License 2.0 by The Perl Foundation.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Flickr::API::Request,
Flickr::API::Response,
Net::OAuth,
XML::Parser::Lite,
Flickr <http://www.flickr.com/>,
<http://www.flickr.com/services/api/>
<https://www.flickr.com/services/api/auth.oauth.html>
<https://github.com/iamcal/perl\-Flickr\-API>