flickr_api Python Library

The Walker utility class automatically handles pagination when iterating through large result sets returned by methods that return a FlickrList. You can pass the method itself and its arguments to the Walker constructor. It supports slicing to limit the number of results processed.

from flickr_api import Walker

# Create a walker for any method that returns paginated results
walker = Walker(flickr_api.Photo.search, tags="nature")

# Iterate through ALL results (handles pagination automatically)
for photo in walker:
    print(photo.title)

# Get total count
print(f"Total results: {len(walker)}")

# Use slicing to limit results
for photo in walker[:100]:  # First 100 only
    print(photo.title)

Most methods that return multiple items return a FlickrList object. This is a list wrapper that provides access to pagination metadata via the .info attribute.

photos = user.getPublicPhotos(per_page=50)

# Access items
for photo in photos:
    print(photo.title)

# Access pagination info
print(f"Page: {photos.info.page}")
print(f"Per page: {photos.info.perpage}")
print(f"Total pages: {photos.info.pages}")
print(f"Total items: {photos.info.total}")

Most methods in the library are designed to be flexible. Instead of requiring a full object instance, you can often pass the unique ID string of that object directly to the method.

# Using an object instance
photo.addTag(tag=tag_object)

# Using an ID string instead
photo.addTag(tag_id="12345")

The library offers two distinct ways to interact with Flickr:

1. Object-Oriented Interface (Recommended): This approach uses domain objects (like Person, Photo, Group) to navigate the Flickr ecosystem. It is more intuitive for working with related entities.
2. Direct REST API Access: This approach allows you to call the underlying Flickr API methods directly via the flickr object, which is useful for specific API calls not covered by the high-level objects.

import flickr_api

# 1. Object-Oriented Interface
flickr_api.set_keys(api_key="...", api_secret="...")
user = flickr_api.Person.findByUserName("username")
photos = user.getPublicPhotos()

# 2. Direct REST API Access
from flickr_api.api import flickr
response = flickr.photos.search(tags="sunset", per_page=10)

The library provides a Pythonic abstraction over the Flickr REST API using domain objects such as Photo, Person, Gallery, and Photoset.

Methods on these objects are flexible: they accept either the domain object itself or its corresponding ID string. For example, when adding a tag to a photo, you can pass a tag object or a tag_id string.

# Example of flexible method arguments
photo.addTag(tag=tag_object)    # Using object
photo.addTag(tag_id="12345")    # Using ID string

The library supports two levels of access:

1. Read-Only Access: Requires only API keys. This allows you to access public data (e.g., searching photos, finding users).
2. Write Access: Requires OAuth 1.0a authentication. This is necessary for operations that modify data, such as uploading photos, deleting photos, or adding comments.

Permission levels for OAuth requests include:

• read
• write (includes read permissions)
• delete (includes all write permissions)

Install the library using pip to begin using the object-oriented Flickr wrapper.

pip install flickr_api

Before making any API calls, you must provide your Flickr API key and secret using flickr_api.set_keys(). This is a required step for all sessions.

import flickr_api

flickr_api.set_keys(api_key="your_api_key", api_secret="your_api_secret")

The library uses domain objects like Person and Photo to interact with Flickr. You can find users, retrieve their public photos, search for photos by tags, and download photo files to your local system.

import flickr_api

# Set your API credentials (required)
flickr_api.set_keys(api_key="your_api_key", api_secret="your_api_secret")

# Find a user
user = flickr_api.Person.findByUserName("username")

# Get their public photos
photos = user.getPublicPhotos()

# Search for photos
results = flickr_api.Photo.search(tags="sunset", per_page=10)

# Download a photo
photo = results[0]
photo.save("sunset.jpg", size_label="Large")

To perform read-only operations (like searching or fetching public data), you must first obtain an API key and secret from the Flickr App Garden and configure the library using flickr_api.set_keys().

import flickr_api

flickr_api.set_keys(api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET")

To use the library, you must provide your Flickr API credentials. You can do this using one of two methods:

Method 1: Direct Assignment (Recommended)

Use flickr_api.set_keys() to assign your credentials directly in your code.

Method 2: Configuration File

Create a file named flickr_keys.py in your project root or Python path with the following content. The library will automatically detect these variables:

API_KEY = "your_api_key"
API_SECRET = "your_api_secret"

import flickr_api

flickr_api.set_keys(api_key="your_api_key", api_secret="your_api_secret")