Instagram Graph API – Part 2: Fetching data with the Insights API

In Part 1 of this min-series I introduced the Instagram Graph API, what is was, and how you could connect to it.

In Part 2 we look at an API that belongs to the Instagram Graph API – the Insights API.  Specifically, we’ll:

• introduce the Insights API
• look at the data you can extract from the Insights API
• connect to the Insights API and extract valuable image related insights
• use Postman to validate we can connect to the Insights API out-with the Facebook domain
• consider some use cases for the Insights API

What exactly is the Insights API?

The Insights API lets you get all insights for individual media objects for a given Instagram account. It features two endpoints

Before you can do this, said account must an Instagram Business Account.  The API features two endpoints:

GET /{ig-media-id}/insights — gets metrics on a media object GET /{ig-user-id}/insights — gets metrics on an Instagram Business Account or Instagram Creator account.

You can use these endpoints to extract a wide range of metrics for all media that belongs to the Instagram Business accounts that you have access to (for more information about configuring access see Part 1 of this mini-series).

What data can you extract with the Insights API?

So, what data can you extract with the Insights API?

A lot!

The following tables details each metric that is available in the Insights API:

Photo & Video Metrics

Metric	Description
engagement	Total number of likes and comments on the media object.
impressions	Total number of times the media object has been seen.
reach	Total number of unique accounts that have seen the media object.
saved	Total number of unique accounts that have saved the media object.
video_views	(Videos only) Total number of times the video has been seen. Returns 0 for videos in carousel albums.

Carousel Album Metrics

Metric	Description
carousel_album_engagement	Total number of likes and comments on the carousel album.
carousel_album_impressions	Total number of times the carousel album has been seen.
carousel_album_reach	Total number of unique accounts that have seen the carousel album.
carousel_album_saved	Total number of unique accounts that have saved the carousel album.

Story Metrics

Metric	Description
exits	Number of times someone exited the story.
impressions	Total number of times the story has been seen.
reach	Total number of unique accounts that have seen the story.
replies	Total number of replies to the story.
taps_forward	Total number of taps to see this story’s next photo or video.

As you can see from the tables above, the Insights API gives you access to valuable metrics such as the total number of likes, comments or even engagement of media that’s being shared by an Instagram account!

Connecting to the Insights API

By now you’ve got overview of what the Insights API is and the data you can expect to extract from it.  Now let’s look at how you can connect to it.  From a process point of view, a good practice before we cut any code is to test the fundamentals.  This will involve:

1. identifying the Facebook Page ID that is connected to your Instagram Business Account that we want to query (we covered this in Part 1)
2. identifying a suitable Instagram Media ID
3. connecting to the Insights API using the Graph API Explorer
4. supplying the media id to the Insights API in the Graph API Explorer
5. verifying that we can get Instagram Media meta data
6. copying the URL we create in the Graph API Explorer and sending this URL using Postman

Using the Graph API Explorer

Please read Part 1 of this tutorial as one of the first things we need to do is identify the Facebook Pages your account as access to.  When you supply this into the Graph Explorer, it will return a list of Pages your account has access to.  You need to take a note of the Page ID and then use this to infer the associated Instagram Business Account.  Again, please read Part 1, it explains all the steps you need to take!

Identifying a suitable Instagram Media ID

By now you’ve identified the Instagram Business Account that’s associated with your Facebook Page.  You can now send requests to the Instagram API!

The first thing we’ll do is identify any media that’s associated with this Instagram Business Account.

To do this you need to send the following query in the Graph Explorer:

https://graph.facebook.com/v3.2/XXX/media?access_token=YYY

Where XXX is the Instagram Business Account ID and YYY is the Access Token you have generated in the Graph API Explorer.

When you send this URL to the Graph API Explorer, it will return the Instagram Media Objects that belong to that user.

You can see this in the screenshot below:

I’m not active on Instagram but have an account for development purposes. If I click on the Media ID (yours will be different), the Graph Explorer will take you to the node:

Extracting Image URL and Number of Comments

Now here is where it gets interesting!

To the left you have the option “Search for a field”.  Enter “media_url” then click Submit. The Graph API will return the URL for the Instagram Media ID Node that we’re currently in:

You can click on this URL; a new tab will open; the image will then be displayed:

For reference, here is the full URL (it’s a test picture I took from an old book I have):

https://scontent.xx.fbcdn.net/v/t51.2885-15/44607845_331662154276372_5860692923554269606_n.jpg?_nc_cat=111&_nc_ht=scontent.xx&oh=14c22e049558c091edcbaaaf94fe4e6b&oe=5D7C0B02

You can add other fields such as “perma_link”, this field will return the link the familiar Instagram Image page:

In this image you can see there is one comment.  You can return the number of comments from the Graph Explorer:

Dive deeper using the Insights API

The values we just extracted sit at the root level for the Media ID in question and you can experiment with other values at your leisure.

You can go deeper with the Insights API endpoint however, for example, you can extract:

• Engagement (Total number of likes and IG Comments on the IG Media object)
• Impressions (Total number of times the IG Media object has been seen)
• Reach (Total number of unique Instagram accounts that have seen the IG Media object)
• and much more….

You can find out more information about what’s exactly available here.

Identifying the Impressions, Engagement and Reach for an Instagram Media Object

For now, we’ll identify the Impressions, Engagement and Reach that a Media Object has received.  You can do this by using the following URL in the Graph API Explorer:

MEDIA_ID/insights?metric=impressions,engagement,reach

The Graph API Explorer will then return something like the following.  The notes and values are self-explanatory:

 

{
  "data": [
    {
      "name": "impressions",
      "period": "lifetime",
      "values": [
        {
          "value": 40
        }
      ],
      "title": "Impressions",
      "description": "Total number of times the media object has been seen",
      "id": "17899859863269349/insights/impressions/lifetime"
    },
    {
      "name": "engagement",
      "period": "lifetime",
      "values": [
        {
          "value": 4
        }
      ],
      "title": "Engagement",
      "description": "Total number of likes and comments on the media object",
      "id": "17899859863269349/insights/engagement/lifetime"
    },
    {
      "name": "reach",
      "period": "lifetime",
      "values": [
        {
          "value": 26
        }
      ],
      "title": "Reach",
      "description": "Total number of unique accounts that have seen the media object",
      "id": "17899859863269349/insights/reach/lifetime"
    }
  ]
}

Connecting to the Insights API using Postman

OK, by now you can connect to Insights API and return some data. It’s good to try and connect from a 3^rd party application like Postman to make sure you can form the request and required parameters outside of the Facebook domain.  It’ll also help rule out any other connectivity issues, prior to writing any code.

This involves a couple of steps which we’ll run through now.

Copy the Request from the Graph API Explorer

The Graph API Explorer has a few options that let you auto-generate code that constructs a value response along with the required parameters.  At the time of writing it supports the following:

• Android SDK
• iOSD SDK
• JavaScript SDK
• PHP SDK
• cURL

To access this, you click on the </> Get Code Button:

You’ll then be presented with a dialogue box, select cURL:

Your only interest in everything between the brackets.  In my case, the full request string consists of the following:

https://graph.facebook.com/v3.2/17899859863269349/insights?metric=impressions%2Cengagement%2Creach&access_token=XXXXXXXXXXX0BAAgSPAn6IpGAh3yPwHHjNsVoYvnTtEM570jZA2CyvUCuG0RTM5dl5fid3ZAZA7DHXN31MTPqPrx8AVvU5xZCZAuWc70EotLlSVofH6HO2RdEpe2ZCHcrowowIgylWjZApRWhxWE5IslK0tlM2BfCcZAjcnNDLfpiMQ2durqpgx6ZBNXOT1yria8B6iA1RMMxrJBqxbiYXY25ZB

Take a copy of this request string, we’ll use this in Postman.

Execute in Postman

Now we have the fully formed request from the Graph API Explorer we can use this in Postman.  Create a new GET Request and past the request string into the address bar:

Click Send, your request will be sent to the Instagram Insights API which will return JSON similar to the following!

It’s a good time to recap. So far, we’ve:

• Connected to the Facebook Graph API
• Located the Facebook Pages and Instagram Business Accounts that our User has access to
• Identified the Instagram Business Account ID
• Constructed requests using the Facebook Graph API Explorer
• Extracted a list of Instagram Business Media Objects
• Extracted root level meta data for an Instagram Media Object
• Extracted Insight data for an Instagram Media Object
• Constructed and Submitted a request using Postman to verify that we can invoke the Facebook and Instagram Graph API outside the Facebook domain

There are quite a few steps here and we’ve covered a lot.  I recommend having a look through the Facebook and Instagram Developer API reference guides.  You’ll find other Nodes, Edges and Fields that let you surface other valuable datapoints!

Sample use cases for the Instagram API

Having programmatic access to Facebook and Instagram data opens the possibility for developers to build innovative solutions for many use cases.

Some examples that immediately spring to mind are:

Monitoring your Marketing Campaign

Maybe you’re promoting products and services on Instagram and whilst you can track the volume of sales through your CRM, you’re unsure how many eyeballs are on your Instagram marketing efforts or how many people are commenting on your content. As we’ve just seen, you can use the Insights API to track important KPIs such as impressions, engagement or the total number of comments per Instagram Media object.

Search by Hashtag

With the Hashtag Search API, you can list all media objects per with a given hashtag or even list the most popular images tagged with a given hashtag.  You can use this insight to help to gauge what sort of content is resonating with your audience.

Audience Insights

The Insights API has another endpoint which lets you extract data associated your followers. For example, you can extract a list of all cities, countries or even the age and gender distribution of your followers.  Use this data to help you better understand your audience and help drive your content creation strategy.

Another useful metric you can extract is the follower count for a given day.  You can write code that will aggregate this data over a given time period, thereby giving you further insights as to when the best time to share content is.

This is something I had to build as part of in interface for researchers involved in the National Geographic Photo Ark Project.  They were interested in helping National Geographic raise awareness of environmental and animal welfare issues.

Part of this involved surfacing content that was raising the number of followers daily, thereby providing researchers and the National Geographic Photo Ark Team with insight as to the types of images photographers should be taking more of and sharing on Instagram.

Identify Trends by Location

Interested in identifying trends by location? Filter users by their location, then run the Hashtag Search API to surface the most popular hashtags.  Run a second query with those hashtags and extract all media with said tags.  You then have a collection of images that are trending in that location!

Custom Dashboards

Do you need to aggregate data from all your social media channels into one easy to read screen? You can use the Facebook, Twitter and Instagram APIs to do just that! With some custom development you can use theses APIs to blend together datasets that give you a holistic view of all your social media data.

Summary

In this blog post we’ve introduced the Insights API. We’ve seen how you can connect to it using the Graph API Explorer and explored some of the data you can extract from the API. We’ve looked at how you can construct and send a request using Postman to the Insights API for testing purposes.

From a business perspective, we’ve identified several use cases for the Insights API, I’m sure you’ve probably got your own ideas brewing!

Are you considering building software that integrates with the Instagram Graph API?
Do you have any further questions?

Drop me a note!