This is the first tutorial of a series focusing (no pun intended) on the Instagram API. Instagram is the mobile social photography service founded in 2010 and acquired by Facebook for $1 billion in 2012. That's how you build a startup!
According to Pew Research, 26% of all online adults use Instagram. Additionally, "roughly half of internet-using young adults ages 18-29 (53%) use Instagram. And half of all users (49%) use the site daily."
The popularity, ubiquity and visual beauty of Instagram make it a compelling and fun API for developers to explore. I've written more than 90 tutorials for Tuts+ and by far one of the most interesting was the Instagram part of my earlier two-part series, Locating Potential Crime Scene Witnesses With Social Media APIs. In that tutorial, we found eyewitnesses to a Macklemore video shoot more than two years earlier:
In this tutorial, I'll give you a broad overview of what you can do with the Instagram API and how to get started. In future episodes, I'll walk you through a variety of useful scenarios that leverage the API. In each episode, I'll provide a code repository with sample code in my favorite PHP framework, Yii. You can learn more about Yii here and in my Programming With Yii2 Series (Tuts+).
I do participate in the discussions below. If you have a question or topic suggestion, please post a comment below. You can also reach me on Twitter @reifman or email me directly.
What Can You Do With the Instagram API?
In addition to finding eyewitnesses, there are a myriad of other things you can do with Instagram's versatile and powerful API. Check out Mashable's 8 Ways to Use Instagram's API. They also link to some interesting third-party services already using the API:
- Instaprint provides an Instagram-connected photo printer for your events.
- Eventstagram provides public display and sharing of Instagram media at your events.
- Casetify lets you print custom device covers from your Instagram account.
As web service APIs go, the Instagram API is robust, and in my experience works very well (better than Twitter's). I'll begin by providing a broad overview of the API before going deeper.
Let's review the endpoints.
The Endpoints
Instagram's endpoints represent a variety of REST-based web service URLs for accessing much of Instagram's overall functionality.
Users
The Users endpoint allows you search for users by name, look up basic information about them, and see the media in their newsfeed (people they follow on Instagram) as well as their own media posts and liked media. Some of these features require the user's specific authentication and others can be used by any developer.
Relationships
The Relationships endpoint allows you to retrieve follower lists (both who a user follows and who they're followed by) as well as respond to relationship requests and make changes to relationships.
Media
With the Media endpoint, you can retrieve information about an Instagram photo or video. It also provides geosearch capabilities to find media posted from a specific time and place, as we did in Locating Potential Crime Scene Witnesses With Social Media APIs. It also allows you to retrieve popular Instagram posts.
Here's an excerpt of JSON code for an example response to https://api.instagram.com/v1/media/popular?access_token=ACCESS-TOKEN:
{
"data": [{
"type": "image",
"users_in_photo": [],
"filter": "Gotham",
"tags": [],
"comments": { ... },
"caption": {
"created_time": "1296656006",
"text": "ãã¼ãâ¥ã¢ããªå§ãã¦ä½¿ã£ã¦ã¿ãã(^^)",
"from": {
"username": "cocomiin",
"full_name": "",
"type": "user",
"id": "1127272"
},
"id": "26329105"
},
"likes": {
"count": 35,
"data": [{
"username": "mikeyk",
"full_name": "Kevin S",
"id": "4",
"profile_picture": "..."
}, {...subset of likers...}]
},
"link": "http://instagr.am/p/BV5v_/",
"user": {
"username": "cocomiin",
"full_name": "Cocomiin",
"profile_picture": "http://distillery.s3.amazonaws.com/profiles/profile_1127272_75sq_1296145633.jpg",
"id": "1127272"
},
"created_time": "1296655883",
"images": {
"low_resolution": {
"url": "http://distillery.s3.amazonaws.com/media/2011/02/01/34d027f155204a1f98dde38649a752ad_6.jpg",
"width": 306,
"height": 306
},
"thumbnail": {
"url": "http://distillery.s3.amazonaws.com/media/2011/02/01/34d027f155204a1f98dde38649a752ad_5.jpg",
"width": 150,
"height": 150
},
"standard_resolution": {
"url": "http://distillery.s3.amazonaws.com/media/2011/02/01/34d027f155204a1f98dde38649a752ad_7.jpg",
"width": 612,
"height": 612
}
},
"id": "22518783",
"location": null
},
Comments, Likes and Tags
As you'd expect, the Comments, Likes and Tags endpoints let you enumerate comments, likes and tags for media items as well as applying (or unapplying) these to media.
For example, here's a sample response to querying for media tagged "snow" using the endpoint https://api.instagram.com/v1/tags/snow/media/recent?access_token=ACCESS-TOKEN:
{
"data": [{
"type": "image",
"users_in_photo": [],
"filter": "Earlybird",
"tags": ["snow"],
"comments": {
"data": [{
"created_time": "1296703540",
"text": "Snow",
"from": {
"username": "emohatch",
"username": "Dave",
"id": "1242695"
},
"id": "26589964"
},
{
"created_time": "1296707889",
"text": "#snow",
"from": {
"username": "emohatch",
"username": "Emo Hatch",
"id": "1242695"
},
"id": "26609649"
}],
"count": 3
}
"caption": {
"created_time": "1296703540",
"text": "#Snow",
"from": {
"username": "emohatch",
"id": "1242695"
},
"id": "26589964"
},
"likes": {
"count": 1,
"data": [{
"username": "mikeyk",
"full_name": "Mike Krieger",
"id": "4",
"profile_picture": "http://distillery.s3.amazonaws.com/profiles/profile_1242695_75sq_1293915800.jpg"
}]
},
"link": "http://instagr.am/p/BWl6P/",
"user": {
"username": "emohatch",
"profile_picture": "http://distillery.s3.amazonaws.com/profiles/profile_1242695_75sq_1293915800.jpg",
"id": "1242695",
"full_name": "Dave"
},
"created_time": "1296703536",
"images": {
"low_resolution": {
"url": "http://distillery.s3.amazonaws.com/media/2011/02/02/f9443f3443484c40b4792fa7c76214d5_6.jpg",
"width": 306,
"height": 306
},
"thumbnail": {
"url": "http://distillery.s3.amazonaws.com/media/2011/02/02/f9443f3443484c40b4792fa7c76214d5_5.jpg",
"width": 150,
"height": 150
},
"standard_resolution": {
"url": "http://distillery.s3.amazonaws.com/media/2011/02/02/f9443f3443484c40b4792fa7c76214d5_7.jpg",
"width": 612,
"height": 612
}
},
"id": "22699663",
"location": null
},
{
"type": "video",
"videos": {
"low_resolution": {
"url": "http://distilleryvesper9-13.ak.instagram.com/090d06dad9cd11e2aa0912313817975d_102.mp4",
"width": 480,
"height": 480
},
"standard_resolution": {
"url": "http://distilleryvesper9-13.ak.instagram.com/090d06dad9cd11e2aa0912313817975d_101.mp4",
"width": 640,
"height": 640
},
"users_in_photo": null,
"filter": "Vesper",
"tags": ["snow"],
"comments": {
"data": [{
"created_time": "1279332030",
"text": "Love the sign here",
"from": {
"username": "mikeyk",
"full_name": "Mikey Krieger",
"id": "4",
"profile_picture": "http://distillery.s3.amazonaws.com/profiles/profile_1242695_75sq_1293915800.jpg"
},
"id": "8"
},
{
"created_time": "1279341004",
"text": "Chilako taco",
"from": {
"username": "kevin",
"full_name": "Kevin S",
"id": "3",
"profile_picture": "..."
},
"id": "3"
}],
"count": 2
},
"caption": null,
"likes": {
"count": 1,
"data": [{
"username": "mikeyk",
"full_name": "Mikeyk",
"id": "4",
"profile_picture": "..."
}]
},
"link": "http://instagr.am/p/D/",
"user": {
"username": "kevin",
"full_name": "Kevin S",
"profile_picture": "...",
"id": "3"
},
"created_time": "1279340983",
"images": {
"low_resolution": {
"url": "http://distilleryimage2.ak.instagram.com/11f75f1cd9cc11e2a0fd22000aa8039a_6.jpg",
"width": 306,
"height": 306
},
"thumbnail": {
"url": "http://distilleryimage2.ak.instagram.com/11f75f1cd9cc11e2a0fd22000aa8039a_5.jpg",
"width": 150,
"height": 150
},
"standard_resolution": {
"url": "http://distilleryimage2.ak.instagram.com/11f75f1cd9cc11e2a0fd22000aa8039a_7.jpg",
"width": 612,
"height": 612
}
},
"id": "3",
"location": null
},
...]
}
Locations
Social service APIs such as Twitter and Instagram have their own Place databases. Instagram calls these Locations. The Location endpoints allow you to look up location IDs in the Instagram service by GPS coordinate and find media posted from those location IDs.
Here's an example query for known locations (or places) near the Eiffel Tower's GPS coordinates:
Instagram returns its native location IDs for known places nearby. For example, you could use this with other location queries to find media posts from Restaurant 58 Tour Eiffel.
Authentication
Once you register your developer application, you can make a wide variety of requests using only your access key. However, to secure specific endpoints and provide private user information, Instagram’s API uses the OAuth 2.0 protocol for authentication.
Here's an example use of OAuth from the API console (described further below):
The default OAuth access is for read only, but Instagram allows you to ask the user to add other permissions via these scopes:
-
Comments: to create or delete comments on a user’s behalf (this permission is restricted to approved apps only).
- Relationships: to follow and unfollow users on a user’s behalf.
- Likes: to like and unlike items on a user’s behalf.
You can learn more about the implementation of Instagram's OAuth now, or wait for upcoming episodes of this series.
Real-Time Services
With the Instagram Real-Time API, you can subscribe to events to monitor live activity for users, tags, locations (Instagram's native place IDs) and GPS areas:
- Users: receive notifications when users who have registered with your application post new photos. This requires authentication with your application.
- Tags: receive notifications when a new photo is tagged with tags of your choosing.
- Locations: receive notifications when new photos are posted and tagged with a specific location (place ID).
- Geographies: receive notifications when new photos are posted in an arbitrary geographical location as defined by a center point and radius.
For real-time access, Instagram suggests using Python-based Tornado or Node.js. There are probably also lessons you can learn from Phirehose, the real-time Twitter framework built in PHP.
For real-time updates, you register a callback endpoint of your own, e.g. a URL. Here's a sample post of subscription updates from Instagram to a callback endpoint:
[
{
"subscription_id": "1",
"object": "user",
"object_id": "1234",
"changed_aspect": "media",
"time": 1297286541
},
{
"subscription_id": "2",
"object": "tag",
"object_id": "nofilter",
"changed_aspect": "media",
"time": 1297286541
},
...
]
The first is a new media post by a user feed you subscribed to. The second is a new media post to a tag subscription.
The API Console
To help you get started and debug, Instagram has an API console powered by Apigee:
You can also share and embed the results:
Reporting Bugs
Once you've registered as a developer, you can easily report API issues to the Instagram team:
What Platforms Does the Instagram API Support?
You can access the Instagram API with any platform using its REST endpoints. Instagram provides libraries for Python and Ruby. Packagist offers a number of community libraries for Instagram for PHP. IBM also has a guide to using vanilla PHP with Instagram.
Rules of the Road
Terms of Use
Instagram users maintain ownership of their photos and videos. Because copyright is so essential to copyright, Instagram says, "It's your responsibility to make sure that you respect that right."
You're also not allowed to replicate the Instagram application experience. Innovate instead.
Before you start using the API, we have a few guidelines that we'd like to tell you about. You can read the full API Terms of Use here.
Rate Limits
As with any web services API, there are rate limits that you must adhere to or be blocked. For example, applications are restricted to 5,000 calls per hour.
What's Next?
I hope you're intrigued to begin using the Instagram API. In the next episode, I'll guide you through everything you need to get started making endpoint requests. If you'd like to get started immediately, you can check out Locating Potential Crime Scene Witnesses With Social Media APIs.
Please feel free to post your questions and comments below. You can also reach me on Twitter @reifman or email me directly. You can also browse my Tuts+ instructor page to see other tutorials I've written.
Comments