Instagram Graph API v10を使いこなす。

Instagram Graph APIを使って、色々なデータを取得します。

アカウントの準備

Instagram Graph APIを使うためには下記のアカウントが必要になります。

• Instagramアカウント
• Facebookアカウント

Instagramアカウントの準備

1. Instagram: アカウントの作成(既にある場合はスキップ)
2. Instagram App: ボトムメニューのプロフィールボタンをクリックします。
3. Instagram App: 右上のメニューボタンをクリックする。
4. Instagram App: 右記のようにクリックする。[設定] > [アカウント] > [プロアカウントに切り替える]

Facebookアカウントの準備

1. Facebook: アカウントの作成(既にある場合はスキップ)
2. Facebook: Facebookページを作成する。
3. Facebookページ: 右記のようにクリックする。[設定] > [Instagram] > [アカウントをリンク]
4. Facebook for Developers: Facebook for Developersでアプリを作成する。
5. Facebook for Developers: ウィザードに従ってアプリを作成する。

アクセストークンを取得する

1. グラフAPIエクスプローラ: グラフAPIエクスプローラを開く
2. グラフAPIエクスプローラ: [ユーザーまたはページ]のドロップダウンリストの中で項目:[ページアクセストークン]のInstagramとリンクしたFacebookページを選択する。

3. グラフAPIエクスプローラ: [アクセス許可] > [許可を追加] で下記のアクセス許可を与える。

   • instagram_basic
   • instagramcontentpublish
   • instagrammanagecomments
   • instagrammanageinsights
   • pagesshowlist
   • pagesreadengagement
4. グラフAPIエクスプローラ: Generate Access Tokenをクリックし、アクセストークンを発行。アクセストークンを文字列としてメモしておく。
5. アクセストークンデバッガー: アクセストークンデバッガーを開く。
6. アクセストークンデバッガー: アクセストークンを入力してデバッグをクリックする。
7. アクセストークンデバッガー: タイプが「Page」になっていることを確認する。

InstagramビジネスユーザーのIDを調べる

ここまでメモしたものを確認します。

• アクセストークン: アクセストークンを取得する#4で取得

以降、それぞれAccessTokenと呼び、コード上に左記の単語が出てきたら読者がメモした値に置き換えてください。

1. グラフAPIエクスプローラ: グラフAPIエクスプローラを開く
2. グラフAPIエクスプローラ: アクセストークンにAccessTokenを入力

3. グラフAPIエクスプローラ: URLに下記を入力する

   /me?fields=id,name,instagram_business_account{id}
   

4. グラフAPIエクスプローラ: 送信をクリック
5. グラフAPIエクスプローラ: レスポンスオブジェクトのinstagrambusinessaccount.idをメモする。(以降、InstagramビジネスユーザーIDと呼びます。)

---

Instagramのユーザー情報を調べる

ここまでメモしたものを確認します。

• アクセストークン(*AccessToken): アクセストークンを取得する#4で取得
• InstagramビジネスユーザーID(*InstagramBusinessAccountID): InstagramユーザーのIDを調べる#5で取得
• グラフAPIエクスプローラ: グラフAPIエクスプローラを開く
• グラフAPIエクスプローラ: アクセストークンにAccessTokenを入力

• グラフAPIエクスプローラ: URLに下記を入力する

  InstagramBusinessAccountID?fields=id,ig_id,username,biography,followers_count,follows_count,media_count,profile_picture_url,website,name
  

• グラフAPIエクスプローラ: 送信をクリック

返却される値は、後述のInstagramビジネスユーザーのデータを参照ください。

---

Instagramアカウントの投稿一覧を取得する

ここまでメモしたものを確認します。

• アクセストークン(*AccessToken): アクセストークンを取得する#4で取得
• InstagramビジネスユーザーID(*InstagramBusinessAccountID): InstagramユーザーのIDを調べる#5で取得
• グラフAPIエクスプローラ: グラフAPIエクスプローラを開く
• グラフAPIエクスプローラ: アクセストークンにAccessTokenを入力

• グラフAPIエクスプローラ: URLに下記のどちらかのパターンを入力する。

  • パターンA

  :InstagramBusinessAccountID/media?fields=id,ig_id,username,caption,comments_count,is_comment_enabled,like_count,media_product_type,media_url,media_type,permalink,owner,shortcode,thumbnail_url,timestamp,comments.limit(10){hidden,id,like_count,media,text,timestamp,user,username,replies},children.limit(10){id,ig_id,caption,comments_count,is_comment_enabled,like_count,media_product_type,media_type,media_url,owner,permalink,shortcode,thumbnail_url,timestamp,username,children,comments}&limit=1
  

  • パターンB

  :InstagramBusinessAccountID?fields=media.limit(1){id,ig_id,username,caption,comments_count,is_comment_enabled,like_count,media_product_type,media_url,media_type,permalink,owner,shortcode,thumbnail_url,timestamp,comments.limit(10){hidden,id,like_count,media,text,timestamp,user,username,replies},children.limit(10){id,ig_id,caption,comments_count,is_comment_enabled,like_count,media_product_type,media_type,media_url,owner,permalink,shortcode,thumbnail_url,timestamp,username,children,comments}}
  

• グラフAPIエクスプローラ: 送信をクリック

返却される値は、後述のInstagramメディアのデータを参照ください。

3-Aと3-Bの違いは、Instagramビジネスユーザーのmedia一覧データを取得を明示する箇所の違いになります。

• 3-A: パス上でmediaへアクセスすることを明示します。
• 3-B: fieldsでmediaへアクセスすることを明示します。 このようなアクセス方法の違いがあるので注意が必要です。

---

自分以外のInstagramビジネスユーザーの情報を探す。

IG User Business Discovery

ここまでメモしたものを確認します。

• アクセストークン(*AccessToken): アクセストークンを取得する#4で取得
• InstagramビジネスユーザーID(*InstagramBusinessAccountID): InstagramユーザーのIDを調べる#5で取得
• グラフAPIエクスプローラ: グラフAPIエクスプローラを開く
• グラフAPIエクスプローラ: アクセストークンにAccessTokenを入力

• グラフAPIエクスプローラ: URLに下記を入力する

  InstagramBusinessAccountID?fields=business_discovery.username(bluebottle){id,ig_id,username,biography,followers_count,follows_count,media_count,profile_picture_url,website,name}
  

• グラフAPIエクスプローラ: 送信をクリック

返却される値は、後述のInstagramビジネスユーザーのデータを参照ください。

---

自分以外のInstagramビジネスユーザーの投稿を探す。

IG User Business Discovery ここまでメモしたものを確認します。

• アクセストークン(*AccessToken): アクセストークンを取得する#4で取得
• InstagramビジネスユーザーID(*InstagramBusinessAccountID): InstagramユーザーのIDを調べる#5で取得
• グラフAPIエクスプローラ: グラフAPIエクスプローラを開く
• グラフAPIエクスプローラ: アクセストークンにAccessTokenを入力

• グラフAPIエクスプローラ: URLに下記を入力する

  InstagramBusinessAccountID?fields=business_discovery.username(bluebottle){media.limit(2){id,username,caption,comments_count,like_count,media_product_type,media_url,permalink,timestamp}}
  

• グラフAPIエクスプローラ: 送信をクリック

返却される値は、後述のInstagramビジネスユーザーのデータを参照ください。

---

Instagramビジネスユーザーのインサイトを取得する

Instagramビジネスユーザーのインサイトは下記のグループで集計されます。 メトリクスはUTC-07:00を終点としてピリオド単位で集計されます。

• lifetime: 最新の値を集計します。
• day: 1日のメトリクスを取得します。
• week: 1週間のメトリクスを取得します。
• days_28: 28日のメトリクスを取得します。

Lifetime

Lifetimeに分類されるメトリクスは、フォロワーの構造を表しています。

• metric

  • audience_city: フォロワーの居住都市
  • audience_country: フォロワーの居住国
  • audiencegenderage: フォロワーの性別-年齢
  • audience_locale: フォロワーの言語
  • online_followers: フォロワーのオンライン状態

最新の状態しか取得できません。

IG User Insights ここまでメモしたものを確認します。

• アクセストークン(*AccessToken): アクセストークンを取得する#4で取得
• InstagramビジネスユーザーID(*InstagramBusinessAccountID): InstagramユーザーのIDを調べる#5で取得
• グラフAPIエクスプローラ: グラフAPIエクスプローラを開く
• グラフAPIエクスプローラ: アクセストークンにAccessTokenを入力

• グラフAPIエクスプローラ: URLに下記を入力する

  InstagramBusinessAccountID/insights?metric=audience_city,audience_country,audience_gender_age,audience_locale,online_followers&period=lifetime
  

• グラフAPIエクスプローラ: 送信をクリック

返却される値は、後述のメトリクスのデータを参照ください。

Day, Week, Days_28

Day, Week, Days_28に分類されるメトリクスは、ユーザーが得た他ユーザーの行動です。

• metric

  • impressions: 集計期間中のビジネスアカウントのメディアオブジェクトの合計ビュー数
  • reach: 集計期間中のビジネスアカウントのメディアオブジェクトの合計ユニークビュー数
  • profile_views: 集計期間中のビジネスアカウントのプロフィールを見た合計ユーザー数
  • follower_count: 集計期間中にフォローされたのユニークアカウントの合計数
  • textmessageclicks: 集計期間中のプロフィールのSMSリンクの合計タップ数
  • website_clicks: 集計期間中のプロフィールのウェブサイトリンクの合計タップ数
  • phonecallclicks: 集計期間中のプロフィールの通話発信リンクの合計タップ数
  • email_contacts: 集計期間中のプロフィールのメールリンクの合計タップ数
  • getdirectionsclicks: 集計期間中の道順の表示リンクの合計タップ数
• since: レスポンスに含まれるメトリクスの開始日をUNIX時間で指定します。
• until: レスポンスに含まれるメトリクスの終了日をUNIX時間で指定します。

IG User Insights ここまでメモしたものを確認します。

• アクセストークン(*AccessToken): アクセストークンを取得する#4で取得
• InstagramビジネスユーザーID(*InstagramBusinessAccountID): InstagramユーザーのIDを調べる#5で取得
• グラフAPIエクスプローラ: グラフAPIエクスプローラを開く
• グラフAPIエクスプローラ: アクセストークンにAccessTokenを入力

• グラフAPIエクスプローラ: URLに下記を入力する

  InstagramBusinessAccountID/insights?metric=email_contacts,follower_count,get_directions_clicks,impressions,phone_call_clicks,profile_views,reach,text_message_clicks,website_clicks&period=day&since=1617000000&until=1617267068
  

• グラフAPIエクスプローラ: 送信をクリック

返却される値は、後述のメトリクスのデータを参照ください。

---

Instagramメディアのインサイトを取得する

IG Media Insights ここまでメモしたものを確認します。

• アクセストークン(*AccessToken): アクセストークンを取得する#4で取得
• InstagramMediaID: [Instagramアカウントの投稿一覧を取得する]で取得したメディアオブジェクトのidフィールドを使います。

Photo and Video Metrics

• metric

  • engagement: メディアオブジェクトの「いいね！」とコメントの合計数
  • impressions: メディアオブジェクトの合計ビュー数
  • reach: メディアオブジェクトを見たユニークアカウントの合計数
  • saved: メディアオブジェクトを保存したユニークアカウントの合計数
  • video_views: メディアオブジェクトのビデオが見られた回数(*Videoのみリクエスト可能、Photoでリクエストするとエラーが発生します。)
• グラフAPIエクスプローラ: グラフAPIエクスプローラを開く
• グラフAPIエクスプローラ: アクセストークンにAccessTokenを入力
• グラフAPIエクスプローラ: URLに下記を入力する

Photoの場合

InstagramMediaID/insights?metric=engagement,impressions,reach,saved

Videoの場合

InstagramMediaID/insights?metric=engagement,impressions,reach,saved,video_views

4. グラフAPIエクスプローラ: 送信をクリック

返却される値は、後述のメトリクスのデータを参照ください。

Album Metrics

• metric

  • carouselalbumengagement: メディアオブジェクトの「いいね！」とコメントの合計数
  • carouselalbumimpressions: メディアオブジェクトの合計ビュー数
  • carouselalbumreach: メディアオブジェクトを見たユニークアカウントの合計数
  • carouselalbumsaved: メディアオブジェクトを保存したユニークアカウントの合計数
  • carouselalbumvideo_views: メディアオブジェクトのビデオが見られた回数(*Videoのみリクエスト可能、Photoでリクエストするとエラーが発生します。)
• グラフAPIエクスプローラ: グラフAPIエクスプローラを開く
• グラフAPIエクスプローラ: アクセストークンにAccessTokenを入力
• グラフAPIエクスプローラ: URLに下記を入力する

Photoの場合

InstagramMediaID/insights?metric=carousel_album_engagement,carousel_album_impressions,carousel_album_reach,carousel_album_saved

Videoの場合

InstagramMediaID/insights?metric=carousel_album_engagement,carousel_album_impressions,carousel_album_reach,carousel_album_saved,carousel_album_video_views

4. グラフAPIエクスプローラ: 送信をクリック

返却される値は、後述のメトリクスのデータを参照ください。

Story Metrics

• metric

  • impressions: メディアオブジェクトの合計ビュー数
  • reach: メディアオブジェクトを見たユニークアカウントの合計数
  • replies: 返信の数です。値には、欧州経済地域（EEA）のユーザーが行った返信は含まれません。ストーリーがEAAのユーザーによって作成された場合は、0の値を返します。
  • taps_forward: 次の写真や動画を見るためのタップをした回数
  • taps_back: 前の写真や動画を見るためのタップをした回数
  • exits: 途中で中断した回数
• グラフAPIエクスプローラ: グラフAPIエクスプローラを開く
• グラフAPIエクスプローラ: アクセストークンにAccessTokenを入力

• グラフAPIエクスプローラ: URLに下記を入力する

  InstagramMediaID/insights?metric=impressions,reach,replies,taps_forward,taps_back,exits
  

• グラフAPIエクスプローラ: 送信をクリック

返却される値は、後述のメトリクスのデータを参照ください。

---

Instagramのデータ群

Instagramビジネスユーザー

データフィールド

• id: ユーザーID
• ig_id: InstagramユーザーID
• username: ユーザ名(アカウント名)
• name: ユーザー名(表示名)
• biography: プロフィール説明文
• website: プロフィールのサイトURL
• profilepictureurl: プロフィール画像のURL
• follows_count: フォローカウント数
• followers_count: フォロワーカウント数
• media_count: 投稿数

データノード

• media: ユーザーが投稿したメディアのノードです。
• insights: ユーザーのインサイトのノードです。
• stories: ユーザーが投稿したストーリーのノードです。
• tags: TODO
• contentpublishinglimit: TODO
• recentlysearchedhashtags: TODO

Instagramメディア / Instagram子メディア

• Instagramメディア

データフィールド

• id: メディアID
• ig_id: InstagramメディアID (*メディア投稿者以外のクエリでは非公開)
• username: メディアを作成したユーザーのユーザーネーム

• mediaproducttype: メディアが公開されるサーフェス、下記の値をとります。

  • AD
  • FEED
  • IGTV
  • STORY

• media_type: メディアの種類、下記の値をとります。

  • CAROUSEL_ALBUM: 複数枚画像で構成されるメディア
  • IMAGE: 単一画像で構成されるメディア
  • VIDEO: 動画で構成されるメディア
• caption: キャプション
• iscommentenabled: コメントが有効か無効か (*メディア投稿者以外のクエリでは非公開)
• comments_count: コメントの数
• like_count: いいねの数
• media_url: メディアURL
• permalink: メディアのInstagram上のURL
• owner: メディアを作成したInstagramユーザーのID (*メディア投稿者以外のクエリでは非公開)
• shortcode: メディアを指すショートコード。 (*メディア投稿者以外のクエリでは非公開)
• video_title: IGTVメディアのタイトル。
• thumbnail_url: メディアのサムネイルURL。VIDEOメディアでのみ使用できます。 (*メディア投稿者以外のクエリでは非公開)
• timestamp: ISO 8601形式のUTCで表した作成日(デフォルトはUTC ±00:00)

データノード

• children: カルーセルアルバムに含まれるメディアを表します。
• comments: メディアに対してのコメントを表します。
• insights: メディアのインサイトを表します。

Instagramコメント / Instagramリプライ

• Instagramコメント
• Instagramリプライ

データフィールド

• id: InstagramコメントID
• user: クエリを発行したユーザーがこのコメントの所有者だった場合に、idが設定されます。
• username: コメントを投稿したユーザーのuser名
• hidden: コメントの可視性
• text: コメントのテキスト
• media: コメントが所属するメディアのメディアID
• like_count: コメントのいいね数
• timestamp: コメントの登録時間

データノード

• replies

メトリクス

データフィールド

• id: メトリクスID
• name: メトリクス名
• period: ピリオド
• title: メトリクスのタイトル
• description: メトリクスの説明

• values: メトリクスの値配列

  • value: メトリクスの値
  • end_time: メトリクスの集計終了時間

データノード

Instagram

データフィールド

データノード

---

永続アクセストークンの取得方法

グラフAPIエクスプローラで生成されるアクセストークンは、有効期間が生成後1時間となっています。 少しテストする程度であればいいのですが、バッチ等で定期的に長期間使用するには不適です。 今回は、有効期間が無い(失効しない)、永続アクセストークンを取得する方法を記載します。

ここまでメモしたものを確認します。

• アクセストークン(*AccessToken): アクセストークンを取得する#4で取得
• アクセストークンデバッガー: アクセストークンデバッガーを開く。
• アクセストークンデバッガー: アクセストークンにAccessTokenを入力
• アクセストークンデバッガー: アクセストークン入力欄の右隣の「デバッグ」ボタンをクリックする。
• アクセストークンデバッガー: ページ下部にある「アクセストークンを延長」ボタンをクリックする。
• アクセストークンデバッガー: 生成されたアクセストークンをPersistentAccessTokenとしてメモする。

以前は、永続アクセストークンを取得するには、Graph APIをいくつか使用し様々なアクセストークンを経由する必要がありました。 今ではボタン一つで生成できるので便利になりましたね。

永続アクセストークンは、失効することがないので取り扱いに気をつけましょう。

---

TODO 追記すること

• ページネーション
• アカウントの状態: 公開/非公開 プロ/一般
• IG User Content Publishing Limit
• IG User Media Publish
• IG User Mentions
• IG User Mentioned Comment
• メンションされたメディア
• Recently Searched Hashtags
• Stories
• Tags
• Instagramメディアの作成
• Mentions
• Instagram用のWebhooksの設定
• コンテンツ公開
• コメントモデレーション
• ハッシュタグ検索
• インサイト