flickr-sdk

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

Showing:

Popularity

Downloads/wk

2.7K

GitHub Stars

108

Maintenance

Last Commit

1yr ago

Contributors

13

Package

Dependencies

2

Size (min+gzip)

32.3KB

License

MIT

Type Definitions

Tree-Shakeable

No?

Readme

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.

MethodPermissionsRequired Arguments
flickr.activity.userCommentsread 👀
flickr.activity.userPhotosread 👀
flickr.auth.checkTokennoneauth_token
flickr.auth.getFrobnone
flickr.auth.getFullTokennonemini_token
flickr.auth.getTokennonefrob
flickr.auth.oauth.checkTokennoneoauth_token
flickr.auth.oauth.getAccessTokennone
flickr.blogs.getListread 👀
flickr.blogs.getServicesnone
flickr.blogs.postPhotowrite ✏️photo_id, title, description
flickr.cameras.getBrandModelsnonebrand
flickr.cameras.getBrandsnone
flickr.collections.getInforead 👀collection_id
flickr.collections.getTreenone
flickr.commons.getInstitutionsnone
flickr.contacts.getListread 👀
flickr.contacts.getListRecentlyUploadedread 👀
flickr.contacts.getPublicListnoneuser_id
flickr.contacts.getTaggingSuggestionsread 👀
flickr.favorites.addwrite ✏️photo_id
flickr.favorites.getContextnonephoto_id, user_id
flickr.favorites.getListnone
flickr.favorites.getPublicListnoneuser_id
flickr.favorites.removewrite ✏️photo_id
flickr.galleries.addPhotowrite ✏️gallery_id, photo_id
flickr.galleries.createwrite ✏️title, description
flickr.galleries.editMetawrite ✏️gallery_id, title
flickr.galleries.editPhotowrite ✏️gallery_id, photo_id, comment
flickr.galleries.editPhotoswrite ✏️gallery_id, primary_photo_id, photo_ids
flickr.galleries.getInfononegallery_id
flickr.galleries.getListnoneuser_id
flickr.galleries.getListForPhotononephoto_id
flickr.galleries.getPhotosnonegallery_id
flickr.groups.browseread 👀
flickr.groups.getInfononegroup_id
flickr.groups.joinwrite ✏️group_id
flickr.groups.joinRequestwrite ✏️group_id, message, accept_rules
flickr.groups.leavedelete 💥group_id
flickr.groups.searchnonetext
flickr.groups.discuss.replies.addwrite ✏️group_id, topic_id, message
flickr.groups.discuss.replies.deletedelete 💥group_id, topic_id, reply_id
flickr.groups.discuss.replies.editwrite ✏️group_id, topic_id, reply_id, message
flickr.groups.discuss.replies.getInfononegroup_id, topic_id, reply_id
flickr.groups.discuss.replies.getListnonegroup_id, topic_id, per_page
flickr.groups.discuss.topics.addwrite ✏️group_id, subject, message
flickr.groups.discuss.topics.getInfononegroup_id, topic_id
flickr.groups.discuss.topics.getListnonegroup_id
flickr.groups.members.getListread 👀group_id
flickr.groups.pools.addwrite ✏️photo_id, group_id
flickr.groups.pools.getContextnonephoto_id, group_id
flickr.groups.pools.getGroupsread 👀
flickr.groups.pools.getPhotosnonegroup_id
flickr.groups.pools.removewrite ✏️photo_id, group_id
flickr.interestingness.getListnone
flickr.machinetags.getNamespacesnone
flickr.machinetags.getPairsnone
flickr.machinetags.getPredicatesnone
flickr.machinetags.getRecentValuesnone
flickr.machinetags.getValuesnonenamespace, predicate
flickr.panda.getListnone
flickr.panda.getPhotosnonepanda_name
flickr.people.findByEmailnonefind_email
flickr.people.findByUsernamenoneusername
flickr.people.getGroupsread 👀user_id
flickr.people.getInfononeuser_id
flickr.people.getLimitsread 👀
flickr.people.getPhotosnoneuser_id
flickr.people.getPhotosOfnoneuser_id
flickr.people.getPublicGroupsnoneuser_id
flickr.people.getPublicPhotosnoneuser_id
flickr.people.getUploadStatusread 👀
flickr.photos.addTagswrite ✏️photo_id, tags
flickr.photos.deletedelete 💥photo_id
flickr.photos.getAllContextsnonephoto_id
flickr.photos.getContactsPhotosread 👀
flickr.photos.getContactsPublicPhotosnoneuser_id
flickr.photos.getContextnonephoto_id
flickr.photos.getCountsread 👀
flickr.photos.getExifnonephoto_id
flickr.photos.getFavoritesnonephoto_id
flickr.photos.getInfononephoto_id
flickr.photos.getNotInSetread 👀
flickr.photos.getPermsread 👀photo_id
flickr.photos.getPopularnone
flickr.photos.getRecentnone
flickr.photos.getSizesnonephoto_id
flickr.photos.getUntaggedread 👀
flickr.photos.getWithGeoDataread 👀
flickr.photos.getWithoutGeoDataread 👀
flickr.photos.recentlyUpdatedread 👀min_date
flickr.photos.removeTagwrite ✏️tag_id
flickr.photos.searchnone
flickr.photos.setContentTypewrite ✏️photo_id, content_type
flickr.photos.setDateswrite ✏️photo_id
flickr.photos.setMetawrite ✏️photo_id
flickr.photos.setPermswrite ✏️photo_id, is_public, is_friend, is_family
flickr.photos.setSafetyLevelwrite ✏️photo_id
flickr.photos.setTagswrite ✏️photo_id, tags
flickr.photos.comments.addCommentwrite ✏️photo_id, comment_text
flickr.photos.comments.deleteCommentwrite ✏️comment_id
flickr.photos.comments.editCommentwrite ✏️comment_id, comment_text
flickr.photos.comments.getListnonephoto_id
flickr.photos.comments.getRecentForContactsread 👀
flickr.photos.geo.batchCorrectLocationwrite ✏️lat, lon, accuracy
flickr.photos.geo.correctLocationwrite ✏️photo_id, foursquare_id
flickr.photos.geo.getLocationnonephoto_id
flickr.photos.geo.getPermsread 👀photo_id
flickr.photos.geo.photosForLocationread 👀lat, lon
flickr.photos.geo.removeLocationwrite ✏️photo_id
flickr.photos.geo.setContextwrite ✏️photo_id, context
flickr.photos.geo.setLocationwrite ✏️photo_id, lat, lon
flickr.photos.geo.setPermswrite ✏️is_public, is_contact, is_friend, is_family, photo_id
flickr.photos.licenses.getInfonone
flickr.photos.licenses.setLicensewrite ✏️photo_id, license_id
flickr.photos.notes.addwrite ✏️photo_id, note_x, note_y, note_w, note_h, note_text
flickr.photos.notes.deletewrite ✏️note_id
flickr.photos.notes.editwrite ✏️note_id, note_x, note_y, note_w, note_h, note_text
flickr.photos.people.addwrite ✏️photo_id, user_id
flickr.photos.people.deletewrite ✏️photo_id, user_id
flickr.photos.people.deleteCoordswrite ✏️photo_id, user_id
flickr.photos.people.editCoordswrite ✏️photo_id, user_id, person_x, person_y, person_w, person_h
flickr.photos.people.getListnonephoto_id
flickr.photos.suggestions.approveSuggestionwrite ✏️suggestion_id
flickr.photos.suggestions.getListread 👀
flickr.photos.suggestions.rejectSuggestionwrite ✏️suggestion_id
flickr.photos.suggestions.removeSuggestionwrite ✏️suggestion_id
flickr.photos.suggestions.suggestLocationwrite ✏️photo_id, lat, lon
flickr.photos.transform.rotatewrite ✏️photo_id, degrees
flickr.photos.upload.checkTicketsnonetickets
flickr.photosets.addPhotowrite ✏️photoset_id, photo_id
flickr.photosets.createwrite ✏️title, primary_photo_id
flickr.photosets.deletewrite ✏️photoset_id
flickr.photosets.editMetawrite ✏️photoset_id, title
flickr.photosets.editPhotoswrite ✏️photoset_id, primary_photo_id, photo_ids
flickr.photosets.getContextnonephoto_id, photoset_id
flickr.photosets.getInfononephotoset_id, user_id
flickr.photosets.getListnone
flickr.photosets.getPhotosnonephotoset_id, user_id
flickr.photosets.orderSetswrite ✏️photoset_ids
flickr.photosets.removePhotowrite ✏️photoset_id, photo_id
flickr.photosets.removePhotoswrite ✏️photoset_id, photo_ids
flickr.photosets.reorderPhotoswrite ✏️photoset_id, photo_ids
flickr.photosets.setPrimaryPhotowrite ✏️photoset_id, photo_id
flickr.photosets.comments.addCommentwrite ✏️photoset_id, comment_text
flickr.photosets.comments.deleteCommentwrite ✏️comment_id
flickr.photosets.comments.editCommentwrite ✏️comment_id, comment_text
flickr.photosets.comments.getListnonephotoset_id
flickr.places.findnonequery
flickr.places.findByLatLonnonelat, lon
flickr.places.getChildrenWithPhotosPublicnone
flickr.places.getInfonone
flickr.places.getInfoByUrlnoneurl
flickr.places.getPlaceTypesnone
flickr.places.getShapeHistorynone
flickr.places.getTopPlacesListnoneplace_type_id
flickr.places.placesForBoundingBoxnonebbox
flickr.places.placesForContactsread 👀
flickr.places.placesForTagsnoneplace_type_id
flickr.places.placesForUserread 👀
flickr.places.resolvePlaceIdnoneplace_id
flickr.places.resolvePlaceURLnoneurl
flickr.places.tagsForPlacenone
flickr.prefs.getContentTyperead 👀
flickr.prefs.getGeoPermsread 👀
flickr.prefs.getHiddenread 👀
flickr.prefs.getPrivacyread 👀
flickr.prefs.getSafetyLevelread 👀
flickr.profile.getProfilenoneuser_id
flickr.push.getSubscriptionsread 👀
flickr.push.getTopicsnone
flickr.push.subscriberead 👀topic, callback, verify
flickr.push.unsubscriberead 👀topic, callback, verify
flickr.reflection.getMethodInfononemethod_name
flickr.reflection.getMethodsnone
flickr.stats.getCSVFilesread 👀
flickr.stats.getCollectionDomainsread 👀date
flickr.stats.getCollectionReferrersread 👀date, domain
flickr.stats.getCollectionStatsread 👀date, collection_id
flickr.stats.getPhotoDomainsread 👀date
flickr.stats.getPhotoReferrersread 👀date, domain
flickr.stats.getPhotoStatsread 👀date, photo_id
flickr.stats.getPhotosetDomainsread 👀date
flickr.stats.getPhotosetReferrersread 👀date, domain
flickr.stats.getPhotosetStatsread 👀date, photoset_id
flickr.stats.getPhotostreamDomainsread 👀date
flickr.stats.getPhotostreamReferrersread 👀date, domain
flickr.stats.getPhotostreamStatsread 👀date
flickr.stats.getPopularPhotosread 👀
flickr.stats.getTotalViewsread 👀
flickr.tags.getClusterPhotosnonetag, cluster_id
flickr.tags.getClustersnonetag
flickr.tags.getHotListnone
flickr.tags.getListPhotononephoto_id
flickr.tags.getListUsernone
flickr.tags.getListUserPopularnone
flickr.tags.getListUserRawnone
flickr.tags.getMostFrequentlyUsedread 👀
flickr.tags.getRelatednonetag
flickr.test.echonone
flickr.test.loginread 👀
flickr.test.nullread 👀
flickr.testimonials.addTestimonialwrite ✏️user_id, testimonial_text
flickr.testimonials.approveTestimonialwrite ✏️testimonial_id
flickr.testimonials.deleteTestimonialwrite ✏️testimonial_id
flickr.testimonials.editTestimonialwrite ✏️user_id, testimonial_id, testimonial_text
flickr.testimonials.getAllTestimonialsAboutread 👀
flickr.testimonials.getAllTestimonialsAboutByread 👀user_id
flickr.testimonials.getAllTestimonialsByread 👀
flickr.testimonials.getPendingTestimonialsAboutread 👀
flickr.testimonials.getPendingTestimonialsAboutByread 👀user_id
flickr.testimonials.getPendingTestimonialsByread 👀
flickr.testimonials.getTestimonialsAboutnoneuser_id
flickr.testimonials.getTestimonialsAboutByread 👀user_id
flickr.testimonials.getTestimonialsBynoneuser_id
flickr.urls.getGroupnonegroup_id
flickr.urls.getUserPhotosnone
flickr.urls.getUserProfilenone
flickr.urls.lookupGallerynoneurl
flickr.urls.lookupGroupnoneurl
flickr.urls.lookupUsernoneurl

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.

ParamTypeDescription
authfunction | StringAn 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.

ParamTypeDescription
consumerKeyStringThe application's API key
consumerSecretStringThe 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

ParamTypeDescription
oauthCallbackStringYour 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

ParamTypeDefaultDescription
requestTokenStringThe OAuth request token
[perms]StringreadPermission 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

ParamTypeDescription
oauthTokenStringThe OAuth token to verify
oauthVerifierStringThe OAuth token verifier string you received from the callback
tokenSecretStringThe 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

ParamTypeDescription
oauthTokenStringThe OAuth token
oauthTokenSecretStringThe 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

ParamTypeDescription
consumerKeyStringThe application's API key
consumerSecretStringThe application's API secret
oauthTokenStringThe OAuth token
oauthTokenSecretStringThe 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.

ParamType
authfunction
fileString | 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.

ParamTypeDescription
authfunction
photoIDNumber | StringThe ID of the photo to replace
fileString | 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.

ParamTypeDefaultDescription
[args]ObjectArguments that will be passed along with every feed request
[args.format]StringjsonThe feed response format
[args.lang]Stringen-usThe 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/

ParamType
[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/

ParamTypeDescription
argsObject
args.user_idNumber | StringThe 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/

ParamTypeDescription
argsObject
args.idNumber | StringA 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/

ParamTypeDescription
argsObject
args.idNumberThe 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/

ParamTypeDescription
argsObject
args.idNumberThe 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/

ParamType
[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/

ParamTypeDescription
argsObject
args.user_idNumber | StringThe 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/

ParamTypeDescription
argsObject
args.user_idNumber | StringThe user ID to fetch recent comments for.

License

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

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Tutorials

No tutorials found
Add a tutorial