Data Connector for Instagram User & Media Insights

Instagram Business enables you to obtain insights about your Instagram media objects and your user account activities. You can use Treasure Data’s connector to bring Instagram insight data into Treasure Data for integration with your other data resources on the Treasure Data platform.

Table of Contents

Prerequisites

You must have an Instagram Business account https://business.instagram.com/ (Personal Instagram accounts can be converted to business accounts).

Knowledge:

  1. Basic knowledge of Treasure Data
  2. Basic knowledge of Instagram
  3. Basic knowledge of Facebook Graph API

Use Web Console

Create a new connection

Go to Treasure Data Connections. Locate and select Instagram User & Media Insights. A dialog will open.



Select an existing OAuth connection for Instagram Insights, or click the link under OAuth connection to create a new connection.





Create a new OAuth connection

Instagram OAuth uses Facebook OAuth so you are taken to the Facebook OAuth page.

Log into your Facebook account:



And grant access to Treasure Data app by clicking the ‘Continue as ’ button.



You will be redirected back to Treasure Data Connections.

Create a new transfer

Select the My Connections tab, find the connection you created, and click New Transfer.



Configure the connector by completing the fields.



Instagram Insights supports the following parameters.

Facebook Page Name (Required)

Enter the name of the Facebook page that is linked to the Instagram Business account. When a user creates or converts an Instagram account to a business account, the user is required to link the Instagram Account to a Facebook page.



Data type (Required)

Select one of the data types: User and Media.

User insights are metrics collected about your Instagram Business account, such as impressions, follower_count, website_clicks, and audience_locale.

Media insights are metrics collected from content posted for your Instagram business account, such as engagement, impressions, reach, and saved.

Start Date & End Date (Required for the User data type)

The start date and end date must follow the format: YYYY-MM-DD. Example: 2017-11-21.

Start Date is inclusive and End Date is exclusive.

If not specified, the end date defaults to the current time in Instagram Business Account Local Time.

If not specified, the start date defaults to 2 days before the end date.

The defaults are set by Facebook API.

Data is aggregated at the end of each day, so the insights of 2017-01-01 result in end_time = 2017-01-02 00:00:00.

If you use incremental loading and scheduled jobs, the time range for the next iteration (run) is calculated based on the period between the initial start and end dates, and the imported data will not have gaps.

Use Individual Metrics

Select if you want to manually choose the metrics data to import. The dropdown lists all individual metrics for the selected data type. You can select multiple metrics.

Media metrics supports only [period: lifetime]


User metrics support day, week, days_28, and lifetime


Note: Except for the online_followers metric, the lifetime metric requires that the Incremental Loading checkbox is unchecked and the Start Date and End Date fields are empty.

Preset Metrics

You can select multiple, preset metrics for the selected data type.

For User metrics, the default is Week metrics. You can select from the following preset User metrics:

  • Week metrics [period: week]

  • Days 28 metrics [period: days_28]

  • Day metrics [period: day]

  • Lifetime metrics [period: lifetime], does not support incremental import

For Media metrics, the default is All media metrics. You can select from the following preset Media metrics:

  • All media metrics. All media metrics will import metrics for all content in Instagram account*

  • Story metrics. Import metrics for Instagram Story

  • Carousel metrics. Import metrics for Instagram Carousel

  • Photo and video metrics, will only import metrics for Instagram image and video*

Import media metrics


Media metrics [period: lifetime]

If a metric is supported by multiple media objects, example: IMAGE, VIDEO, STORY, and so on, then the metric values of all those media objects will be imported.

Import user metrics

User metrics support day, week, days_28, and lifetime


Note: Except for the online_followers metric, all [period: lifetime] metrics require that the Incremental Loading checkbox is unchecked and the Start Date and End Date fields are empty.

Incremental Loading

By enabling Incremental Loading, you can schedule a job to run iteratively. Each iteration of the job run is calculated based on the Start Date and End Date values.



In the following example, let’s use a 9 day range between the start and end date:

Start Date: 2017-10-01
End Date: 2017-10-11

Each job will have the same time range as determined by period between the start and end dates. The transfer of metrics begins at the completion of the previous job, until the period extends past the current date (which is the default end date). Further transfers will be delayed until a complete period is available, at which the job will execute and then pause until the next period is available.

1st run: Starting end_time: 2017-10-01 07:00:00 Ending end_time: 2017-10-10 07:00:00

2nd run: Starting end_time: 2017-10-11 07:00:00 Ending end_time: 2017-10-20 07:00:00

3rd run: Starting end_time: 2017-10-21 07:00:00 Ending end_time: 2017-10-30 07:00:00

Data schema

User

For the user data, output metrics are grouped by metrics end time.

Columns:
  • end_time:

      Type: timestamp
      Example: 2017-10-04 07:00:00 UTC
    
  • Metric column names are a combination of the metric name and the period. You can import as many metrics as you want to import.

      Type: json
      Format: <metric_name>_<period>
      Example:
         impressions: "777"
         online_followers: "{"0":10,"2":12}"
         audience_city: "{"San Bruno, California":1,"San Francisco, California":14}"
    

Example:

+---------------------------+-----------------------+-----------------+
| end_time:timestamp        | impressions_week:json | reach_week:json |
+---------------------------+-----------------------+-----------------+
| "2017-10-04 07:00:00 UTC" | "777"                 | "129"           |
| "2017-10-25 07:00:00 UTC" | "424"                 | "105"           |
| "2017-10-12 07:00:00 UTC" | "277"                 | "94"            |
| "2017-10-17 07:00:00 UTC" | "301"                 | "92"            |
| "2017-10-19 07:00:00 UTC" | "246"                 | "86"            |
| "2017-10-10 07:00:00 UTC" | "425"                 | "115"           |
| "2017-10-06 07:00:00 UTC" | "869"                 | "139"           |
| "2017-10-01 07:00:00 UTC" | "245"                 | "93"            |
| "2017-10-14 07:00:00 UTC" | "163"                 | "74"            |
| "2017-10-22 07:00:00 UTC" | "328"                 | "95"            |
| "2017-10-27 07:00:00 UTC" | "493"                 | "111"           |
| "2017-10-16 07:00:00 UTC" | "220"                 | "87"            |
| "2017-10-08 07:00:00 UTC" | "870"                 | "142"           |
| "2017-10-20 07:00:00 UTC" | "290"                 | "90"            |
| "2017-10-18 07:00:00 UTC" | "314"                 | "90"            |
+---------------------------+-----------------------+-----------------+

Media

Media insights support only the lifetime period and therefore do not have end_time columns

Columns:
  • media_id. Id of the media object

      Type: string
      Example: 17911498252005516
    
  • media_type. Type of the media object

      Type: string
      Example: IMAGE
    
  • media_url. Url of the media object

      Type: string
      Example: https://scontent.xx.fbcdn.net/t51.2885-9/25006602_1743229305722329_8614293073817501696_n.jpg
    
  • Metric column names are a combination of the metric name and period. You can have multiple metric columns if you want to import multiple metrics.

      Type: json
      Format: <metric_name>_<period>
      Example:
      engagement : "21"
    

Example:

+---------------------+-------------------+------------------------------------------------------------------------------------------------+--------------------------+---------------------------+---------------------+---------------------+---------------------------+
| media_id:string     | media_type:string | media_url:string                                                                               | engagement_lifetime:json | impressions_lifetime:json | reach_lifetime:json | saved_lifetime:json | video_views_lifetime:json |
+---------------------+-------------------+------------------------------------------------------------------------------------------------+--------------------------+---------------------------+---------------------+---------------------+---------------------------+
| "17911498252005516" | "IMAGE"           | "https://scontent.xx.fbcdn.net/t51.2885-9/25006602_1743229305722329_8614293073817501696_n.jpg" | "21"                     | "114"                     | "76"                | "0"                 | nil                       |
| "17885782774150716" | "VIDEO"           | "https://video.xx.fbcdn.net/t50.2886-2/24738919_151765602217728_5437292618071408640_n.mp4"     | "9"                      | "86"                      | "56"                | "0"                 | "36"                      |
| "17906391814069651" | "IMAGE"           | "https://scontent.xx.fbcdn.net/t51.2885-9/25010789_2052507434765323_4336390331424571392_n.jpg" | "17"                     | "88"                      | "58"                | "0"                 | nil                       |
| "17910305437028795" | "IMAGE"           | "https://scontent.xx.fbcdn.net/t51.2885-9/24177420_156326688310586_4148079938462810112_n.jpg"  | "15"                     | "127"                     | "74"                | "0"                 | nil                       |
| "17892948598126997" | "VIDEO"           | "https://video.xx.fbcdn.net/t50.2886-2/23171122_896280000521668_699036065209516032_n.mp4"      | "15"                     | "114"                     | "68"                | "0"                 | "62"                      |
| "17893013761117885" | "IMAGE"           | "https://scontent.xx.fbcdn.net/t51.2885-9/23101052_1745909115421876_275162886614024192_n.jpg"  | "22"                     | "120"                     | "66"                | "0"                 | nil                       |
+---------------------+-------------------+------------------------------------------------------------------------------------------------+--------------------------+---------------------------+---------------------+---------------------+---------------------------+

Preview and Advanced Configuration

In Create Transfer screen, click next to see a preview of the data to be imported. You can click Advanced Settings to add more detail to your configuration.


You can specify the following parameters:

  • Throttled wait in milliseconds. When API limit are reached, Facebook will throttle (block) API calls. You must wait for the specified amount of time before you can start calling the API again.

      Type: number
      Default: 3600000
    
  • Maximum retry times. Specifies the maximum retry times for each API call.

      Type: number
      Default: 3
    
  • Initial retry interval millisecond. Specifies the wait time for first retry.

      Type: number
      Default: 20000
    
  • Maximum retry interval milliseconds. Specifies the maximum time between retries.

      Type: number
      Default: 120000
    
  • Connection timeout in milliseconds. Specifies amount of time before the connection times out when doing API calls.

      Type: number
      Default: 30000
    
  • Connection idle timeout in milliseconds. Specifies amount of time that a connection can stay idle in the pool.

      Type: number
      Default: 60000
    

Last modified: Mar 15 2018 08:03:26 UTC

If this article is incorrect or outdated, or omits critical information, let us know. For all other issues, access our support channels.