flickr-sdk

    3.10.0 • Public • Published

    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.

    Install

    npm i flickr-sdk

    DownloadsWeekly Downloads

    795

    Version

    3.10.0

    License

    MIT

    Unpacked Size

    759 kB

    Total Files

    19

    Last publish

    Collaborators

    • alex-seville
    • jeremyruppel
    • superic
    • pdokas