Instagram APi Using Raspberry Pi

Mmmm brunch, my favourite meal of the day (after breakfast, dinner, lunch, tea, high tea, elevensies and supper).

But why a picture of brunch on a serious tech blog like this?  It would seem that the young people these days all seem to like Instagram.  Never one to not follow fashion I thought I'd get into Instagram Geek Dad style!  That means learning how to use the Instagram API on my Raspberry Pi and getting access to pictures of brunch from my account.

There's good documentation online, but here's my step-by-step guide on how to do it. Remember this post is for Geek Dads like me,not IT professionals so please don't scorn me if you think this is easy meat.

Step 1 - Sign up and Register an Application
Using the Instagram API relies on OAUTH2.0, much like the Fitbit API that I blogged about here.

Step 1 is about logging on, registering your app and getting secret data for your application.

Go to instagram developer site at https://www.instagram.com/developer/ and log in using your Instagram account credentials, (i.e. those which you get when you sign up as a normal, non-Geek user).  You'll need to provide extra details like why you want to get access to the API.  I put something along the lines of "to test what the API can do with my Raspberry Pi".  I'm sure you can put whatever you like here (within reason).

Select the "Manage Clients" button (top right of the screen) and add details for your specific test client.  I just used this blogs address for the various URL fields requested and my Gmail address for the Support email address.  You'll be given a client ID and a client secret that you need to log these for the next steps.

Step 2 - Get the User (You) to Authorise Your Test App
For the next step you need to get the user (you in this case) to authorise you accessing their account with your app.  To do this you simply point a browser at an address like the one below:

https://api.instagram.com/oauth/authorize/?client_id=<YourIDHere>&redirect_uri=http://pdwhomeautomation.blogspot.com&response_type=code&scope=basic+public_content+follower_list+comments+relationships+likes

Here the client ID is the one you get when you registered your app and the scope parameters at the end are described here.  I basically requested all possible scope items for my app.

You may have to login with your Instagram credentials if not already logged in and you will have to click a button marked "Authorise".  This effectively links your Instagram account to the developer application you created.

The browser session will be redirected to the URL you specified as your "Redirect URI" when you signed up and the last segment of the URL is the "code" you use for step 3.  Log this!!

Step 3 - Get an Access Token
Like all OAUTH2.0 implementations I've seen you use an access token to authorise your API requests.  However the token seems to be long lived, there's no periodic requesting of a new access token using a refresh token.  (However Instagram warn you may need to request a new access token at some point).

To get the access token you need to make a HTTP POST request using a bunch of parameters in the message body.  Instagram helpfully gives you the structure of a cURL command you can run on your Raspberry Pi.  Here it is:

curl -F 'client_id=CLIENT_ID' \ -F 'client_secret=CLIENT_SECRET' \ -F 'grant_type=authorization_code' \ -F 'redirect_uri=AUTHORIZATION_REDIRECT_URI' \ -F 'code=CODE' \ https://api.instagram.com/oauth/access_token

Simply replace the parameters in the above command with the ones you've collected through this process.

The response to this cURL command will be something like this (details changed of course):
{"access_token":"3911234.abcder.;dfjlkpaefjpfj;ldfjljdfljdff","user":{"username":"MyUserName","bio":"A geek, UK\udfdfdfd\dfdff\rrr\34546\454534545\fdfhh I love my girls\u\dfdfdf\ererr\webgh\jjkgkt","website":"http:\/\/pdwhomeautomation.blogspot.co.uk","profile_picture":"https:\/\/scontent.cdninstagram.com\/t51.2885-9\/10570229_699866173_1234567_a.jpg","full_name":"The Geek Dad (Geeky Man)","id":"678765"}}

So with the access token at the start of the JSON response, here's a few things you can do on the API.

Using the API
The key thing that Instagram warn is that your app starts in "Sandbox Mode" meaning restricted access to the API in terms of API calls, number of users etc.  You would then need to register your app for it to be promoted to use the full API.  Not required for someone who just wants to play.

The API has a set of endpoints that I'll describe with a few examples below.  The documentation on the Instagram developer site here is pretty good.

In the examples below, replace <YourAccessToken> with the one you got from the OAUTH2.0 request above.

Get information about yourself as a user:

https://api.instagram.com/v1/users/self?access_token=<YourAccessToken>

This provides the same JSON response as when you requested the access token (step 3 above).

You can also see recent media for you as a user by doing:

https://api.instagram.com/v1/users/self/media/recent?access_token=<YourAccessToken>

This gives you a whole bunch  of JSON detailing your most recent Instagram posts.  Within this you can see parameters like creation date, location, the filter used, the caption, number of likes etc.  There is also a bunch of URLs for different size versions of the image (low resolution, thumbnail and standard resolution).  Each of these are shown below.

Low:

Thumbnail:

Standard:

Mmmmm, brunch!