Rich Media Data API
Back

From WeChat Official Account Admin Platform
Jump to: navigation, search

Through these data APIs, developers can obtain data similar to but more flexible than data provided on the WeChat Official Account Admin Platform web site and then perform additional advanced processing as required.

The Data APIs are only available to developers with a certified official account.

Notes:

1. Official account data provided from the data APIs only includes data after December 1, 2014. Any data provided from  before this date will likely be inaccurate.
2. In order to speed up subsequent user access and reduce API calling time, we suggest developers store data obtained through API calls in their own databases.

Rich media data APIs contain API calls used to obtain data about rich media messages from data statistical modules on the WeChat Official Account Admin Platform. The provided APIs are as follows:

API Name Maximum Time Span API Calling URL (https Required)
Obtain daily data for a rich media message (getarticlesummary) 1 https://api.weixin.qq.com/datacube/getarticlesummary?access_token=ACCESS_TOKEN
Obtain cumulative data for a rich media message (getarticletotal) 1 https://api.weixin.qq.com/datacube/getarticletotal?access_token=ACCESS_TOKEN
Obtain detailed data for a rich media message (getuserread) 3 https://api.weixin.qq.com/datacube/getuserread?access_token=ACCESS_TOKEN
Obtain detailed data for a rich media message by hour (getuserreadhour) 1 https://api.weixin.qq.com/datacube/getuserreadhour?access_token=ACCESS_TOKEN
Obtain sharing data for a rich media message (getusershare) 7 https://api.weixin.qq.com/datacube/getusershare?access_token=ACCESS_TOKEN
Obtain sharing data for a rich media message by hour (getusersharehour) 1 https://api.weixin.qq.com/datacube/getusersharehour?access_token=ACCESS_TOKEN

The maximum time span indicates the maximum time range for obtaining data during one API calling event. For example, if the maximum time span is 7, data from up to 7 days can be obtained once. Please obtain the actual value of access_token through "Obtain access_token".

Request Description

Rich media data APIs (including all APIs in the list) should use the HTTP POST method to send parameters to the corresponding API calling URL. A sample set of parameters is provided below:

{ 
    "begin_date": "2014-12-08", 
    "end_date": "2014-12-08"
}

Calling Parameter Description

Parameter Required Description
access_token Yes Access token providing authorization to the calling API
begin_date Yes Start date for queried data. The difference between begin_date and end_date should be less than the maximum time span (for example, if the maximum time span is 1, begin_date and end_date should be identical); otherwise, an error will be reported.
end_date Yes End date for queried data, yesterday's date as the maximum possible value

Return Description

An example of a successful JSON response from the getarticlesummary API is provided below:

{ 
    "list": [ 
        { 
            "ref_date": "2014-12-08", 
            "msgid": "10000050_1", 
            "title": "DiLi Daily on December 27th", 
            "int_page_read_user": 23676, 
            "int_page_read_count": 25615, 
            "ori_page_read_user": 29, 
            "ori_page_read_count": 34, 
            "share_user": 122, 
            "share_count": 994, 
            "add_to_fav_user": 1, 
            "add_to_fav_count": 3
        } 
 	 // Below would be data on the number of view for all articles (including articles sent to groups) up until that day
    ]
}

An example of a successful JSON response from the getarticletotal API is provided below (note that the value corresponding to each day in the details is the number of article views up to that day, not the number of article views on that day). Note that getarticlesummary and getarticletotal have the following important differences:

1. getarticlesummary obtains the view count for all articles (including articles linked in a rich media message contain a group of articles) on a day.
2. getarticletotal obtains the view count of an article (including articles linked in a rich media message contain a group of articles) from the send date up to the date the API is called (up to 7 days). For example, if an article is sent on December 1st and the view count is 10,000 each fro December 1st, December 2nd and December 3rd, the data obtained by getarticletotal is 10,000 till 00:00 of December 2nd, 20,000 till 00:00 of December 3rd, and 30,000 till 00:00 of December 4th.
{ 
   "list": [ 
       { 
           "ref_date": "2014-12-14", 
           "msgid": "202457380_1", 
           "title": "Lost of Drawings by Malaysia Airlines", 
           "details": [ 
               { 
                   "stat_date": "2014-12-14", 
                   "target_user": 261917, 
                   "int_page_read_user": 23676, 
                   "int_page_read_count": 25615, 
                   "ori_page_read_user": 29, 
                   "ori_page_read_count": 34, 
                   "share_user": 122, 
                   "share_count": 994, 
                   "add_to_fav_user": 1, 
                   "add_to_fav_count": 3,
                   "int_page_from_session_read_user": 657283, 
                   "int_page_from_session_read_count": 753486, 
                   "int_page_from_hist_msg_read_user": 1669, 
                   "int_page_from_hist_msg_read_count": 1920, 
                   "int_page_from_feed_read_user": 367308, 
                   "int_page_from_feed_read_count": 433422, 
                   "int_page_from_friends_read_user": 15428, 
                   "int_page_from_friends_read_count": 19645, 
                   "int_page_from_other_read_user": 477, 
                   "int_page_from_other_read_count": 703, 
                   "feed_share_from_session_user": 63925, 
                   "feed_share_from_session_cnt": 66489, 
                   "feed_share_from_feed_user": 18249, 
                   "feed_share_from_feed_cnt": 19319, 
                   "feed_share_from_other_user": 731, 
                   "feed_share_from_other_cnt": 775
               }, 
	// Data with stat_date matching the period from ref_date (rich media message sent date) up to the date the API is called" (up to 7 days) would be included below
           ]
       },
	// Data about rich media messages containing a group of articles from ref_date (rich media message sent date) between begin_date and end_date would be included below
   ]
}

An example of a successful JSON response from the getuserread API is provided below:

{ 
   "list": [ 
       { 
           "ref_date": "2014-12-07", 
           "int_page_read_user": 45524, 
           "int_page_read_count": 48796, 
           "ori_page_read_user": 11, 
           "ori_page_read_count": 35, 
           "share_user": 11, 
           "share_count": 276, 
           "add_to_fav_user": 5, 
           "add_to_fav_count": 15
       }, 
	// Below would be data with ref_date being a value between begin_date and end_date
   ]
}

An example of a successful JSON response from the getuserreadhour API is provided below:

{ 
   "list": [ 
       { 
           "ref_date": "2014-12-07", 
           "ref_hour": 1200, 
           "int_page_read_user": 0, 
           "int_page_read_count": 0, 
           "ori_page_read_user": 4, 
           "ori_page_read_count": 25517, 
           "share_user": 4, 
           "share_count": 96, 
           "add_to_fav_user": 1, 
           "add_to_fav_count": 3
       }
 	//Below would be data for each hour in the day with ref_hour incrementing hour-by-hour
   ]
}

An example of a successful JSON response for the getusershare API is provided below:

{ 
   "list": [ 
       { 
           "ref_date": "2014-12-07", 
           "share_scene": 1, 
           "share_count": 207, 
           "share_user": 11
       }, 
       { 
           "ref_date": "2014-12-07", 
           "share_scene": 5, 
           "share_count": 23, 
           "share_user": 11
       }
	// Below would be data with a different share_scene, or with ref_date being a value between begin_date and end_date
   ]
}

An example of a successful JSON response for the getusersharehour API is as follows:

{ 
   "list": [ 
       { 
           "ref_date": "2014-12-07", 
           "ref_hour": 1200, 
           "share_scene": 1, 
           "share_count": 72, 
           "share_user": 4
       }
	// Below would be data with a different share_scene, or with ref_hour gradually incrementing hour-by-hour. As the maximum time span is 1, ref_date is a fixed value.
   ]
}

Return Parameter Description

Parameter Description
ref_date Date of the data, between begin_date and end_date
ref_hour Hour of the data, from 000 to 2300, indicating from [000,100) (first hour of each day) to [2300,2400) (last hour of each day)
stat_date Date of data statistics, with ref_date in getarticletotal API indicating the date in the rich media message is sent
msgid Composed of msgid (rich media message ID) and index (article index). Such as 12003_3, 12003 indicates the rich media message ID, 3 indicates the article index within the rich media message (assuming that this rich media message includes five articles)
title Title of the rich media message
int_page_read_user Number of followers who viewed the article web page (by clicking the rich media message)
int_page_read_count Number of views of the article web page
ori_page_read_user Number of followers who viewed the original web page (by clicking "Read more" on the article web page), 0 if there is no original web page
ori_page_read_count View count of the original web page
share_scene Share type

1: Shared to a chat, 2: Shared to Moments, 3: Shared to Weibo, 255: Other

share_user Number of followers who shared the article web page
share_count Number of times the article web page has been shared
add_to_fav_user Number of followers who favorited the article web page
add_to_fav_count Number of times for article web page favorited
Description of fields in the API of obtaining total rich media broadcast data

intpagefromsessionreaduser Number of users viewing the official account session
intpagefromsessionreadcount Number of views for the official account session
intpagefromhistmsgreaduser Number of users viewing the history message page
intpagefromhistmsgreadcount Number of views for the history message page
intpagefromfeedreaduser Number of users viewing Moments
intpagefromfeedreadcount Number of views for Moments
intpagefromfriendsreaduser Number of users viewing chat sharing
intpagefromfriendsreadcount Number of views for chat sharing
intpagefromotherreaduser Number of users viewing other scenarios
intpagefromotherreadcount Number of views for other scenarios

feedsharefromsessionuser Number of users sharing the official account session on Moments
feedsharefromsessioncnt Number of sharings of the official account session on Moments
feedsharefromfeeduser Number of users sharing on Moments from Moments
feedsharefromfeedcnt Number of sharings on Moments from Moments
feedsharefromotheruser Number of users sharing on Moments from other scenarios
feedsharefromothercnt Number of sharings on Moments from other scenarios

target_user Number of targeted users, usually equal to the total number of followers (minus followers added to the blacklist or who failed to receive messages due to abnormal operation)
user_source Exists only when the data of rich media viewing over time is obtained, indicating the entry for a user to view the rich media message. 0: session; 1: chat; 2: Moments; 3: Tencent Weibo; 4: history message page; 5: other

An error code will be returned upon failure. For details about error codes, please see Return Codes.

Developer Guide
Custom-defined Menu
WeChat JS-SDK