FAQ: Using the Flickr::API in Perl

This FAQ describes how to use the Flickr API to read data from Flickr using Perl.

Step 1: Installing the API

• Download the API from cpan.
• Install the perl module using the manual
• Test the api using a simple script.

Step 2: Getting an API key from flickr

With just the API key, you have access to all the data on Flickr you usually see if you’re not logged in. For a lot a nice tricks you need to be authenticated. The below step describe how to authorize the api the use your own permissions. Be careful if you write a web application. All the stuff you do that needs the token is done with your user-id on Flickr. If you want things done with other users permissions check this page.

• Apply for a Flickr api here. You will receive a key and a secret. Write these down, because you’ll need these to if you want the full authorization token.
• The key will be visible here. Edit the details of the key and set the application type to ‘mobile application’. This will give you the Authentication URL in light grey text below the mobile permissions.
• Link the API key to a Flickr account. You can do this by pasting the Authentication URL in a browser. After pressing the allow button, you’ll get a mini-token. It will look something like ’999-999-999′. Write this down as we need this to get the full token. You can only use this mini-token once. If you fail at the step below you need to redo this step.
• Now get the full token by visiting this link. Enter the mini-token en press the ‘call method’ button. The full token will be visible in the output at the bottom of the screen.
• Test the API without the authentication by using this script. The script will generate a lot of output. Search for ‘error_message’. If there is no message, your API keys works.
• Test the authentication by using this script.

Step 3: Using the retrieved data

If you’ve used the above authentication script, you ended up with a variable called response. This variable is filled with an array with hashes.
• Find out what fields you want to use using the dumper module. See here for an example that shows all the info for the dutch group De Doka. You could capture the output in a text file for easy reference. Viewing that file with vi won’t be a problem, but your standard Linux TextEditor doesn’t like it since it contains characters that the standard character-set won’t understand.
• The main fields of the hash are:
  • success – Useless field
  • tree – Contains all the output from the request
  • _msg – Contains the textual returncode like ‘OK’
  • error_code – The errorcode. Hopefully a 0
  • _content – The content of _msg in a packed format
  • _protocol – Which http was used
  • error_message – If Error_code is not 0 this contains the error message
  • _headers – Contains the HTTP Headers
  • _rc – Useless field
  • _request – Contains info about the request you made
• Getting one of these fields can be done with “$response->{fieldname}”. Check the authentication script in step two for an example.
• Once you checked the error_code is zero, you can start getting the info from the array “tree”. There are more ways than one to do this. Feel free to devise one of your own.
• Getting a field like the name of the group could look like “$response->{tree}->{children}[1]->{children}[1]->{children}[0]->{content}”.
  For some reason most of the children[0] will be empty except on the lowest levels. The Dumper module will come in handy if you don’t get the field you expect.
  You can use the dumper on any level. For instance “print data:Dumper($response->{tree}->{children}[1]->{children}[1]“

Step 4: What calls can I do and how?

• For a complete list of all the call available check the list on the right on this page.
• If you click on any of the available API Methods you will see a page with all the info you need.
• If a method doesn’t need Authentication you don’t have to send the auth_token with your request. If you do include your token the request will be done with you Flickr user permissions.
• The Arguments will tell you what argument you need to provide and which ones are optional.
• The API Explorer lets you do the request from a web page. The debug feature is very helpful as it acts exactly the same as if making the call from perl.

Step 5: More info

• Flickr’s own documentation
• Blog of the Flickr Developers
• Flickr Hacks group
• Flickr API group
• Getting good? Jobs at Flickr