Getting Started With the Instagram API: Media Endpoints

Final product image
What You'll Be Creating

This is part two of a series on the Instagram API. In this tutorial, I'll guide you through using Instagram's Media Endpoints, which allow you to search for popular images from a specific time and place. 

You can download code for each episode by using the GitHub repository link in the sidebar. You may also be interested in my two-part Tuts+ series, Locating Potential Crime Scene Witnesses With Social Media APIs

The code for these tutorials is written in PHP using the Yii Framework. You can learn more about Yii in Introduction to the Yii Framework (Tuts+) and in the Programming With Yii2 Series (Tuts+). You can also easily adapt the code segments for your own PHP application.

I do participate in the discussions. 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.

Let's begin by registering as a developer with Instagram.

Getting Started

To get started, visit the Instagram API page for developers and click Register Your Application:

Instagram Hello Developers

You'll need to sign up for a developer account:

Instagram Developer Signup

Then you can register a new application to receive your Client ID:

Instagram New Client Registration

On the Manage Clients dashboard, you'll see your Client ID and Client Secret, so make note of these:

Instagram Manage Clients

Using the Media Endpoints

As web service APIs go, the Instagram API is robust, and in my experience works very well. Instagram offers a handful of API endpoints:

Instagram API Documentation Overview and Endpoints

For this tutorial, we'll focus on the Media endpoints:

Instagram API Media Endpoints

With Media endpoints, you can retrieve information about an Instagram photo or video by referencing its ID or the shortcode from its URL, e.g. 0EyZ53Ja9X from 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. And finally, it allows you to retrieve popular, trending Instagram posts.

The API Console

To help you get started and debug, Instagram has an API console powered by Apigee:

Instagram API Console powered by Apigee

You can try out queries against the Media endpoints using the API console. Here's an example result for media/popular:

Obviously, you can see how useful this is for working with media from the popular mobile photography service.

Let's move on to installing our sample codebase and configuring it to work with your Instagram client application.

Installing the Codebase

For this series, I'm going to continue to build on the Eyewitness codebase from Locating Potential Crime Scene Witnesses With Social Media APIs. You can clone the GitHub repository located in the sidebar to run our sample code.

You'll need to configure your local Apache configuration. I use MAMP, so it looks something like this:

You need to create a database locally. I use PHPMyAdmin to create one graphically:

Create your Eyewitness database

Then I create an initialization file in /var/secure/eyew.ini with my database credentials and Instagram IDs and keys. I described this process recently in another Tuts+ tutorial: Protecting Your Keys From GitHub.

My ini file looks like this:

Update your Composer and its vendor libraries:

Then initialize our database. The first migration installs user tables for our Yii2-User by developer Dmeroff extension, and the second creates our app-specific tables:

Again, you can learn more about setting up a Yii Framework application in my Programming With Yii2 series for Tuts+.

Here's the MySQL schema for our Instagram image table—we call it the Gram table. We'll use it to store geosearch results.

The Home Page

I've renamed the sample application "Instapi", short for Instagram API.

Here's a look at what you should see when you visit the site in your browser:

Instagram API Sample Code Home Page

Performing Media Searches

To implement media searches in our Instapi application, I'm using Galen Grover's Instagram PHP package.

Search Popular Images

First, let's implement a search for media/popular. We'll query the API and display the results in a table.

I've created an action called popular in GramController.php:

It calls searchPopular() in the Gram.php model:

In /views/gram/popular.php, we set up an HTML table structure:

and include the _item.php partial view to display individual media results:

Here are the results of Instagram media popular queries. Go ahead and refresh the page in your app. It's fun to see what comes up next.

Instagram Media Popular Results Table

Look Up Information About an Image or Video

I've linked the Instagram media ID in the first column to a controller action that calls the media endpoint which gets us more information:

Here's the lookup function in the Instagram model:

Here's a screenshot of the data dumped to the screen:

Instagram API Media Information Dumped to Screen

Obviously, you could use and store this information however you would like.

Search for Media From a Time and Place

Now, let's search for images from a specific time and place. For this example, I'll review our Eyewitness example.

Our codebase allows you to define a moment as a place and time. It consists of a friendly descriptor, a location (latitude and longitude), a start time and a duration (in minutes). For my first example, I'm looking for Instagram users who were present at Macklemore's video shooting on the evening of Wednesday, July 24, 2013 at Seattle's landmark Dick's Drive In.

Using Google Maps, I can get the GPS latitude and longitude for Dick's. It's 47.6195 -122.321. 

Dicks Drive In Broadway Seattle GPS in Google Maps

From the article, I learned that the production shut down at 1 am. I'm going to choose a start time of 10 pm and a duration of 3 hours.

Create a Moment

Instagram accepts start times in GMT so I've hardcoded an eight-hour time change adjustment from my timezone (PST). You may need to change this in the code.

To search Instagram, just click on the camera icon below:

The Moments Index Grid

The actual search is fairly straightforward: $instagram->searchMedia( $this->latitude, $this->longitude,$params ); 

The results are stored in the Gram table, which we can then browse:

Here's the first page of results from my search. You can see the crowds and Macklemore's Cadillac limo driving up.

Macklemore Search Results

Then on page three, an Instagram user named Joshua Lewis has a shot of Macklemore exiting the Cadillac: 

More Macklemore Search Results

Here's Macklemore:

Macklemore Arrives on Instagram

This example clearly shows the power that the Instagram search API provides. In just a few moments, we found a variety of eyewitnesses to an event from the summer of 2013.

What's Next?

I hope you've enjoyed learning about the Instagram API thus far. In the next episode, we'll explore OAuth authentication so that we can query areas of the Instagram service that require user authorization.

In the meantime, 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. 

Related Links

The preview image is modified from a result that came up in our API search. 



Related Articles