instagramAPI
NodeJS driver for the Instagram API.
Installation
npm install instagramapi
How it works
- First of all, you need to authentify. You can use
client_id/client_secret
from the app you are building, or anaccess_token
from a user that use your app. - Some features need an access_token to work
var ig = ; // Every call to `ig.use()` overrides the `client_id/client_secret`// or `access_token` previously entered if they exist.ig;ig;
- If you activated "Signed Requests", you need to sign requests that need the write access (relationship, likes, comments, ...) with:
app;
Server-Side Authentication using OAuth and the Instagram API
Instagram uses the standard oauth authentication flow in order to allow apps to act on
a user's behalf. Therefore, the API provides two convenience methods to help
you authenticate your users. The first, get_authorization_url
, can be used
to redirect an unauthenticated user to the instagram login screen based on a
redirect_uri
string and an optional options
object containing
an optional scope
array and an optional state
string. The
second method, authorize_user
, can be used to retrieve and set an access token
for a user, allowing your app to act fully on his/her behalf. This method takes
three parameters: a response_code
which is sent as a GET parameter once a
user has authorized your app and instagram has redirected them back to your
authorization redirect URI, a redirect_uri
which is the same one
supplied to get_authorization_url
, and a callback that takes
two parameters err
and result
. err
will be populated if and
only if the request to authenticate the user has failed for some reason.
Otherwise, it will be null
and response
will be populated with a
JSON object representing Instagram's confirmation reponse that the user is
indeed authorized. See instagram's authentication
documentation for more information.
Below is an example of how one might authenticate a user within an ExpressJS app.
var http = ;var express = ;var api = ;var app = ; app; api; var redirect_uri = 'http://yoursite.com/handleauth'; exports { res;}; exports { api;}; // This is where you would initially send users to authorizeapp;// This is your redirect URIapp; http;
Using the API
Once you've setup the API and/or authenticated, here is the full list of what you can do:
/********************************//* USERS *//********************************/ig; /* OPTIONS: { [count], [min_id], [max_id] }; */ig; /* OPTIONS: { [count], [min_timestamp], [max_timestamp], [min_id], [max_id] }; */ig; /* OPTIONS: { [count], [min_timestamp], [max_timestamp], [min_id], [max_id] }; */ig; /* OPTIONS: { [count], [max_like_id] }; */ig; /* OPTIONS: { [count] }; */ig; /********************************//* RELATIONSHIP *//********************************//* OPTIONS: { [count], [cursor] }; */ig; /* OPTIONS: { [count], [cursor] }; */ig; ig; ig; ig; /********************************//* MEDIAS *//********************************/igmedia'media_id' {}; /* OPTIONS: { [min_timestamp], [max_timestamp], [distance] }; */ig; ig; /********************************//* COMMENTS *//********************************/ig; ig; ig; /********************************//* LIKES *//********************************/ig; ig; ig; /********************************//* TAGS *//********************************/ig; /* OPTIONS: { [min_tag_id], [max_tag_id] }; */ig; ig; /********************************//* LOCATIONS *//********************************/iglocation'location_id' {}; /* OPTIONS: { [min_id], [max_id], [min_timestamp], [max_timestamp] }; */ig; /* SPECS: { lat, lng, [foursquare_v2_id], [foursquare_id] }; *//* OPTIONS: { [distance] }; */ig; /********************************//* GEOGRAPHIES *//********************************//* OPTIONS: { [min_id], [count] } */ig; /********************************//* SUBSCRIPTIONS *//********************************/ig; ig /* OPTIONS: { [verify_token] } */ig; /* OPTIONS: { [verify_token] } */ig; /* OPTIONS: { [verify_token] } */ig; /* OPTIONS: { [verify_token] } */ig;
Subscriptions
Subscriptions are callbacks from Instagram to your app when new things happen. They should be web-accessable, and return req.query['hub.challenge']
on GET. Read more here. After you subscribe, Instagram will calllback your web URL whenever a new post, user action, etc happens.
You can get your subscriptions with this:
ig;
You can delete all your subscriptions with this:
ig;
or just one with this:
ig;
Errors
When errors occur, you receive an error object with default properties, but we also add some other things:
// Available when the error comes from Instagram API
err.code; // code from Instagram
err.error_type; // error type from Instagram
err.error_message; // error message from Instagram
// If the error occurs while requesting the API
err.status_code; // the response status code
err.body; // the received body
and
err.retry(); // Lets you retry in the same conditions that before
Pagination
When you use functions like user_media_recent
or tag_media_recent
, you will get a pagination
object in your callback. This object
is basically the same that Instagram would give you but there will be a next()
function that let you retrieve next results without caring about anything.
var ig = ; var { // Your implementation here ifpaginationnext paginationnexthdl; // Will get second page results }; ig;
Tests
Put the following in your environment:
export INSTAGRAM_ACCESS_TOKEN=YOUACCESSTOKEN
Then just use
make test
More infos
- You can find more informations on the Instagram developer website.
- If you have any questions or remark, feel free to contact us at
hello@totems.co
License
Distributed under the MIT License.