API Reference

API Reference

Using flickr_api, you can access the Flickr API in two different ways.

Direct API methods calls

The first one directly calls the API methods with a syntax close to the one that you will find within Flickr's official API documentation.

The answers are XML strings or JSON strings and you will have to parse them yourself. This method is recommended for experimented users only. For other users please refer to the Object Oriented API.

Here is an example of method call:

>>> from flickr_api.api import flickr
>>> print flickr.reflection.getMethodInfo(method_name = "flickr.photos.getInfo")

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
<method name="flickr.photos.getInfo" needslogin="0" needssigning="0" requiredperms="0">
	<description>Get information about a photo. The calling user must have permission to view the photo.</description>
	<response>...</response>
	<explanation>...</explanation>
</method>
<arguments>
	<argument name="api_key" optional="0">Your API application key. &lt;a href=&quot;/services/api/misc.api_keys.html&quot;&gt;See here&lt;/a&gt; for more details.</argument>
        ...
</arguments>
<errors>
	<error code="1" message="Photo not found.">The photo id was either invalid or was for a photo not viewable by the calling user.</error>
	...
</errors>
</rsp>

Object-Oriented Interface Usage

Most operations can be undertaken using flickr_apis OO interface, and you will most likely use this.

Retrieving a user

To have direct access to user you have 3 methods:

1. by username

>>> user = flickr_api.Person.findByUserName(username)

2. by email

>>> user = flickr_api.Person.findByEmail(email)

3. If an authentication handlier is set, you can retrieve the authenticated user with :

>>> user = flickr_api.test.login()

Managing Photos

• Get photos from a user

>>> photos = user.getPhotos()       # if authenticated
>>> photos = user.getPublicPhotos() # otherwise

Some information about the response from the server, e.g. pagination information, is available in the info attribute of the photos list:

>>> print photos.info.pages # the number of available pages of results
>>> print photos.info.page  # the current page number
>>> print photos.info.total # total number of photos

• Download a photo

>>> p.save(filename, size_label = 'Medium 640') # downloading the photo file

• Upload a photo In the simplest case, you simply need to provide the path to the file and the title:

>>> flickr_api.upload(photo_file = "path_to_the_photo_file", title = "My title")

Note: If you want to set the photo to private, make sure you set is_public="0" (note the number string!)

You can also directly provide a file-like object using the photo_file_data argument. For instance you can upload an image from a URL using:

>>> import urllib
>>> URL = "the url to the image"
>>> filehandler = urllib.urlopen(URL)
>>> flickr_api.upload(photo_file = "some file name", title = "My title", photo_file_data=filehandler)

Or if the you've generated the image data by any another way:

>>> from StringIO import StringIO
>>> filehandler = StringIO(image_data)
>>> flickr_api.upload(photo_file = "some file name", title = "My title", photo_file_data=filehandler)

• Add/Delete a comment

>>> comment = photo.addComment(comment_text = "A comment") # adding a comment
>>> comment.delete() # deleting the comment

• Retrieve the comments

>>> comments = photo.getComments()
>>> for comment in comments : print comment.text

• Walking through search results

Results returned by Flickr may be paginated. Pages can usually be dealt with using the page and per_page arguments. However, to avoid having to deal with pages manually, the Walker object exists:

w = Walker(Photo.search, tags="animals")
for photo in w:
    print photo.title

Managing Photosets (aka Albums)

• Get the photosets of a user

>>> photosets = user.getPhotosets()

• Create a photoset

>>> photoset = flickr_api.Photoset.create(title = "The title of the photoset", primary_photo = cover_photo)

Note: cover_photo is an instance of Photo() (see #77)

• Delete a photoset

>>> photoset.delete()

• Get the photos of a photoset

>>> photos = photoset.getPhotos()

• Add a photo to a set

>>> photoset.addPhoto(photo = a_photo)

• Add a comment to a photoset

>>> photoset.addComment(comment_text = "the text of the comment...")

Cache

It is possible to cache frequent request to avoid repeated access to Flickr site:

import flickr_api
flickr_api.enable_cache()

You can also provide customized cache object:

import flickr_api
from flickr_api.cache import SimpleCache
flickr_api.enable_cache(SimpleCache(timeout = 300,max_entries = 10)

The code for caching comes from the Stuvel's Python API. It should then be compliant with Django caching system.

import flickr_api
from django.core.cache import cache
flickr_api.enable_cache(cache)

To disable the caching system:

flickr_api.disable_cache()