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()

Get information about the owner of the access_token.

Permission Requirements: basic

user(userId)

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)

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

Permission Requirements: basic

userMedia(userId, options)

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)

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

Permission Requirements: public_content

userSearch(term, options)

Get a list of users matching the query.

Permission Requirements: public_content

userSelfFollows(options)

Get the list of users this user follows.

Permission Requirements: follower_list

userSelfFollowedBy(options)

Get the list of users this user is followed by.

Permission Requirements: follower_list

userSelfRequestedBy()

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

Permission Requirements: follower_list

userRelationship(userId)

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)

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)

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)

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)

Search for recent media in a given area.

Permission Requirements: public_content

mediaComments(mediaId)

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)

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)

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

Permission Requirements: comments

mediaLikes(mediaId)

Get a list of users who have liked this media.

Permission Requirements: basic, public_content

postMediaLike(mediaId)

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)

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)

Get information about a tag object.

Permission Requirements: public_content

getMediasByTag(tagName, params)

Get a list of recently tagged media.

Permission Requirements: public_content

searchTags(tagName)

Search for tags by name.

Permission Requirements: public_content

getLocation(locationId)

Get information about a location.

Permission Requirements: public_content

getMediasByLocation(locationId, params)

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

Permission Requirements: public_content

searchLocations(params)

Search for a location by geographic coordinate.

Permission Requirements: public_content

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.