Developer Guide: API
To begin using the Flickr API:
Things You Oughta Know
- Documentation: Here's the documentation for the whole Flickr API. You can find here all the methods and feeds available, plus API kit details.
- Authentication: Flickr's auth flow is designed to ensure our users' accounts are safe. We require that users go to Flickr to authenticate a 3rd party application (such as yours), instead of allowing a possibly malicious 3rd party to handle the username/password. We make no exceptions. This approach supports all manner of applications, from websites, to mobile clients, to set-top boxes. Please carefully review the documentation to choose the flow that is most appropriate for your integration.
- Limits: Since the Flickr API is quite easy to use, it's also quite easy to abuse, which threatens all services relying on the Flickr API. To help prevent this, we limit the access to the API per key. If your application stays under 3600 queries per hour across the whole key (which means the aggregate of all the users of your integration), you'll be fine. If we detect abuse on your key, we will need to expire the key, or turn it off, in order to preserve the Flickr API functionality for others (including us!). We also track usage on other factors as well to ensure no API user abuses the system.
- Data Security: Don't store all user data, such as auth tokens, in a central place. Doing so creates a tempting place for hackers to target in order to access many accounts at once.
- Optimizing API queries: Search and localized calls take more CPU cycles than simple data lookups and so they may take more time to execute. Also, keep an eye out for the "extras" parameters availability in the API queries which may help reduce how many calls you need to make. Check out our Code blog for some tips, such as this post on the Standard Photo Response.
- Privacy: Every user has a default privacy setting for photos uploaded to their account. Please honor this default by either uploading with this setting or presenting it as the pre-selected option in a list of other privacy options. You can get this default via the
flickr.prefs.getPrivacyAPI call, and please check this default daily in case the user has changed it. If your project is presenting the privacy options for a user to choose among, please use the standardized Flickr terms: Public, Friends, Family, Friends and Family, Private.
- Short-term caching: Your application can cache API results and images for up to 24 hrs to help reduce API load.
- Using the "flic.kr" shorturl: If you'd like to use a short url for a photo, you can use the native flic.kr url shortener. The format is:
flic.kr/p/[short-photo-id]where the short photo id is a base58 conversion of the photo id. You can find more info and code samples on this post of the Flickr API Group.
- Requesting keys: You can request an API key here. We cannot change which account a key is handled under, so make sure you don't apply for the key under a developer's personal account since if they leave, your Flickr API key would be harder for you to control.
- Let the users know what's going on when you interact or modify their photos. For instance, you should let the user know if you're adding tags to an uploaded image.
- Screen scraping flickr.com isn't good. The API is the scalable way to get this data, and we also routinely block screen scrapers.
- Photographers upload their photos with a certain aspect ratio. Please honor these photo dimensions. Square thumbnails are an exception in order to enable browsing.
- When linking through to Flickr, link back to the photo's page and not to a hosting url that contains the term "farm" which does not provide any context or metadata around the photo.
We don't provide technical support for the Flickr API. However, here are some resources in case you have a question or a problem:
- code.flickr.com is the Flickr developer blog, where Flickr team members geek out on all sorts of Flickry things, such as:
- Flickr API Group: this is where Flickr developers can converse with each other and the Flickr engineering team on various development topics.
- API Mailing List: the mailing list for Flickr API developers.
- @flickrAPI on Twitter: the announcements stream for updates to the API and the Developer Guide, plus code.flickr.com blog posts and other neat developer-related news.
- App Garden: Flickr has an App Garden to showcase the apps built with the Flickr API. Fill out a profile page for your app's API key to be included, particularly if you have an uploader since these get called out on the photo page as the uploader source. FAQs.
- Flickr Blog: blog.flickr.net is where we post announcements and share great photos.
- Twitter: twitter.com/flickr is where we share quick announcement with links to our blog. This is an announcement-only and unmonitored account, so please contact us directly through our site if you have any questions or comments.
- API explorer: At the bottom of the API page describing a method, we have a tool called the API Explorer where you can play around with the arguments to a method and see the return. Here's an example:
- API Usage Stats: Check out neat stats about your Flickr API usage plus a handy utilization graph by going to your app key's stats page. You can find the stats page by going to Apps By You and clicking on the "stats" link next to each app.