InstagramJS

Javascript wrapper around Instagram API

Features

• Promise based
• No browser support (sorry, can't get excited about JSONP)
• Tested on NodeJS 6, 7, 8

Install

npm i instagramjs

Usage

All requests are made using an access token. See Authentication for a step-by-step guide on how to obtain a token.

const Instagram = require('instagramjs')
const access = new Instagram('access_token')

Note: to quickly get a token for testing purposes, check out our InstAuth tool.

Global config

Below are defaults:

const access = new Instagram('access_token', {
  baseURL: 'https://api.instagram.com/v1',
  fullResponse: false, // true -> include status code & headers
  timeout: 0 // request timeout in ms
})

Scenarios

User

access.user('self').get()
  .then(console.log) // GET /users/self
 
access.user('id').get()
  .then(console.log) // GET /users/id
 
access.user('id').media().get()
  .then(console.log) // GET /users/id/media/recent (recent is by default)
 
access.user('self').media('liked').get({count: 20})
  .then(console.log) // GET /users/self/media/liked?count=20
 
access.user().search({q: 'foo'})
  .then(console.log) // GET /users/search?q=foo

User Relationship

access.user('self').follows().get()
  .then(console.log) // GET /users/self/follows
 
access.user('self').followedBy().get()
  .then(console.log) // GET /users/self/followed-by
 
access.user('self').requestedBy().get()
  .then(console.log) // GET /users/self/requested-by
 
access.user('id').relationship().get()
  .then(console.log) // GET /users/id/relationship
 
access.user('id').relationship().post({action: 'unfollow'})
  .then(console.log) // POST /users/id/relationship?action=unfollow

Media

access.media('id').get()
  .then(console.log) // GET /media/id
 
access.media().shortcode('abc').get()
  .then(console.log) // GET /media/shortcode/abc
 
access.media().search({distance: 1000, lat: 10, lng: 20})
  .then(console.log) // GET /media/search?distance=1000&lat=10&lng=20

Media Comments

access.media('id').comment().get()
  .then(console.log) // GET /media/id/comments
 
access.media('id').comment('cid').delete().then(() => {
  console.log('deleted')
}) // DELETE /media/id/comments/cid

Media Likes

access.media('id').like().get()
  .then(console.log) // GET /media/id/likes
 
access.media('id').like().post().then(() => {
  console.log('liked')
}) // POST /media/id/likes
 
access.media('id').like().delete().then(() => {
  console.log('deleted')
}) // DELETE /media/id/likes

Tags

access.tag('name').get()
  .then(console.log) // GET /tags/name
 
access.tag('name').media().get()
  .then(console.log) // GET /tags/name/media/recent (recent is by default)
 
access.tag().search({q: 'foo'})
  .then(console.log) // GET /tags/search?q=foo

Locations

access.location('id').get()
  .then(console.log) // GET /locations/id
 
access.location('id').media().get()
  .then(console.log) // GET /locations/id/media/recent (recent is by default)
 
access.location().search({distance: 100, lat: 5, lng: 10})
  .then(console.log) // GET /locations/search?distance=100&lat=5&lng=10

Request Options

As you might've noticed in the exaples, it's possible to specify query params in the request options, e. g.:

access.user('self').media('liked').get({count: 20}) // ?count=20

Additionaly, a full response option could be enabled for a single request:

access.user('self').get(true).then(console.log)
 
// Returns full response
{
  status: 200,
  headers: { ... },
  data: { ... }
}

If you need to specify request timeout:

access.user('self').get(100) // request timeout 100ms

And, finally, combination of above:

access.user('self').get({foo: 'bar'}, true, 100)

Custom Request

If some of the endpoints are not available via Resource interface, it's always possible to build a custom request:

access.request({
  url: '/my/url',
  method: 'get',
  params: {
    foo: 'bar'
  },
  fullResponse: false,
  timeout: 0
}).then(console.log)