Data APIs are open to all verified Official Accounts. With data APIs, developers can get data that is similar to but more flexible than that of the statistics module in the Official Accounts Platform and can also perform advanced processing operations as needed.
In the Official Account login authorization mechanism, "Article Summary" APIs belong to the broadcast and notification authorizations set.
Notes:
1. The API's Official Account database only stores data after December 1, 2014. Data before this time may not be found or is untrusted dirty data.
2. Developers should save the data obtained by calling the API in their own databases. This will speed up the subsequent visit speed while reducing unnecessary loss in Weixin API call.
3. When you call the API getarticlesummary, the data is collected only when the number of intermediate page readers, the number of original page readers, the number of persons who shared and forwarded the article, and the number of times the article is shared, forwarded and added to favorites are equal to or greater than 3. Otherwise, the data is not collected.
4. To ensure that the Official Account data is calculated and processed, query the previous-day data each day before 08:00.
"Article Summary" APIs refer to the APIs that get the article summary data in the data statistics module of the Official Accounts Platform. For the specific APIs, see the following list:
| API Name | Maximum Time Span | API Calling Address (starting with https) |
|---|---|---|
| getarticlesummary | 1 | https://api.weixin.qq.com/datacube/getarticlesummary?access_token=ACCESS_TOKEN |
| getarticletotal | 1 | https://api.weixin.qq.com/datacube/getarticletotal?access_token=ACCESS_TOKEN |
| getuserread | 3 | https://api.weixin.qq.com/datacube/getuserread?access_token=ACCESS_TOKEN |
| getuserreadhour | 1 | https://api.weixin.qq.com/datacube/getuserreadhour?access_token=ACCESS_TOKEN |
| getusershare | 7 | https://api.weixin.qq.com/datacube/getusershare?access_token=ACCESS_TOKEN |
| getusersharehour | 1 | https://api.weixin.qq.com/datacube/getusersharehour?access_token=ACCESS_TOKEN |
The maximum time span is the maximum time range in which data can be acquired when an API is called. For example, a maximum time span of 7 means that data of the past 7 days can be acquired at a time. The actual value of access_token is obtained via the "Get access_token" API.
API Request Format
"Article Summary" APIs (including the above APIs) post the following sample packet to API calling address:
{
"begin_date": "2014-12-08",
"end_date": "2014-12-08"
}
Call Parameters
| Parameter | Required | Description |
|---|---|---|
| access_token | Yes | The credential for API call |
| begin_date | Yes | Gets the start date of the data. The difference between begin_date and end_date must be less than the "maximum time span" (for example, when the maximum time span is 1, the difference between begin_date and end_date can only be 0). Otherwise, an error will occur. |
| end_date | Yes | Gets the end date of the data. The maximum value of end_date is yesterday. |
Response Description
For a successful request, the response JSON packet of the API getarticlesummary is as follows:
{
"list": [
{
"ref_date": "2014-12-08",
"msgid": "10000050_1",
"title": "12.27 DiLi Daily Report",
"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
}
//Data such as the number of reads of all broadcasted articles on this day will be listed.
]
}
For a successful request, the response JSON packet of the API getarticletotal is as follows. Note: 1. In details, the value for each day is the article data up to the current day (not on the current day). 2. The differences between getarticlesummary and getarticletotal are as follows:
1. The former gets data such as the number of reads of all broadcasted articles on the current day.
2. The latter gets data such as the number of reads of all broadcasted articles up to the day when this API is called (that must be within 7 days from when articles are broadcasted). For example, if the number of reads on the 1st, 2nd and 3rd day of December is 10,000, respectively, then getarticletotal gets the following data: 10,000 reads up to December 1 24:00, 20,000 reads up to December 2 24:00, and 30,000 reads up to December 3 24:00.
{
"list": [
{
"ref_date": "2014-12-14",
"msgid": "202457380_1",
"title": "Painting Lost in 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
}, //Followed by data on stat_date (within 7 days) from ref_date (the date when articles are broadcasted) to the API calling date
]
},//Followed by data of broadcasted articles on ref_date (the date when articles are broadcasted) between begin_date and end_date
]
}
For a successful request, the response JSON packet of the API getuserread is as follows:
{
"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
}, //Followed by data of ref_date between begin_date and end_date
]
}
For a successful request, the response JSON packet of the API getuserreadhour is as follows:
{
{
"list": [
{
"ref_date": "2015-07-14",
"ref_hour": 0,
"user_source": 0,
"int_page_read_user": 6391,
"int_page_read_count": 7836,
"ori_page_read_user": 375,
"ori_page_read_count": 440,
"share_user": 2,
"share_count": 2,
"add_to_fav_user": 0,
"add_to_fav_count": 0
},
{
"ref_date": "2015-07-14",
"ref_hour": 0,
"user_source": 1,
"int_page_read_user": 1,
"int_page_read_count": 1,
"ori_page_read_user": 0,
"ori_page_read_count": 0,
"share_user": 0,
"share_count": 0,
"add_to_fav_user": 0,
"add_to_fav_count": 0
},
{
"ref_date": "2015-07-14",
"ref_hour": 0,
"user_source": 2,
"int_page_read_user": 3,
"int_page_read_count": 3,
"ori_page_read_user": 0,
"ori_page_read_count": 0,
"share_user": 0,
"share_count": 0,
"add_to_fav_user": 0,
"add_to_fav_count": 0
},
{
"ref_date": "2015-07-14",
"ref_hour": 0,
"user_source": 4,
"int_page_read_user": 42,
"int_page_read_count": 100,
"ori_page_read_user": 0,
"ori_page_read_count": 0,
"share_user": 0,
"share_count": 0,
"add_to_fav_user": 0,
"add_to_fav_count": 0
}
//Followed by the data of increasing ref_hour within 24 hours a day
]
}
For a successful request, the response JSON packet of the API getusershare is as follows:
{
"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
}//Followed by data of different share_scene (where an article is shared to) and ref_date (between begin_date and end_date)
]
}
For a successful request, the response JSON packet of the API getusersharehour is as follows:
{
"list": [
{
"ref_date": "2014-12-07",
"ref_hour": 1200,
"share_scene": 1,
"share_count": 72,
"share_user": 4
}//Followed by data of different share_scene and increasing ref_hour. Since the maximum time span is 1, ref_date is a fixed value.
]
}
Response Parameters
| Parameter | Description |
|---|---|
| ref_date | The date of the data, between begin_date and end_date |
| ref_hour | The hour of the data, from 000 to 2300, representing [000,100) to [2300, 2400), respectively, that is, the first hour and the last hour of each day |
| stat_date | The statistics date. In the API getarticletotal, ref_date refers to the date articles are broadcasted, and stat_date refers to the date the data is collected. |
| msgid | Note: msgid is composed of msgid (the article ID, which is the msg_data_id returned after the broadcast API is called) and index (article sequence index). Take 12003_3 as an example: 12003 is msgid, which is the ID of the broadcasted articles. 3 is the index, indicating the 3rd broadcasted article if a total of 5 articles are broadcasted. |
| title | The article's title |
| int_page_read_user | The number of readers of the article page that users are redirected to after tapping the broadcasted article card |
| int_page_read_count | The number of reads of the article page |
| ori_page_read_user | The number of readers of the original page that users are redirected to after tapping Read More. 0 indicates no original page. |
| ori_page_read_count | The number of reads of the original page |
| share_scene | The source an article is shared from. 1: Weixin friends; 2: Moments; 3: Tencent Weibo; 255: Others. |
| share_user | The number of persons an article is shared to |
| share_count | The number of times an article is shared |
| add_to_fav_user | The number of persons who add an article to Favorites |
| add_to_fav_count | The number of times an article is added to Favorites |
| Explanations to the fields in getarticletotal | intpagefromsessionreaduser: The number of readers from the Official Account chat |
intpagefromsessionreadcount: The number of reads from the Official Account chat intpagefromhistmsgreaduser: The number of readers from the Message History page intpagefromhistmsgreadcount: The number of reads from the Message History page intpagefromfeedreaduser: The number of readers from Moments intpagefromfeedreadcount: The number of reads from Moments intpagefromfriendsreaduser: The number of readers of the article forwarded by Weixin friends intpagefromfriendsreadcount: The number of reads of the article forwarded by Weixin friends intpagefromotherreaduser: The number of readers from other sources intpagefromotherreadcount:The number of reads from other sources intpagefromkanyikanreaduser: The number of readers from Top Stories intpagefromkanyikanreadcount: The number of reads from Top Stories intpagefromsouyisoureaduser: The number of readers from Search intpagefromsouyisoureadcount: The number of reads from Search feedsharefromsessionuser: The number of persons who forwarded the article from an Official Account chat to Moments feedsharefromsessioncnt: The number of times the article is forwarded from the Official Account chat to Moments feedsharefromfeeduser: The number of persons who forwarded the article from Moments to Moments feedsharefromfeedcnt: The number of times the article is forwarded from Moments to Moments feedsharefromotheruser: The number of persons who forwarded the article from other sources to Moments feedsharefromothercnt: The number of times the article is forwarded from other sources to Moments | | target_user | The number of target users, approximately equal to the number of followers (excluding those blocked in the blacklist and those fail to receive the article due to exceptions) | | user_source | Indicates where the article is shared to. This field is available only when getuserreadhour is called. 0: Chat; 1: Weixin friends; 2: Moments; 3: Tencent Weibo; 4: Message History; 5: Others; 6: Top Stories; 7: Search |
When an error occurs, Weixin will return the error code and other information. For the specific error code, see Common Error Codes.