TalkingData：API简介

1、用途

TalkingData App Analytics（应用统计分析）向您开放的数据API，帮助直接通过服务端调用来获得计算好的指标结果；这样您可以不受TalkingData报表页面束缚，根据自己的需要来组织自己需要的报表，亦或将您认为重要的指标入库保存。

数据API可帮助您获得这些能力：

• 报表页面中几乎所有的数据指标都可以通过API获得

• 支持实时数据，今日数据随时可调用获得实时结果

• 支持数据筛选，例如只查某一特定渠道、版本数据刷下载量好评

2、如何开通

数据API的开通按应用进行：为每款要调用数据的产品申请”Accesskey”后，即可携带”Accesskey”来调用这款产品的数据了。

请注意”Accesskey”的保密，泄露给他人可能造成数据的泄漏。为了调用的安全，在开通时您可提供访问数据接口的IP地址，来避免他人仿冒查询。

您需要在报表页面中申请接口，位置如下：

登录进入应用统计分析 ——> 选择您的任意一款产品进入报表页面 ——> 点开左菜单中的”设置”项目，进入”数据接口” ——> 点击”申请接入码”来为这款产品开通API

接口说明

1、接口描述

调用方法

以HTTP的Post方式请求接口URL，在HTTP的body中以JSON格式传入查询参数。在Response中获取数据结果，结果同样是JSON格式。编码请使用UTF-8。刷talkingdata

接口URL：https://api.talkingdata.com/metrics/app/v1

在body中传入查询参数，参数名一律小写，带*号为必填：

{
 "accesskey": "fb46c6980e294be483fa********be35"// *填写应用的接入码
"metrics":["newuser"], // *填写要查询的指标项
"groupby":"daily", // *填写数据维度，即数据分组方式
"filter":{ // *数据筛选条件
 "start":"2015-04-14",// *查询时期的起始日
 "end":"2015-04-15", // *查询时期的截止日
 "platformids":[1,2], //限定要查询的系统平台
 "versions":["1.0","2.0"], //限定应用版本号
 "channelids":[1605,1607], //限定查询渠道
 "eventids":["clear","addCar"], //限定查询的事件id
 "pagenames":["index","pay"] //限定查询的页面名
 },
"order":"desc",// 数据结果排序方式，除按时间分组外默认倒序
"limit":10, // 限定返回数据的条数
"sum":true, // 返回结果中给出数据总和 
"avg":false // 返回结果中给出数据的平均值
 }

参数说明

参数	子参数	含义和格式	必填
accesskey		产品accesskey，向平台申请获得	是
metrics		要查询的数据指标	是
groupby		查询指标时的数据分组形式，比如传入”daily”即代表按”日”进行分组，返回结果就是查询期每日的数据量，每日一行	是
filter	start	查询期的起始时间,格式：yyyy-MM-dd	是
	end	查询期的结束时间,格式：yyyy-MM-dd	是
	platformids	平台过滤条件，支持多个平台，1代表Android，2代表iOS，4代表WinPhone，16代表HTML5，不填查询全平台	否
	versions	版本过滤条件，支持多个版本	否
	channelids	渠道过滤条件，支持多个渠道	否
	eventids	事件过滤条件，支持多个事件。	否
		限定需要查询的eventid是哪些事件
	pagenames	受访页面过滤条件，支持多个页面名。	否
		限定需要查询的页面有哪些
order		排序方式：按照结果数值大小desc-大到小，asc-小到大	否
		如果您选择的查询维度是日期方式：则此参数无效，因日期默认正序
		默认值：正序
limit		限定数据返回条数，如groupby方式选择了以机型方式分组，数据结果将是每个机型一行数据，limit可限制只返回多少条机型。	否
		默认值1000，可传入更小的值
sum		是否对结果数据求和，true表示需要，false表示不需要	否
		默认为不需要
avg		是否对结果数据求平均，true表示需要，false表示不需要	否
		默认为不需要

调用限制

为了所有用户都能获得最好的调用体验，调用时请注意如下限制： • 接口访问频次：同一IP每10秒可访问一次 • 分组为daily的查询，时期跨度不能超过180天。否则只会返回180天的数据，以起始时间计算。 • 除时间外的groupby方式，返回结果行数最大1000条。 • 只有您设定的IP地址，才能访问该产品的数据接口。

2、详细参数

在调用接口时，最重要的是metrics和groupby参数，这两个参数决定了您要以如何的的方式查询哪一项指标。以下是支持的指标和分组方式。app运营数据采集

• metrics支持范围 以下是传入metrics参数时可以支持的指标列表

类型	metrics参数	含义
用户类	newuser	查询新增用户数
	activeuser	查询活跃用户数
	versionupuser	全版本上升级用户数，必须传一个版本参数
	wau	某日的近7日活跃用户数，只支持groupby为daily的查询
	mau	某日的近30日活跃用户数，只支持groupby为daily的查询
	totaluser	查询截至某日的累计用户数, 只支持groupby为daily的查询
	bounceuser	一次性用户数
启动类	session	启动次数
	sessionlength	汇总的使用时长
	avgsessionlength	平均每次启动使用时长
留存类	day1retention	新增用户次日留存率
（特别注意：此类型查询只支持groupby为daily的查询）	day3retention	新增用户3日留存率
	day7retention	新增用户7日留存率
	day14retention	新增用户14日留存率
	day30retention	新增用户30日留存率
	dauday1retention	活跃用户次日留存率
	dauday3retention	活跃用户3日留存率
	dauday7retention	活跃用户7日留存率
	dauday14retention	活跃用户14日留存率
	dauday30retention	活跃用户30日留存率
	day7churnuser	某日的7日不使用流失用户数
	day14churnuser	某日的14日不使用流失用户数
	day7backuser	7日以上流失用户中的回流用户
	day14backuser	14日以上流失用户中的回流用户
页面类	pageview	页面访问次数，只支持pagename的分组方式
	Pageviewuser	页面访问人数，只支持pagename的分组方式
	pageviewlength	页面访问的汇总时长，只支持pagename的分组方式
	avgpageviewlength	页面的平均每次访问时长，只支持pagename的分组方式
事件类	events	事件次数，只支持eventid,eventlabel,daily的分组方式
	eventuser	事件人数，只支持eventid,daily的分组方式

• groupby支持范围

系统支持的数据groupby输出方式：

类型	groupby参数	含义
时间	daily	查询的指标，按每日数值输出结果
	hourly	查询的指标，按每小时数值输出结果（目前仅支持newuser、session两个指标）
	whole	查询的指标，整个查询期输出一个整体值。
		如查询活跃用户，采用whole的groupby方式查询出的结果是查询时期的跨日排重活跃，而不是简单的每日活跃用户的加和值。
通用	channelid	根据查询时期，按照每个渠道的数据值，输出结果；默认以每个渠道数值大到小倒序，最多输出1000个渠道
（仅用户类、启动类指标可用此类groupby，如：新增用户，启动次数，活跃用户）	appversion	按照每个应用的版本数据值，输出结果；默认以数值大到小倒序，最多输出1000个版本
	mobilemodel	按照每款设备机型的数据值输出结果，最多提供1000款机型
	screen	按照每种分辨率数据值输出结果，最多提供1000款机型
	geocountry	按照不同国家的数据值输出结果
	geochina	按照每个中国省市地区的数据值输出结果
	carrier	按照不同运营商的数据值输出结果
	network	按照不同联网方式的数据值输出数据
特殊分组方式	eventid	在查询事件类指标时，按照每个的eventid的数据值来给出结果
	eventlabel	在查询使用了label的事件时，按照不同label的数据值来给出结果
	pagename	在查询页面类指标时，按照每个页面的数据值来给出结果

3、接口返回

调用接口后会返回如下返回码，根据返回码来了解调用的状态：

状态码 信息 200 请求成功 400 超出访问频率限制（每10秒一次） 401 accesskey不合法或IP未授权 402 参数不合法 403 服务错误 404 不存在的metric 405 不支持的分组方式 406 App不存在

如果您的调用成功了，会获得与下方示例类似的数据结果：手游APP推广

{
"code": 200, //状态码
"message": "Request success.", //请求信息
"result": [{ //返回结果集
 "daily": "2015-04-01",
 "newuser": 100
}]
}

4、辅助接口

调用接口时，会用到filter 条件来指定只查询部分 渠道、版本、事件、页面 的数据，您需要知道要查询内容的确切名称，才能指定查询。我们提供了辅助接口用于索引所有能查询的 渠道、版本、事件、页面 名称，以帮助您了解哪些条件可以查询。

检索全部版本

以HTTP的Post方式请求以下接口URL，在Response中获取所有的应用版本信息，结果根据版本登记时间由新至旧排序。 在body中可增加系统平台过滤条件，1为iOS，2为android。

接口URL： https://api.talkingdata.com/metrics/app/v1/versionlist

 {
"accesskey" : " fb46c6980e294be483faf9dc****be35", 
"filter":{
"platformids":[1,2] //*设定查询的系统平台，1代表Android，2代表iOS
 }
}

检索全部渠道

以HTTP的Post方式请求以下接口URL，body中限定要查询的平台。 示例请参考”检索全部版本”

接口URL： https://api.talkingdata.com/metrics/app/v1/channellist

返回结果示例：

{
"status": 200,
"message": "Request success.",
"result": [
 {
 "channelid": 1000, //渠道id，用作查询过滤条件
 "partnername": "channel1", //渠道名
 "registertime": "2015-03-23 16:17:58", //创建时间
 "displayname": "渠道1" //对应报表显示名
 },…
]
}

检索全部事件

以HTTP的Post方式请求以下接口URL，body中限定要查询的平台。 示例请参考”检索全部版本” 接口URL： https://api.talkingdata.com/metrics/app/v1/eventlist

返回结果示例：

{
 "status": 200,
 "message": "Request success.",
 "result": [
 {
 "eventid": "appStatusRefresh", //事件id，作为查询过滤条件
 "displayname": "appStatusRefresh", //对应报表的事件显示名
 "registertime": "2012-10-08 16:19:26"//创建时间
 },…
 ]
 }

检索全部页面app如何刷量

以HTTP的Post方式请求以下接口URL，body中限定要查询的平台。 示例请参考”检索全部版本”

接口URL： https://api.talkingdata.com/metrics/app/v1/pagelist

返回结果示例：

{
 "status": 200,
 "message": "Request success.",
 "result": [
{
 "pagename": "BatteryManagerActivity",//页面名称，用作查询过滤条件
 "pagedisplayname": "电量管理页面", //对应报表显示名
 "registertime": "2013-10-16 13:45:39" //创建时间
},…
 ]
}

查询示例

以下常用示例帮助您更好理解API接口，并仿照示例代码来构造实际查询。

• 查询新增用户趋势 示例：查询3月份中每一天的新增用户数量

{
"accesskey" : "fb46c6980e294be483faf9dc****be35",
"metrics":["newuser"], //在metrics中输入newuser即查询新用户
"groupby":"daily", //这里输入daily，规定指标按每日分组
"filter":{
 "start":"2015-03-01", //这里限定了查询的日期是3-1日～3-31日
 "end":"2015-03-31" ,
 "platformids":[1,2] //平台1，2表示Android和iOS平台汇总数据
 }
 }

返回结果：

{
 "code": 200//状态码
"message": "Request success." //请求信息
"result": [{ //返回结果集
"daily": "2015-03-01",
"newuser": 100
},{
"daily": "2015-03-02",
"newuser": 200
}, … , {
"daily": "2015-03-31",
"newuser": 1000
}]
}

查询自定义事件数据

示例1：查询3月份中所有自定义事件的发生次数

{
 "accesskey" : " fb46c6980e294be483faf9dc****be35",
 "metrics":["events"],//查询事件发生次数
 "groupby":"eventid",//以事件id作为分组条件
 "filter":{
 "start":"2015-03-01",
 "end":"2015-03-31" ,
 "platformids":[1,2]
 }
 }

返回结果：

{
"code": 200//状态码
 "message": "Request success." //请求信息
 "result": [{ //返回结果集
 "eventid": "event1",
 "events": 10000
 },{
 "eventid": "event2",
 "events": 2000
 }, … , {
 "eventid": "event8",
 "events": 1000
 }]
 }

示例2：查询一个名称为”register”的自定义事件，4月份中每一天的事件人数

{
 "accesskey" : " fb46c6980e294be483faf9dc****be35",
 "metrics":["eventuser"],//查询事件人数
 "groupby":"daily",// 查询每一天的数据值
 "filter":{ // *数据筛选条件
 "start":"2015-04-01",// *查询时期为4月份整体
 "end":"2015-04-30", 
 "eventids":["register"] //限定查询事件是register这一个
 }
 }

返回结果：

{
"code": 200//状态码
 "message": "Request success." //请求信息
 "result": [{ //返回结果集
 "daily": "2015-04-01",
 "eventuser": 100
 },{
 "daily": "2015-04-02",
 "eventuser": 200
 }, … , {
 "daily": "2015-04-30",
 "eventuser": 1000
 }]
 }

• 查询某个渠道下用户使用最多的前100机型

示例：查询3月份中渠道id为100,渠道名为appstore的用户使用最多的前100机型

{
 "accesskey" : " fb46c6980e294be483faf9dc****be35",
 "metrics":["activeuser"],//查询活跃用户
 "groupby":"mobilemodel", //查询数据按每款机型数量分组
 "filter":{
 "start":"2015-03-01",
 "end":"2015-03-31" ,
 "platformids":[1,2]，
 "channelids": [100] //限定查询数据是appstore渠道的数据，对应渠道id为100
 "order":"desc", // 结果按照数值从大到小排序
 "limit":100 // 只返回100款机型的数据
 }
 }

返回结果：

{
"code": 200//状态码
 "message": "Request success." //请求信息
 "result": [{ //返回结果集
 "mobilemodel": "iphone5S",
 "activeuser": 3000
 },{
 "mobilemodel": "iphone6 Plus",
 "activeuser": 2000
 }, … , {
 "mobilemodel": "小米1S",
 "activeuser": 1000
 }]
 }

查询一个应用版本上的活跃用户数 示例：查询3月份中版本为1.0的活跃用户数

{
 "accesskey" : " fb46c6980e294be483faf9dc****be35",
 "metrics":["activeuser"],//查询活跃用户
 "groupby":"appversion", //以版本做分组条件
 "filter":{
 "start":"2015-03-01",
 "end":"2015-03-31" ,
 "platformids":[1,2]，
 "versions": ["1.0"] //过滤版本
 }
 }

返回结果：

{
"code": 200//状态码
 "message": "Request success." //请求信息
 "result": [{ //返回结果集
 "appversion": "1.0",
 "activeuser": 3000
 }]
 }