instagram-api

NodeJS Library for Instagram.

Installation

npm install instagram-api

Setting up a connection

var accessToken = '23612221.3fcb46b.348431486f3a4fb85081d5242db9ca1c';
var InstagramAPI = require('instagram-api');
var instagramAPI = new InstagramAPI(accessToken);

Promises

This package uses promises to control async control-flow. If you are unfamiliar with how promises work, now might be a good time to brush up on them, here and here

Basically a promise represents a value which will be present at some point - "I promise you I will give you a result or an error at some point". This means that

// DON'T DO THIS
user = instagramAPI.userSelf()
console.log(user);

will never work! This is because user is a promise object, not a data from Instagram. The right way to do it is:

instagramAPI.userSelf().then(function(result) {
    console.log(result.data); // user info
    console.log(result.limit); // api limit
    console.log(result.remaining) // api request remaining
}, function(err){
	console.log(err); // error info
});

API Methods

userSelf([requestOptions])

Get information about the owner of the access_token.

Permission Requirements: basic

user(userId[, requestOptions])

Get information about a user. This endpoint requires the public_content scope if the user-id is not the owner of the access_token.

Permission Requirements: public_content

userSelfMedia(params[, requestOptions])

Get the most recent media published by the owner of the access_token.

Permission Requirements: basic

userMedia(userId, options[, requestOptions])

Get the most recent media published by a user. This endpoint requires the public_content scope if the user-id is not the owner of the access_token.

Permission Requirements: public_content

userSelfMediaLiked(options[, requestOptions])

Get the list of recent media liked by the owner of the access_token.

Permission Requirements: public_content

userSearch(term, options[, requestOptions])

Get a list of users matching the query.

Permission Requirements: public_content

userSelfFollows(options[, requestOptions])

Get the list of users this user follows.

Permission Requirements: follower_list

userSelfFollowedBy(options[, requestOptions])

Get the list of users this user is followed by.

Permission Requirements: follower_list

userSelfRequestedBy([requestOptions])

List the users who have requested this user's permission to follow.

Permission Requirements: follower_list

userRelationship(userId[, requestOptions])

Get information about a relationship to another user. Relationships are expressed using the following terms in the response:

• outgoing_status: Your relationship to the user. Can be 'follows', 'requested', 'none'.
• incoming_status: A user's relationship to you. Can be 'followed_by', 'requested_by', 'blocked_by_you', 'none'.

Permission Requirements: follower_list

setUserRelationship(userId, action[, requestOptions])

Modify the relationship between the current user and the target user. You need to include an action parameter to specify the relationship action you want to perform. Valid actions are: 'follow', 'unfollow' 'approve' or 'ignore'. Relationships are expressed using the following terms in the response:

• outgoing_status: Your relationship to the user. Can be 'follows', 'requested', 'none'.
• incoming_status: A user's relationship to you. Can be 'followed_by', 'requested_by', 'blocked_by_you', 'none'.

Permission Requirements: relationships

media(mediaId[, requestOptions])

Get information about a media object. Use the type field to differentiate between image and video media in the response. You will also receive the user_has_liked field which tells you whether the owner of the access_token has liked this media. The public_content permission scope is required to get a media that does not belong to the owner of the access_token.

Permission Requirements: basic, public_content

mediaByShortcode(shortcode[, requestOptions])

This endpoint returns the same response as GET /media/media-id. A media object's shortcode can be found in its shortlink URL. An example shortlink is http://instagram.com/p/tsxp1hhQTG/. Its corresponding shortcode is tsxp1hhQTG.

Permission Requirements: basic, public_content

mediaSearch(params[, requestOptions])

Search for recent media in a given area.

Permission Requirements: public_content

mediaComments(mediaId[, requestOptions])

Get a list of recent comments on a media object. The public_content permission scope is required to get comments for a media that does not belong to the owner of the access_token.

Permission Requirements: basic, public_content

postMediaComment(mediaId, text[, requestOptions])

Create a comment on a media object with the following rules:

• The total length of the comment cannot exceed 300 characters.
• The comment cannot contain more than 4 hashtags.
• The comment cannot contain more than 1 URL.
• The comment cannot consist of all capital letters.

The public_content permission scope is required to create comments on a media that does not belong to the owner of the access_token.

Permission Requirements: comments

removeMediaComment(mediaId, commentId[, requestOptions])

Remove a comment either on the authenticated user's media object or authored by the authenticated user.

Permission Requirements: comments

mediaLikes(mediaId[, requestOptions])

Get a list of users who have liked this media.

Permission Requirements: basic, public_content

postMediaLike(mediaId[, requestOptions])

Set a like on this media by the currently authenticated user. The public_content permission scope is required to create likes on a media that does not belong to the owner of the access_token.

Permission Requirements: likes

removeMediaLike(mediaId[, requestOptions])

Remove a like on this media by the currently authenticated user. The public_content permission scope is required to delete likes on a media that does not belong to the owner of the access_token.

Permission Requirements: likes

getTag(tagName[, requestOptions])

Get information about a tag object.

Permission Requirements: public_content

getMediasByTag(tagName, params[, requestOptions])

Get a list of recently tagged media.

Permission Requirements: public_content

searchTags(tagName[, requestOptions])

Search for tags by name.

Permission Requirements: public_content

getLocation(locationId[, requestOptions])

Get information about a location.

Permission Requirements: public_content

getMediasByLocation(locationId, params[, requestOptions])

Get a list of recent media objects from a given location.

Permission Requirements: public_content

searchLocations(params[, requestOptions])

Search for a location by geographic coordinate.

Permission Requirements: public_content

Details

• requestOptions parameter is optional and almost ever should be ignored.

Changelog

• Version 1.0.3 - 14/10/2016
  • Small fixes
• Version 1.0.2 - 27/05/2016
  • Pagination fix
  • Documentation enhacement
• Version 1.0.1 - 18/05/2016
  • Adding docs in README
• Version 1.0.0 - 17/05/2016
  • Library working.

License

MIT.