node package manager
Loosely couple your services. Use Orgs to version and reuse your code. Create a free org »

flickr-sdk

flickr-sdk

Almost certainly the best Flickr API client in the world for node and the browser

Install

$ npm install flickr-sdk

Usage

flickr-sdk is based on superagent and all methods that make API calls will return a superagent Request instance configured for the request. This means that you can do anything with Flickr requests that you can do with superagent.

The Flickr API is divided into several services:

  • The REST API service, which provides access to Flickr data
  • The OAuth service, which authenticates users via OAuth 1.0
  • The Feeds service, which provides feeds of public Flickr data
  • The Upload service, where you can upload photos!
  • The Replace service, where you can replace photos you previously uploaded

Example

var Flickr = require('flickr-sdk');

Browser Usage

Since OAuth 1.0 requires your application's key and secret to sign requests, flickr-sdk does not support this authentication method in the browser. Upload, Replace, and REST API calls that require authentication will not work without a valid OAuth signature. You can still use flickr-sdk to call REST API methods that don't require authentication or to get public feeds.

flickr-sdk has been tested with browserify but should work with other client-side module bundlers like webpack and rollup. If you need a standalone browser-ready version of flickr-sdk, each release on npm will contain a browserified version of this module at node_modules/flickr-sdk/flickr-sdk.js. It is not minified.

Flickr

All of the REST API methods are available on the Flickr prototype. Each method accepts a single parameter which is an optional hash of arguments. Refer to the REST API docs for the full list of methods and their supported arguments.

Method Permissions Required Arguments
flickr.activity.userComments read 👀
flickr.activity.userPhotos read 👀
flickr.auth.checkToken none auth_token
flickr.auth.getFrob none
flickr.auth.getFullToken none mini_token
flickr.auth.getToken none frob
flickr.auth.oauth.checkToken none oauth_token
flickr.auth.oauth.getAccessToken none
flickr.blogs.getList read 👀
flickr.blogs.getServices none
flickr.blogs.postPhoto write ✏️ photo_id, title, description
flickr.cameras.getBrandModels none brand
flickr.cameras.getBrands none
flickr.collections.getInfo read 👀 collection_id
flickr.collections.getTree none
flickr.commons.getInstitutions none
flickr.contacts.getList read 👀
flickr.contacts.getListRecentlyUploaded read 👀
flickr.contacts.getPublicList none user_id
flickr.contacts.getTaggingSuggestions read 👀
flickr.favorites.add write ✏️ photo_id
flickr.favorites.getContext none photo_id, user_id
flickr.favorites.getList none
flickr.favorites.getPublicList none user_id
flickr.favorites.remove write ✏️ photo_id
flickr.galleries.addPhoto write ✏️ gallery_id, photo_id
flickr.galleries.create write ✏️ title, description
flickr.galleries.editMeta write ✏️ gallery_id, title
flickr.galleries.editPhoto write ✏️ gallery_id, photo_id, comment
flickr.galleries.editPhotos write ✏️ gallery_id, primary_photo_id, photo_ids
flickr.galleries.getInfo none gallery_id
flickr.galleries.getList none user_id
flickr.galleries.getListForPhoto none photo_id
flickr.galleries.getPhotos none gallery_id
flickr.groups.browse read 👀
flickr.groups.getInfo none group_id
flickr.groups.join write ✏️ group_id
flickr.groups.joinRequest write ✏️ group_id, message, accept_rules
flickr.groups.leave delete 💥 group_id
flickr.groups.search none text
flickr.groups.discuss.replies.add write ✏️ group_id, topic_id, message
flickr.groups.discuss.replies.delete delete 💥 group_id, topic_id, reply_id
flickr.groups.discuss.replies.edit write ✏️ group_id, topic_id, reply_id, message
flickr.groups.discuss.replies.getInfo none group_id, topic_id, reply_id
flickr.groups.discuss.replies.getList none group_id, topic_id, per_page
flickr.groups.discuss.topics.add write ✏️ group_id, subject, message
flickr.groups.discuss.topics.getInfo none group_id, topic_id
flickr.groups.discuss.topics.getList none group_id
flickr.groups.members.getList read 👀 group_id
flickr.groups.pools.add write ✏️ photo_id, group_id
flickr.groups.pools.getContext none photo_id, group_id
flickr.groups.pools.getGroups read 👀
flickr.groups.pools.getPhotos none group_id
flickr.groups.pools.remove write ✏️ photo_id, group_id
flickr.interestingness.getList none
flickr.machinetags.getNamespaces none
flickr.machinetags.getPairs none
flickr.machinetags.getPredicates none
flickr.machinetags.getRecentValues none
flickr.machinetags.getValues none namespace, predicate
flickr.panda.getList none
flickr.panda.getPhotos none panda_name
flickr.people.findByEmail none find_email
flickr.people.findByUsername none username
flickr.people.getGroups read 👀 user_id
flickr.people.getInfo none user_id
flickr.people.getLimits read 👀
flickr.people.getPhotos none user_id
flickr.people.getPhotosOf none user_id
flickr.people.getPublicGroups none user_id
flickr.people.getPublicPhotos none user_id
flickr.people.getUploadStatus read 👀
flickr.photos.addTags write ✏️ photo_id, tags
flickr.photos.delete delete 💥 photo_id
flickr.photos.getAllContexts none photo_id
flickr.photos.getContactsPhotos read 👀
flickr.photos.getContactsPublicPhotos none user_id
flickr.photos.getContext none photo_id
flickr.photos.getCounts read 👀
flickr.photos.getExif none photo_id
flickr.photos.getFavorites none photo_id
flickr.photos.getInfo none photo_id
flickr.photos.getNotInSet read 👀
flickr.photos.getPerms read 👀 photo_id
flickr.photos.getPopular none
flickr.photos.getRecent none
flickr.photos.getSizes none photo_id
flickr.photos.getUntagged read 👀
flickr.photos.getWithGeoData read 👀
flickr.photos.getWithoutGeoData read 👀
flickr.photos.recentlyUpdated read 👀 min_date
flickr.photos.removeTag write ✏️ tag_id
flickr.photos.search none
flickr.photos.setContentType write ✏️ photo_id, content_type
flickr.photos.setDates write ✏️ photo_id
flickr.photos.setMeta write ✏️ photo_id
flickr.photos.setPerms write ✏️ photo_id, is_public, is_friend, is_family
flickr.photos.setSafetyLevel write ✏️ photo_id
flickr.photos.setTags write ✏️ photo_id, tags
flickr.photos.comments.addComment write ✏️ photo_id, comment_text
flickr.photos.comments.deleteComment write ✏️ comment_id
flickr.photos.comments.editComment write ✏️ comment_id, comment_text
flickr.photos.comments.getList none photo_id
flickr.photos.comments.getRecentForContacts read 👀
flickr.photos.geo.batchCorrectLocation write ✏️ lat, lon, accuracy
flickr.photos.geo.correctLocation write ✏️ photo_id, foursquare_id
flickr.photos.geo.getLocation none photo_id
flickr.photos.geo.getPerms read 👀 photo_id
flickr.photos.geo.photosForLocation read 👀 lat, lon
flickr.photos.geo.removeLocation write ✏️ photo_id
flickr.photos.geo.setContext write ✏️ photo_id, context
flickr.photos.geo.setLocation write ✏️ photo_id, lat, lon
flickr.photos.geo.setPerms write ✏️ is_public, is_contact, is_friend, is_family, photo_id
flickr.photos.licenses.getInfo none
flickr.photos.licenses.setLicense write ✏️ photo_id, license_id
flickr.photos.notes.add write ✏️ photo_id, note_x, note_y, note_w, note_h, note_text
flickr.photos.notes.delete write ✏️ note_id
flickr.photos.notes.edit write ✏️ note_id, note_x, note_y, note_w, note_h, note_text
flickr.photos.people.add write ✏️ photo_id, user_id
flickr.photos.people.delete write ✏️ photo_id, user_id
flickr.photos.people.deleteCoords write ✏️ photo_id, user_id
flickr.photos.people.editCoords write ✏️ photo_id, user_id, person_x, person_y, person_w, person_h
flickr.photos.people.getList none photo_id
flickr.photos.suggestions.approveSuggestion write ✏️ suggestion_id
flickr.photos.suggestions.getList read 👀
flickr.photos.suggestions.rejectSuggestion write ✏️ suggestion_id
flickr.photos.suggestions.removeSuggestion write ✏️ suggestion_id
flickr.photos.suggestions.suggestLocation write ✏️ photo_id, lat, lon
flickr.photos.transform.rotate write ✏️ photo_id, degrees
flickr.photos.upload.checkTickets none tickets
flickr.photosets.addPhoto write ✏️ photoset_id, photo_id
flickr.photosets.create write ✏️ title, primary_photo_id
flickr.photosets.delete write ✏️ photoset_id
flickr.photosets.editMeta write ✏️ photoset_id, title
flickr.photosets.editPhotos write ✏️ photoset_id, primary_photo_id, photo_ids
flickr.photosets.getContext none photo_id, photoset_id
flickr.photosets.getInfo none photoset_id, user_id
flickr.photosets.getList none
flickr.photosets.getPhotos none photoset_id, user_id
flickr.photosets.orderSets write ✏️ photoset_ids
flickr.photosets.removePhoto write ✏️ photoset_id, photo_id
flickr.photosets.removePhotos write ✏️ photoset_id, photo_ids
flickr.photosets.reorderPhotos write ✏️ photoset_id, photo_ids
flickr.photosets.setPrimaryPhoto write ✏️ photoset_id, photo_id
flickr.photosets.comments.addComment write ✏️ photoset_id, comment_text
flickr.photosets.comments.deleteComment write ✏️ comment_id
flickr.photosets.comments.editComment write ✏️ comment_id, comment_text
flickr.photosets.comments.getList none photoset_id
flickr.places.find none query
flickr.places.findByLatLon none lat, lon
flickr.places.getChildrenWithPhotosPublic none
flickr.places.getInfo none
flickr.places.getInfoByUrl none url
flickr.places.getPlaceTypes none
flickr.places.getShapeHistory none
flickr.places.getTopPlacesList none place_type_id
flickr.places.placesForBoundingBox none bbox
flickr.places.placesForContacts read 👀
flickr.places.placesForTags none place_type_id
flickr.places.placesForUser read 👀
flickr.places.resolvePlaceId none place_id
flickr.places.resolvePlaceURL none url
flickr.places.tagsForPlace none
flickr.prefs.getContentType read 👀
flickr.prefs.getGeoPerms read 👀
flickr.prefs.getHidden read 👀
flickr.prefs.getPrivacy read 👀
flickr.prefs.getSafetyLevel read 👀
flickr.profile.getProfile none user_id
flickr.push.getSubscriptions read 👀
flickr.push.getTopics none
flickr.push.subscribe read 👀 topic, callback, verify
flickr.push.unsubscribe read 👀 topic, callback, verify
flickr.reflection.getMethodInfo none method_name
flickr.reflection.getMethods none
flickr.stats.getCSVFiles read 👀
flickr.stats.getCollectionDomains read 👀 date
flickr.stats.getCollectionReferrers read 👀 date, domain
flickr.stats.getCollectionStats read 👀 date, collection_id
flickr.stats.getPhotoDomains read 👀 date
flickr.stats.getPhotoReferrers read 👀 date, domain
flickr.stats.getPhotoStats read 👀 date, photo_id
flickr.stats.getPhotosetDomains read 👀 date
flickr.stats.getPhotosetReferrers read 👀 date, domain
flickr.stats.getPhotosetStats read 👀 date, photoset_id
flickr.stats.getPhotostreamDomains read 👀 date
flickr.stats.getPhotostreamReferrers read 👀 date, domain
flickr.stats.getPhotostreamStats read 👀 date
flickr.stats.getPopularPhotos read 👀
flickr.stats.getTotalViews read 👀
flickr.tags.getClusterPhotos none tag, cluster_id
flickr.tags.getClusters none tag
flickr.tags.getHotList none
flickr.tags.getListPhoto none photo_id
flickr.tags.getListUser none
flickr.tags.getListUserPopular none
flickr.tags.getListUserRaw none
flickr.tags.getMostFrequentlyUsed read 👀
flickr.tags.getRelated none tag
flickr.test.echo none
flickr.test.login read 👀
flickr.test.null read 👀
flickr.testimonials.addTestimonial write ✏️ user_id, testimonial_text
flickr.testimonials.approveTestimonial write ✏️ testimonial_id
flickr.testimonials.deleteTestimonial write ✏️ testimonial_id
flickr.testimonials.editTestimonial write ✏️ user_id, testimonial_id, testimonial_text
flickr.testimonials.getAllTestimonialsAbout read 👀
flickr.testimonials.getAllTestimonialsAboutBy read 👀 user_id
flickr.testimonials.getAllTestimonialsBy read 👀
flickr.testimonials.getPendingTestimonialsAbout read 👀
flickr.testimonials.getPendingTestimonialsAboutBy read 👀 user_id
flickr.testimonials.getPendingTestimonialsBy read 👀
flickr.testimonials.getTestimonialsAbout none user_id
flickr.testimonials.getTestimonialsAboutBy read 👀 user_id
flickr.testimonials.getTestimonialsBy none user_id
flickr.urls.getGroup none group_id
flickr.urls.getUserPhotos none
flickr.urls.getUserProfile none
flickr.urls.lookupGallery none url
flickr.urls.lookupGroup none url
flickr.urls.lookupUser none url

Kind: global class

new Flickr(auth)

Creates a new Flickr REST API client.

You must pass a superagent plugin or your API key as the first parameter. For methods that don't require authentication, you can simply provide your API key. For methods that do require authentication, use the OAuth plugin.

Param Type Description
auth function | String An authentication plugin function or an API key

Example (Get info about a public photo with your API key)

 
var flickr = new Flickr(process.env.FLICKR_API_KEY);
 
flickr.photos.getInfo({
  photo_id: 25825763 // sorry, @dokas
}).then(function (res) {
  console.log('yay!', res.body);
}).catch(function (err) {
  console.error('bonk', err);
});

Example (Searching for public photos with your API key)

 
var flickr = new Flickr(process.env.FLICKR_API_KEY);
 
flickr.photos.search({
  text: 'doggo'
}).then(function (res) {
  console.log('yay!', res.body);
}).catch(function (err) {
  console.error('bonk', err);
});

Example (Authenticate as a user with the OAuth plugin)

 
var flickr = new Flickr(Flickr.OAuth.createPlugin(
  process.env.FLICKR_CONSUMER_KEY,
  process.env.FLICKR_CONSUMER_SECRET,
  process.env.FLICKR_OAUTH_TOKEN,
  process.env.FLICKR_OAUTH_TOKEN_SECRET
));
 
flickr.test.login().then(function (res) {
  console.log('yay!', res.body);
}).catch(function (err) {
  console.error('bonk', err);
});

Flickr.OAuth

Kind: static class of Flickr

new OAuth(consumerKey, consumerSecret)

Creates a new OAuth service instance. You can use this service to request and validate OAuth tokens, as well as generate an auth plugin suitable for use with the REST and Upload services.

You need to register an application to obtain your consumerKey and consumerSecret.

OAuth 1.0 requires your consumer secret to sign calls, and you should never expose secrets to the browser.

Param Type Description
consumerKey String The application's API key
consumerSecret String The application's API secret

Example

var oauth = new Flickr.OAuth(
  process.env.FLICKR_CONSUMER_KEY,
  process.env.FLICKR_CONSUMER_SECRET
);

oAuth.request(oauthCallback) ⇒ Request

Get a Request Token using the consumer key.

Kind: instance method of OAuth
See

Param Type Description
oauthCallback String Your application's OAuth callback URL

Example

oauth.request('http://localhost:3000/oauth/callback').then(function (res) {
  console.log('yay!', res);
}).catch(function (err) {
  console.error('bonk', err);
});

oAuth.authorizeUrl(requestToken, [perms]) ⇒ String

Returns the authorization url for requestToken. You may also pass the perms your app is requesting as read (the default), write, or delete. Your application should redirect the user here to ask them to verify your request token.

Kind: instance method of OAuth
See: https://www.flickr.com/services/api/auth.oauth.html#authorization

Param Type Default Description
requestToken String The OAuth request token
[perms] String read Permission level, may be "read", "write" or "delete"

Example

var url = oauth.authorizeUrl(requestToken); // "https://www.flickr.com/services/oauth..."
 
res.setHeader("Location", url);
res.statusCode = 302;
res.end();

oAuth.verify(oauthToken, oauthVerifier, tokenSecret) ⇒ Request

Verify an OAuth token using the verifier and token secret. If your user has indeed verified your request token, you will receive an OAuth token and secret back, as well as some very basic profile information. You can now use this token and secret to make calls to the REST API.

Kind: instance method of OAuth
See

Param Type Description
oauthToken String The OAuth token to verify
oauthVerifier String The OAuth token verifier string you received from the callback
tokenSecret String The OAuth token secret

Example

oauth.verify(oauthToken, oauthVerifier, tokenSecret).then(function (res) {
  console.log('oauth token:', res.body.oauth_token);
  console.log('oauth token secret:', res.body.oauth_token_secret);
}).catch(function (err) {
 console.log('bonk', err);
});

oAuth.plugin(oauthToken, oauthTokenSecret) ⇒ function

Returns an oauth plugin for this consumer key and secret.

Kind: instance method of OAuth

Param Type Description
oauthToken String The OAuth token
oauthTokenSecret String The OAuth token secret

Example

var flickr = new Flickr(oauth.plugin(
  oauthToken,
  oauthTokenSecret
));

OAuth.createPlugin(consumerKey, consumerSecret, oauthToken, oauthTokenSecret) ⇒ function

Returns an oauth plugin for this consumer key, consumer secret, oauth token and oauth token secret,

Kind: static method of OAuth

Param Type Description
consumerKey String The application's API key
consumerSecret String The application's API secret
oauthToken String The OAuth token
oauthTokenSecret String The OAuth token secret

Example

var flickr = new Flickr(Flickr.OAuth.createPlugin(
  process.env.FLICKR_CONSUMER_KEY,
  process.env.FLICKR_CONSUMER_SECRET,
  process.env.FLICKR_OAUTH_TOKEN,
  process.env.FLICKR_OAUTH_TOKEN_SECRET
));

Flickr.Upload ⇐ Request

Kind: static class of Flickr
Extends: Request
See: https://www.flickr.com/services/api/upload.api.html

new Upload(auth, file, [args])

Creates a new Upload service instance. Since the Upload API only does one thing (upload files), an Upload instance is simply a Request subclass.

The Upload endpoint requires authentication. You should pass a configured instance of the OAuth plugin to upload photos on behalf of another user.

Param Type
auth function
file String | fs.ReadStream | Buffer
[args] Object

Example

var upload = new Flickr.Upload(auth, 'upload.png', {
  title: 'Works on MY machine!'
});
 
upload.then(function (res) {
  console.log('yay!', res.body);
}).catch(function (err) {
  console.error('bonk', err);
});

Flickr.Replace ⇐ Request

Kind: static class of Flickr
Extends: Request
See: https://www.flickr.com/services/api/replace.api.html

new Replace(auth, photoID, file, [args])

Creates a new Replace service instance. Since the Replace API only does one thing (replace files), an Replace instance is simply a Request subclass.

The Replace endpoint requires authentication. You should pass a configured instance of the OAuth plugin to replace photos on behalf of another user.

Param Type Description
auth function
photoID Number | String The ID of the photo to replace
file String | fs.ReadStream | Buffer
[args] Object

Example

var replace = new Flickr.Replace(auth, 41234567890, 'replace.png', {
  title: 'Now in pink!'
});
 
replace.then(function (res) {
  console.log('yay!', res.body);
}).catch(function (err) {
  console.error('bonk', err);
});

Flickr.Feeds

Kind: static class of Flickr

new Feeds([args])

Creates a new Feeds service instance. You can use this instance to explore and retrieve public Flickr API data.

Param Type Default Description
[args] Object Arguments that will be passed along with every feed request
[args.format] String json The feed response format
[args.lang] String en-us The language to request for the feed

Example

var feeds = new Flickr.Feeds();

feeds.publicPhotos([args]) ⇒ Request

Returns a list of public content matching some criteria.

Kind: instance method of Feeds
See: https://www.flickr.com/services/feeds/docs/photos_public/

Param Type
[args] Object

feeds.friendsPhotos(args) ⇒ Request

Returns a list of public content from the contacts, friends & family of a given person.

Kind: instance method of Feeds
See: https://www.flickr.com/services/feeds/docs/photos_friends/

Param Type Description
args Object
args.user_id Number | String The user ID of the user to fetch friends' photos and videos for.

feeds.favePhotos(args) ⇒ Request

Returns a list of public favorites for a given user.

Kind: instance method of Feeds
See: https://www.flickr.com/services/feeds/docs/photos_faves/

Param Type Description
args Object
args.id Number | String A single user ID. This specifies a user to fetch for.

feeds.groupDiscussions(args) ⇒ Request

Returns a list of recent discussions in a given group.

Kind: instance method of Feeds
See: https://www.flickr.com/services/feeds/docs/groups_discuss/

Param Type Description
args Object
args.id Number The ID of the group to fetch discussions for.

feeds.groupPool(args) ⇒ Request

Returns a list of things recently added to the pool of a given group.

Kind: instance method of Feeds
See: https://www.flickr.com/services/feeds/docs/groups_pool/

Param Type Description
args Object
args.id Number The ID of the group to fetch for.

feeds.forum([args]) ⇒ Request

Returns a list of recent topics from the forum.

Kind: instance method of Feeds
See: https://www.flickr.com/services/feeds/docs/forums/

Param Type
[args] Object

feeds.recentActivity(args) ⇒ Request

Returns a list of recent comments on photostream and sets belonging to a given user.

Kind: instance method of Feeds
See: https://www.flickr.com/services/feeds/docs/activity/

Param Type Description
args Object
args.user_id Number | String The user ID to fetch recent activity for.

feeds.recentComments(args) ⇒ Request

Returns a list of recent comments that have been commented on by a given person.

Kind: instance method of Feeds
See: https://www.flickr.com/services/feeds/docs/photos_comments/

Param Type Description
args Object
args.user_id Number | String The user ID to fetch recent comments for.

License

Code licensed under the MIT license. See LICENSE file for terms.