はじめに
Facebookが提供しているビジネスアカウント用InstagramAPIについての解説。(2018/03/06時点, APIのバージョンは2.12)
ところどころ自分へのメモとしてエンジニア向けの内容もありますが、わからないところはエンジニアに確認するのが良さそう。
Instagramが提供しているAPIについては下記リンクへ。
ビジネスアカウント用InstagramAPIとは
Instagramでビジネスアカウントに設定しているアカウントのメディア情報やコメント、メタデータを管理したり、インサイト情報を取得できる。
ただし、InstagramアカウントがFacebookページに紐づいていることで使用できるもの。
詳細は下記リンクへ。
APIの利用について
APIを利用できるようになるには、
FacebookにAPIを利用するための申請が必要になる。
現時点ではやりたいことに応じて下記のようなパーミッションの申請をFacebookに行わなければならない。
- instagram_basic
- instagram_content_publish
- instagram_manage_comments
- instagram_manage_insights
またもしくは
- ads_management
- manage_pages
- business_management
などが必要になる。
詳しくはエンジニアに相談してみよう。
また、APIの機能を利用する対象となるInstagramのビジネスアカウントはFacebookPageと紐づいた状態になっている必要がある。
詳しい手順は下記リンクに記載してある。
上記の手順に従って紐づけるとこのようになる。
もろもろ設定すると
FacebookのAPIを利用してビジネスアカウントのIDを取得できるようになる。
↓(エンジニア向け)
me/accounts?fields=instagram_business_account
制限
1ユーザーあたり1時間に200回までAPIにリクエストを行うことができる。
ただ、 /media/comments に対して(主にコメントの書き込み)は 1時間で60回という制限がある。
Facebook Grap APIの制限に関しての詳細は下記リンクへ。
Webhooks(ウェブフックス)
FacebookのWebhooks(ウェブフックス)機能を使用することで、
誰かが対象メディアにコメントしたり、ストーリーが終了したことをリアルタイムに受け取ることができるようになる。
そうすることで、 ストーリーが終了したときにインサイトデータを取得する といった機能を実装することができるようになる。
これをうまく活用すればFacebookGraphAPIのレート制限を回避することができるようになる。
InstagramのWebhookについては comments と story_insights に対して設定することができる。
詳細は下記リンクへ。
それぞれAPIで出来ること
主にこちらのページに記載してある。
コメント(comment)/リプライ(reply)
以下、コメント(comment)/リプライ(reply)についてできること。
- コメントのメタデータの取得
- コメントの非表示
- コメントの削除
- コメントへの返事
- コメントへの返事を全て取得
取得できるメタデータ情報
- 非表示かどうか
- コメントID
- コメントへのいいね数
- 投稿メディアID
- コメント内容
- コメント時間
- ビジネスアカウントID(*コメントしたユーザーの情報ではなく使用しているアクセストークンを取得したユーザー)
メディア(media)
以下、メディア(media)についてできること。
- メディアのメタデータの取得
- コメントのオンとオフの切り替え
- コメントの作成
- カルーセルメディア情報の取得
- すべてのコメントの取得
- すべてのインサイトデータの取得
取得できるメタデータ情報
- キャプション(*1)
- 1枚目以外のカルーセル(カルーセルのときのみ)
- コメント情報(*1)
- コメント数
- メディアID
- インスタグラムのユーザーID
- コメントが可能かどうか
- いいね数
- メディアタイプ(画像・動画・カルーセル)
- 投稿URL
- 投稿者ID
- パーマリンク
- ショートコード
- サムネイルURL(動画投稿のみ)
- 投稿時間
*1...1枚目以外のカルーセル情報には含まれない
インサイト情報
[画像、動画の場合]
- エンゲージメント(いいね数とコメント数の合計)
- インプレッション数
- リーチ数(ユニークユーザー数)
- 保存数
- 動画再生数(動画のみ)
[カルーセルの場合]
- カルーセルアルバムエンゲージメント(いいねとコメントのみ)
- カルーセルアルバムインプレッション数
- カルーセルアルバムリーチ数
- カルーセルアルバム保存数
- カルーセルアルバム動画再生数
[ストーリーの場合]
- 離脱数
- インプレッション数
- リーチ数(ユニークユーザー数)
- 返信数
- タップ数(次へ)
- タップ数(戻る)
こんな感じのリクエストを送ると見れる(エンジニア向け)
画像、動画の場合
投稿メディアID/insights?metric=impressions,engagement,reach,saved
{
"data": [
{
"name": "impressions",
"period": "lifetime",
"values": [
{
"value": 384
}
],
"title": "Impressions",
"description": "Total number of times the media object has been seen",
"id": "17911965460051769/insights/impressions/lifetime"
},
{
"name": "engagement",
"period": "lifetime",
"values": [
{
"value": 34
}
],
"title": "Engagement",
"description": "Total number of likes and comments on the media object",
"id": "17911965460051769/insights/engagement/lifetime"
},
{
"name": "reach",
"period": "lifetime",
"values": [
{
"value": 217
}
],
"title": "Reach",
"description": "Total number of unique accounts that have seen the media object",
"id": "17911965460051769/insights/reach/lifetime"
},
{
"name": "saved",
"period": "lifetime",
"values": [
{
"value": 0
}
],
"title": "Saved",
"description": "Total number of unique accounts that have saved the media object",
"id": "17911965460051769/insights/saved/lifetime"
}
]
}
カルーセルの場合
カルーセルメディアID/insights?metric=carousel_album_engagement,carousel_album_impressions,carousel_album_reach,carousel_album_saved,carousel_album_video_views
{
"data": [
{
"name": "carousel_album_engagement",
"period": "lifetime",
"values": [
{
"value": 68
}
],
"title": "Carousel Album Engagement",
"description": "Total number of likes and comments on the carousel album",
"id": "17903821636004916/insights/carousel_album_engagement/lifetime"
},
{
"name": "carousel_album_impressions",
"period": "lifetime",
"values": [
{
"value": 300
}
],
"title": "Carousel Album Impressions",
"description": "Total number of times the carousel album has been seen",
"id": "17903821636004916/insights/carousel_album_impressions/lifetime"
},
{
"name": "carousel_album_reach",
"period": "lifetime",
"values": [
{
"value": 161
}
],
"title": "Carousel Album Reach",
"description": "Total number of unique accounts that have seen the carousel album",
"id": "17903821636004916/insights/carousel_album_reach/lifetime"
},
{
"name": "saved",
"period": "lifetime",
"values": [
{
"value": 0
}
],
"title": "Carousel Album Saved",
"description": "Total number of unique accounts that have saved the carousel album",
"id": "17903821636004916/insights/saved/lifetime"
},
{
"name": "video_views",
"period": "lifetime",
"values": [
{
"value": 0
}
],
"title": "Carousel Album Video Views",
"description": "Total number of times the carousel album has been seen",
"id": "17903821636004916/insights/video_views/lifetime"
}
]
}
ストーリーの場合
ストーリーID/insights?metric=exits,impressions,reach,replies,taps_forward,taps_back
{
"data": [
{
"name": "exits",
"period": "lifetime",
"values": [
{
"value": 12
}
],
"title": "Exits",
"description": "Number of times someone exited the carousel",
"id": "17890196911076847/insights/exits/lifetime"
},
{
"name": "impressions",
"period": "lifetime",
"values": [
{
"value": 66
}
],
"title": "Impressions",
"description": "Total number of times the media object has been seen",
"id": "17890196911076847/insights/impressions/lifetime"
},
{
"name": "reach",
"period": "lifetime",
"values": [
{
"value": 50
}
],
"title": "Reach",
"description": "Total number of unique accounts that have seen the media object",
"id": "17890196911076847/insights/reach/lifetime"
},
{
"name": "replies",
"period": "lifetime",
"values": [
{
"value": 0
}
],
"title": "Replies",
"description": "Total number of replies to the carousel",
"id": "17890196911076847/insights/replies/lifetime"
},
{
"name": "taps_forward",
"period": "lifetime",
"values": [
{
"value": 24
}
],
"title": "Taps Forward",
"description": "Total number of taps to see this story's next photo or video",
"id": "17890196911076847/insights/taps_forward/lifetime"
},
{
"name": "taps_back",
"period": "lifetime",
"values": [
{
"value": 4
}
],
"title": "Taps Back",
"description": "Total number of taps to see this story's previous photo or video",
"id": "17890196911076847/insights/taps_back/lifetime"
}
]
}
ページ(Page)
FacebookPageに紐づくInstagramビジネスアカウントIDを取得できる。
ユーザー(User)
以下、ユーザー(User)についてできること。
- Instagramビジネスアカウントのメタデータの取得
- メディアの作成・投稿(Content Publishing APIで可能)
- 他のInstagramビジネスアカウントの情報取得(Business Discovery)
- インサイト情報の取得
- 投稿の取得
- ストーリーの取得
- アカウントがタグ付けされている投稿情報の取得
- 他のユーザーによってメンションされているコメント情報の取得
- 他のユーザーによってキャプション内にてメンションされている投稿情報の取得
- メンションに対してのコメント
Instagramビジネスアカウントのメタデータ、インサイト情報、メディアなどを取得できる。
取得できるメタデータ情報
メタデータ
- 自己紹介文
- ビジネスアカウントID
- インスタグラムのユーザーID
- フォロワー数
- フォロー数
- 投稿数
- ユーザー名
- プロフィール画像URL
- website情報
インサイト情報
- インプレッション数: プロフィールページのインプレッション数(*1)
- リーチ数: プロフィールページのユニークアクセス数(*1)
- フォロワー数(*2)
- Eメールリンククリック数(*2)
- テキストメッセージリンククリック数(*2)
- (*2)
- 位置情報クリック数(*2)
- Webサイトクリック数(*2)
- 指定期間のプロフィールビュー数(*2)
- 訪問ユーザー年齢(*3)
- 訪問ユーザー位置情報(*3)
- 訪問ユーザー国(*3)
- 訪問ユーザー市(*3)
- 指定した期間のオンラインフォロワー数(*3)
取得できる期間
*1...1日単位、1週間合計、28日間合計
*2...1日単位のみ
*3...1日前のデータのみ
30日以内で期間を指定してインサイト情報を取得できる。
取得できる期間の指定方法には
- 日別
- 1週間合計
- 28日間合計
などがある。
ちなみに30日より長い期間で指定すると下記のようなエラーが返ってくる。(エンジニア向け)
There cannot be more than 30 days (2592000 s) between since and until.
こんな感じでリクエストを送ると見れる(エンジニア向け)
ビジネスアカウントID/insights?metric=impressions&period=day&since=1504191600&until=1505746800
2017/09/09 00:00:00~2017/09/19 00:00:00 で期間指定
2017/09/19にAPIにリクエストを送っているため9/19のデータは取得できていない。
{
"data": [
{
"name": "impressions",
"period": "day",
"values": [
{
"value": 47,
"end_time": "2017-09-01T07:00:00+0000"
},
{
"value": 261,
"end_time": "2017-09-02T07:00:00+0000"
},
{
"value": 46,
"end_time": "2017-09-03T07:00:00+0000"
},
{
"value": 49,
"end_time": "2017-09-04T07:00:00+0000"
},
{
"value": 18,
"end_time": "2017-09-05T07:00:00+0000"
},
{
"value": 64,
"end_time": "2017-09-06T07:00:00+0000"
},
{
"value": 47,
"end_time": "2017-09-07T07:00:00+0000"
},
{
"value": 312,
"end_time": "2017-09-08T07:00:00+0000"
},
{
"value": 372,
"end_time": "2017-09-09T07:00:00+0000"
},
{
"value": 36,
"end_time": "2017-09-10T07:00:00+0000"
},
{
"value": 35,
"end_time": "2017-09-11T07:00:00+0000"
},
{
"value": 51,
"end_time": "2017-09-12T07:00:00+0000"
},
{
"value": 200,
"end_time": "2017-09-13T07:00:00+0000"
},
{
"value": 113,
"end_time": "2017-09-14T07:00:00+0000"
},
{
"value": 91,
"end_time": "2017-09-15T07:00:00+0000"
},
{
"value": 51,
"end_time": "2017-09-16T07:00:00+0000"
},
{
"value": 98,
"end_time": "2017-09-17T07:00:00+0000"
},
{
"value": 80,
"end_time": "2017-09-18T07:00:00+0000"
}
],
"title": "Impressions",
"description": "Total number of times this profile has been seen",
"id": "17841405034517108/insights/impressions/day"
}
],
"paging": {
"previous": "",
"next": ""
}
}
ビジネスアカウントID/insights?fields=values,id,description,name,title&period=day&metric=impressions,reach,follower_count,email_contacts,phone_call_clicks,text_message_clicks,get_directions_clicks,website_clicks,profile_views&pretty=0
{
"data": [
{
"values": [
{
"value": 98,
"end_time": "2017-09-17T07:00:00+0000"
},
{
"value": 80,
"end_time": "2017-09-18T07:00:00+0000"
}
],
"id": "17841405034517108/insights/impressions/day",
"description": "Total number of times this profile has been seen",
"name": "impressions",
"title": "Impressions"
},
{
"values": [
{
"value": 59,
"end_time": "2017-09-17T07:00:00+0000"
},
{
"value": 46,
"end_time": "2017-09-18T07:00:00+0000"
}
],
"id": "17841405034517108/insights/reach/day",
"description": "Total number of unique accounts that have seen this profile",
"name": "reach",
"title": "Reach"
},
{
"values": [
{
"value": 3,
"end_time": "2017-09-17T07:00:00+0000"
},
{
"value": 4,
"end_time": "2017-09-18T07:00:00+0000"
}
],
"id": "17841405034517108/insights/follower_count/day",
"description": "Total number of unique accounts following this profile",
"name": "follower_count",
"title": "Follower Count"
},
{
"values": [
{
"value": 0,
"end_time": "2017-09-17T07:00:00+0000"
},
{
"value": 0,
"end_time": "2017-09-18T07:00:00+0000"
}
],
"id": "17841405034517108/insights/email_contacts/day",
"description": "Total number of taps on the email link in this profile",
"name": "email_contacts",
"title": "Email Contacts"
},
{
"values": [
{
"value": 0,
"end_time": "2017-09-17T07:00:00+0000"
},
{
"value": 0,
"end_time": "2017-09-18T07:00:00+0000"
}
],
"id": "17841405034517108/insights/phone_call_clicks/day",
"description": "Total number of taps on the call link in this profile",
"name": "phone_call_clicks",
"title": "Phone Call Clicks"
},
{
"values": [
{
"value": 0,
"end_time": "2017-09-17T07:00:00+0000"
},
{
"value": 0,
"end_time": "2017-09-18T07:00:00+0000"
}
],
"id": "17841405034517108/insights/text_message_clicks/day",
"description": "Total number of taps on the text message link in this profile",
"name": "text_message_clicks",
"title": "Text Message Clicks"
},
{
"values": [
{
"value": 0,
"end_time": "2017-09-17T07:00:00+0000"
},
{
"value": 0,
"end_time": "2017-09-18T07:00:00+0000"
}
],
"id": "17841405034517108/insights/get_directions_clicks/day",
"description": "Total number of taps on the directions link in this profile",
"name": "get_directions_clicks",
"title": "Get Directions Clicks"
},
{
"values": [
{
"value": 0,
"end_time": "2017-09-17T07:00:00+0000"
},
{
"value": 1,
"end_time": "2017-09-18T07:00:00+0000"
}
],
"id": "17841405034517108/insights/website_clicks/day",
"description": "Total number of taps on the website link in this profile",
"name": "website_clicks",
"title": "Website Clicks"
},
{
"values": [
{
"value": 12,
"end_time": "2017-09-17T07:00:00+0000"
},
{
"value": 20,
"end_time": "2017-09-18T07:00:00+0000"
}
],
"id": "17841405034517108/insights/profile_views/day",
"description": "Total number of unique accounts that have viewed this profile within the specified period",
"name": "profile_views",
"title": "Profile Views"
}
],
"paging": {
"previous": "",
"next": ""
}
}
ビジネスアカウントID/insights?fields=values,id,description,name,title&period=lifetime&metric=audience_gender_age,audience_locale,audience_country,audience_city,online_followers&pretty=0
ちなみに返り値の U は Unknown の略のよう。
参考: https://stackoverflow.com/questions/11315946/what-is-u-means-in-gender-value
{
"data": [
{
"values": [
{
"value": {
"F.13-17": 1,
"F.18-24": 16,
"F.25-34": 40,
"F.35-44": 4,
"F.45-54": 2,
"M.18-24": 11,
"M.25-34": 21,
"M.35-44": 8,
"M.45-54": 3,
"U.25-34": 1
},
"end_time": "2017-09-18T07:00:00+0000"
}
],
"id": "17841405034517108/insights/audience_gender_age/lifetime",
"description": "The gender and age distribution of this profile's followers",
"name": "audience_gender_age",
"title": "Gender and Age"
},
{
"values": [
{
"value": {
"ar_AR": 1,
"de_DE": 1,
"en_GB": 2,
"en_US": 11,
"es_LA": 1,
"ja_JP": 90,
"ja_KS": 1
},
"end_time": "2017-09-18T07:00:00+0000"
}
],
"id": "17841405034517108/insights/audience_locale/lifetime",
"description": "The locales by country codes of this profile's followers",
"name": "audience_locale",
"title": "Location"
},
{
"values": [
{
"value": {
"AU": 1,
"DE": 1,
"GB": 1,
"HK": 1,
"IQ": 1,
"IT": 1,
"JP": 87,
"MX": 1,
"PH": 11,
"TW": 1,
"US": 1
},
"end_time": "2017-09-18T07:00:00+0000"
}
],
"id": "17841405034517108/insights/audience_country/lifetime",
"description": "The countries of this profile's followers",
"name": "audience_country",
"title": "Audience Country"
},
{
"values": [
{
"value": {
"Baghdad, Baghdad Governorate": 1,
"Rome, Lazio": 1,
"Chofu, Tokyo": 1,
"Fukui-shi, Fukui Prefecture": 2,
"Hakodate-shi, Hokkaido": 2,
"Kadoma-shi, Osaka Prefecture": 1,
"Kakogawa-shi, Hyōgo Prefecture": 1,
"Kita-ku, Tokyo": 2,
"Maebashi-shi, Gunma Prefecture": 1,
"Setagaya-ku, Tokyo": 2,
"Shibuya-ku, Tokyo": 27,
"Shinjuku-ku, Tokyo": 4,
"Takasaki-shi, Gunma Prefecture": 1,
"Toda-shi, Saitama Prefecture": 1,
"Tokoname-shi, Aichi Prefecture": 1,
"Toshima, Tokyo": 2,
"Toyota, Aichi Prefecture": 1,
"Wako-shi, Saitama Prefecture": 1,
"Teotihuacán, State of Mexico": 1,
"Cebu City, Central Visayas": 10,
"Mandaue City, Central Visayas": 1,
"Chungho, New Taipei City": 1,
"Sendai, Miyagi Prefecture": 1,
"Shimotsuke-shi, Tochigi Prefecture": 1,
"Saitama-shi, Saitama Prefecture": 2,
"Chiba-shi, Chiba Prefecture": 1,
"Nagareyama-shi, Chiba Prefecture": 1,
"Chiyoda-ku, Tokyo": 2,
"Chuo-ku, Tokyo": 1,
"Minato-ku, Tokyo": 7,
"Shinagawa-ku, Tokyo": 1,
"Meguro-ku, Tokyo": 3,
"Ota-ku, Tokyo": 1,
"Nakano-ku, Tokyo": 2,
"Adachi-ku, Tokyo": 1,
"Kawasaki-shi, Kanagawa Prefecture": 3,
"Yokohama, Kanagawa Prefecture": 1,
"Nagoya-shi, Aichi Prefecture": 2,
"Yosa-gun, Kyoto Prefecture": 1,
"Osaka, Osaka Prefecture": 1,
"Dazaifu-shi, Fukuoka Prefecture": 1,
"Strathmore, Victoria": 1,
"Benningen, Bayern": 1,
"Banbury, England": 1,
"Hong Kong": 1
},
"end_time": "2017-09-18T07:00:00+0000"
}
],
"id": "17841405034517108/insights/audience_city/lifetime",
"description": "The cities of this profile's followers",
"name": "audience_city",
"title": "Audience City"
},
{
"values": [
{
"value": 0,
"end_time": "2017-09-18T07:00:00+0000"
}
],
"id": "17841405034517108/insights/online_followers/lifetime",
"description": "Total number of this profile's followers that were online during the specified period",
"name": "online_followers",
"title": "Online Followers"
}
]
}
最後に
なにか間違いあればコメントや修正リクエスト頂ければと思います。
また、自分のビジネスアカウントIDバレしてますが
特にインフルエンサーでもなんでもないのでお気になさらずどんどんみてください。