Flickr has a really nice API exposed that allows anyone with an API key to interrogate and present public Flickr data on their own website or application. The API supports a number of formats such as REST, XML-RPC and SOAP, or you could use a third-party API kit. In .NET-land there is a fantastic open source wrapper for the API - FlickrNET. This article explains some of the fundamentals of getting up and running with the FlickrNET API.
Why we used Flickr
2009 is the 250th anniversary of Robert Burn's birth, In Frame Digital towers we received a brief at the end of 2008 from Homecoming Scotland to create a promotional site to mark the bard's birthday and launch 'Homecoming Scotland 2009', a global campaign to promote Burn's night worldwide and encourage people to host their own Burn's party. The website would be used to provide historical information on Robert Burns and also be used as online resource for users wanting to host their own Burn's Supper, wherever they were in the world. One of the key aims was that registered users could create their own online account, accessing special stationary and manage invitations online. After the big day, users could upload images and videos of their Burns night to the website and share them with the world. Rather than build our own image upload and management tools we immediately thought 'Flickr'. Why reinvent the wheel where there are some perfectly good round ones available already?
Cool, before I read on, can I see it working?
Sure. Download and play with the demo, or use the live example to upload files to our own Frame Digital account. Just don't go getting clever with your image uploads, everything is set to private by default.
You could also do worse than look at the website the inspiration for this article came, our implementation of Flickr.NET on the World Famous Burns Supper website.
Getting Started with FlickrNET.
This article is aimed at .NET 3.5 and assums you know how to build websites in .NET using Visual Studio 2008 or the free Visual Web Developer 2008 Express Edition. All the example code below is in C#.
There are already some great examples on the project's Codeplex site including example applications and an introduction to some of the Flickr.NET concepts here. This article aims to add to this with some simple complete working examples.
First off, you'll need:
- A Flickr API key - signup and get one Flickr.
- The Flick.NET API library from Codeplex either download the binary or the source, depending on how much you want to tinker with it)
The Flickr.NET library and the methods used match the API naming convention pretty closely, often referring to the Flickr API docs can help if you aren't sure how what all the method calls mean.
A Simple 'hello world'
Probably one of the simplest operations you can do with the Flickr API is a text search. Okay, not exactly "hello world" but its images we are dealing with, so let search them.
Make sure you have the correct entries in the web.config file, you need to add the following entries
A new entry to the <configSections> :
<section name="flickrNet" type="FlickrNet.FlickrConfigurationManager,FlickrNet"/>
An entry for flickrNet, containing your API key and shared secret:
<flickrNet apiKey="27fbead54d11ca5bd00ad282797xxxxx" secret="05aa93655a3xxxxx" cacheDisabled="true" />
Searching works by populating a PhotoSearchOptions object then sending it off to Flickr to get your matches.
This is a basic one that creates a search with some basic parameters set pretty wide. We are searching for 'hello world' and it can be in the title, description, metatags or pretty much anywhere because of the PhotoSearchExtras.All and MachineTagMode.AnyTag parameters.
FlickrNet.PhotoSearchOptions options = new FlickrNet.PhotoSearchOptions();
options.PerPage = 25;
options.Text = 'hello world';
options.MachineTagMode = MachineTagMode.AnyTag;
options.Extras = PhotoSearchExtras.All;
Photos photos = flickr.PhotosSearch(options);
There are a lot of search options, its almost a blog post in itself, or you could go read the documentation on Flickr.
Authentication
To do anything remotely interesting with Flickr, such as upload photos or edit existing ones you have to authenticate to a user account. When you authenticate a user you receive a token from Flickr. This token is unique for your API key and the user and permissions the user has allowed you to have. Once you have a valid authentication token, it does not change unless the user revokes it. If you are manipulating your own account, or plan on accessing the same account multiple times, its a good idea to save it.
1. Setup your website
Make sure your website is setup to run the Flickr.NET Library. For example, if you can run a simple search uisng the API like the one outlined above, you're good to go.
2. Configure your API settings on Flickr
For a web application, you must configure your callback URL in the API control panel on the Flickr website to return back to your authentication page - you can use localhost for this if required.
3. Obtain Auth.Token from Flickr
Once your have a working website and the API callback is configured you can now actually go get the frob needed to generate the auth token.
This is a two stage process:
- Create the authentication URL using your own API key and shared secret and visit Flickr, login to your account and allow the requested permissions to get the Frob.
- Flickr will redirect back to your callback URL with the Frob. We can then use this frob to get our Auth Token from Flickr. In the example code we take this Auth Token and store it in the web.config file (you'll need to give your web.config the correct write permissions for this)
In our demo, we use the following code to generate the correct url with write permissions:
FlickrNet.Flickr flickr = new FlickrNet.Flickr();
// Want to request "write" access so call the AuthCalcWebUrl method.
string auth_url = flickr.AuthCalcWebUrl(FlickrNet.AuthLevel.Write);
// Redirect to our special URL URL
Response.Redirect(auth_url);
If all goes according to plan you should get an authentication token from Flickr - you can then use for uploading and editing images. If you are planning manipulating just one accoutn can can always save the auth token details - providing the account owner doesn't change the permissions, the auth token details don't change either.
Uploading
Ok, first off, you can't upload until you authenticate the account. Got that bit? Ace. If you haven't authenticated, the demo with this article helps you do it, and will even try and save the authentication token to the web.config if you have the correct filesystem permissions.
Flickr.NET contains an UploadPicture method with 10 parameters for title & descriptions and visibility &permissions options. You can leave most empty or set them to their default values for a basic image upload load or go crazy - you can always set them later.
This call will upload an image with visibility set to private, a title set in a textfield, and description and metatags set empty:
var flickr_id = flickr.UploadPicture(upImage.PostedFile.InputStream,
title,"","", 0, 0, 0, FlickrNet.ContentType.Photo, SafetyLevel.None, HiddenFromSearch.Visible);
Setting Permissions
.UploadPicture Returns a flickr_id that you can then use to query the upload, set permissions and edit the meta data.
For example, once we have the flickr_id we can use it to edit the permissions. This example will set the image so it is only visible to Friends nad only friends and family can edit the metadata:
flickr.PhotosSetPerms(FlickrImg.Flickr_id, 0, 0, 1, PermissionComment.Everybody, PermissionAddMeta.FriendsAndFamily);
Being able to modify permissions is really useful, for example when users upload images on our sites, they can be moderated and set to visible via our own CMS without CMS users having to go anywhere near Flickr.
Retrieving Image URLs from your uploaded image
So now you've got your image into Flickr, you'll be wanting to get it out again, right? Well its pretty easy too. Depending on how large your image is flickr will automatically resize it into different sizes which in Flickr.NET are stored in a photo SizeCollection.
This example queries Flickr using our recently obtained flickr_id and displays the medium sized image and a link to the image on Flickr using an Image and HyperLink control:
var flickrPhotos = flickr.PhotosGetSizes(flickr_id);
hypFlickr.NavigateUrl = flickrPhotos.SizeCollection[3].Url;
hypFlickr.Text = "View image on Flickr";
hypFlickr.Target = "_blank";
imgFlickr.ImageUrl = flickrPhotos.SizeCollection[3].Source;
And Finally...
This is just a small introduction, download and use our working demo or check out the live example, it will show you how to search, upload and authenticate using the Flickr.NET assembly.
Huge thanks also has to go to Tim Heuer and Sam Judson for bothering to take the time to write the Flick.NET API library in the first place, and making things just a little bit easier in .NET-land.