查询API

诸葛io除了提供了非常灵活的可视化分析界面外，还提供了强大、完善的查询API。

查询API包括以下四类:

• 数据统计API
• 用户查询API
• 用户行为轨迹API
• 用户群查询API

一、概述

诸葛io查询API是基于RESTful、超媒体的JSON web服务。在设计的每一步都强调了灵活性和标准遵从性，因此使用它是一件简单的事情。

二、协议

查询API的根URL是 https://saasapi.zhugeio.com/v2/

为了获得最大安全性，不支持使用非加密HTTP上的API。

使用HTTP Basic Authentication方式做访问授权，HTTP Header里加一个字段(Key/Value对): Authorization: Basic base64_auth_string

其中 base64_auth_string 的生成算法为: base64(UserName:PassWord)。 即用UserName加上冒号，加上PassWord拼接起来，再做base64转换，UserName和PassWord需申请开通API获取。

三、数据统计API

诸葛io的查询分析API是由指标、维度和条件组成的。一般来说，API的调用就是通过条件筛选得到的记录，然后按维度细分后汇总得到指标。

1. 调用方法

调用URL地址为:

https://saasapi.zhugeio.com/v2/stat/{app_id}?metrics=?&dimensions=?&conditions=?&user_filters=?

参数说明:

注意:请求的参数值需做UrlEncode。

URL请求示例: 以诸葛io官网京北商城DEMO为例，请求2017-07-01到2017-07-07每天的活跃用户数

https://saasapi.zhugeio.com/v2/stat/35510?metrics=users&dimensions=$day&conditions={"$day":["between","2017-03-01","2017-03-27"]}

2. 指标（metrics）

指标是要统计最终要得到的结果数值（求和、计数等）。

指标可以分为简单指标和复合指标两类:

• 简单指标是对查询结果进行求和、计数、平均值等运算后直接得到的结果数值；
• 复合指标是两个或多个简单指标进行加减乘除等数学运算后得到的结果数值，如事件的「活跃比」就是复合指标。（需要说明的是，API中只提供有限的复合指标的查询支持，需要更多指标的客户通过自己开发完成）

诸葛io API中常用的指标包含:

• sessions:会话数，又即访问次数或启动次数。
• users:用户数，去重唯一的用户数量。
  • 如 dimensions 参数属性包含如下值，计算结果为新增用户数，否则为活跃用户数。
    • $birth_day
    • $birth_week
    • $birth_month
• occurrences:触发次数，事件发生的次数。
• avg_occurrences_per_user:人均触发次数，某事件平均每人的触发次数。
• avg_session_length:会话平均时长，以秒为单位。
• avg(event.<attribute_name>):数值型属性的平均值，可用于事件和用户统计。
• min(event.<attribute_name>):数值型属性的最小值，可用于事件和用户统计。
• max(event.<attribute_name>):数值型属性的最大值，可用于事件和用户统计。
• sum(event.<attribute_name>):数值型属性的和，可用于事件和用户统计。
• md(event.<attribute_name>):数值型属性的中位数（median），可用于事件和用户统计。

示例如下:

"metrics":"users"

3. 分组（dimensions）

查询时可以使用分组条件对结果进行分类汇总。每次查询最多同时可以有3个分组条件，其中只能有一个事件自定义属性。

示例如下:

dimensions=$day,$utm_source

可以进行分组的维度包括:

3.1 事件维度

• $event_name:事件名。包含自定义事件和预置事件（session start和session end）
• event.<attribute_name>:事件自定义属性。
• $bucket(event.<attribute_name>):事件数值型属性的分布。
• $day:触发日期。
• $week:触发周。
• $month:触发月。
• $hour:小时。如「2017-02-21 16:00」。
• $hour_of_day:一天中的小时。如「18:00」。
• $ip_address:客户端ip地址。
• $current_page_url:当前网址。
• $country:国家。
• $province:省。
• $city:城市。

3.2 会话维度（即所在会话的session start事件的特殊维度）

• $platform:平台类型。取值:android、ios、 js、wxa（小程序）。
• $referrer_domain:来源网站（域名）。
• $referrer_url:来源网址，仅用于条件不能用于分组。
• $browser_model:浏览器类型。
• $browser_version:浏览器版本。
• $device_maker:设备品牌。
• $device_model:设备类型。
• $os:操作系统类型。
• $os_version:操作系统版本。
• $screen_x:屏幕宽度。
• $screen_y:屏幕高度。
• $utm_source:来源。
• $utm_medium:媒介。
• $utm_campaign:活动。
• $utm_content:内容。
• $utm_term:关键词。
• $carrier:运营商。
• $network:网络类型。取值:2g、3g、4g、wifi。不区分大小写。

3.3 用户维度

• $birth_day:用户的新增日期，或会话的开始日期。
• $birth_week:用户的新增周，或会话的开始周。
• $birth_month:用户的新增月份，或会话的开始月份。
• $is_anonymous:是否匿名。
• $last_active_day:最后的活跃日期。
• user.<attribute_name>:用户自定义属性。

4. 过滤条件（conditions）

查询可以通过在一个或多个维度上指定筛选的值或范围，来缩小结果统计的范围。

每个查询最多可以设置5个过滤条件，条件之间为「与」关系，不支持「或」和括号运算。

每个过滤条件是一对key:value，key是一个维度属性（dimension），value由运算符和属性值构成。

示例如下:

"conditions":{"$day":["between","2017-01-01","2017-01-31"],"$city":["==","北京"]}

支持以下运算符:

["==","value"]    // 等于、是。适用于字符型、数值型维度
["!=","value"]    // 不等于、不是。适用于字符型、数值型维度
["in","value1","value2"...]        // 是其中之一。适用于字符型、数值型维度
["not_in","value1","value2"...]    // 不是其中之一。适用于字符型、数值型维度
["between","value1","value2"]    // 介于两者之间。适用于日期时间型、数值型维度
["begin_with","value"]    // 开始是。适用于字符型维度
["end_with","value"]    // 结束是。适用于字符型维度
["contains","value"]    // 包含。适用于字符型维度
["<","value"]    //适用于日期时间型、数值型维度
[">","value"]    //适用于日期时间型、数值型维度
["<=","value"]    //适用于日期时间型、数值型维度
[">=","value"]    //适用于日期时间型、数值型维度

5. 用户筛选（user_filters）

简单的用户筛选可以通过过滤条件实现。复杂的用户条件筛选可以使用用户群来进行。 每次查询最多可以指定一个用户群作为用户筛选条件。

注:本次项目中统计API仅实现用户组筛选，不实现用户筛选和事件筛选。

示例如下:

"user_filters":{"$user_group":"用户群名称"}

6. 统计结果

统计结果由以下部分构成:

• results:统计结果，按分组展开
• query:完整的查询条件

示例如下:

{
  "results": [
    {
      "$day": "2014-09-01",
      "$utm_source": "百度",
      "users": 142
    },
    {
      "$day": "2014-09-01",
      "$utm_source": "谷歌",
      "users": 5506
    },
    {
      "$day": "2014-09-02",
      "$utm_source": "百度",
      "users": 3875
    },
    {
      "$day": "2014-09-02",
      "$utm_source": "谷歌",
      "users": 5506
    }
  ],
  "app_id": [
    "461"
  ],
  "created_at": "2015-09-08T14:30:29Z",
  "expires_at": "2015-09-16T05:17:55Z",
  "query": {
    "metrics": [
      "users"
    ],
    "dimensions": [
      "$day"
    ],
    "conditions": {
      "$day": [
        "between",
        "2015-01-01",
        "2015-01-08"
      ]
    },
    "app_id": [
      "461"
    ]
  },
  "_links": {
    "self": {
      "href": "当前查询url"
    },
    "app": {
      "href": "app的url"
    }
  }
}

7. 常见查询请求示例

新增用户数

metrics:        "users",
dimensions:        "$birth_day",
conditions:        {"$birth_day":["between","2017-01-01","2017-01-31"]}

新增用户数（按来源网站）

metrics:        "users",
dimensions:        "$birth_day,$referrer_domain",
conditions:        {"birth_day":["between","2017-01-01","2017-01-31"]}

活跃用户数

metrics:        "users",
dimensions:        "$day",
conditions:        {"day":["between","2017-01-01","2017-01-31"]}

某个事件的触发人数

metrics:        "users",
dimensions:        "$day",
conditions:        {"day":["between","2017-01-01","2017-01-31"],"$event_name":["==","登录"]}
user_filters:        {"$user_group":"用户群名称"}

四、用户查询API

用户查询API用来查询符合条件的用户。

1. 查询条件

查询条件可以由若干个用户属性条件和事件条件构成。

2. 调用方法

调用URL地址为:

https://saasapi.zhugeio.com/v2/app_users/{app_id}/user/infos?conditions=?&sort_by=?&start_index=?&limit=?

参数说明:

注:请求的参数值需做UrlEncode。

URL请求示例:

以诸葛io官网京北商城DEMO为例，请求2017-07-01到2017-07-07触发了查看商品详情的新增用户的用户信息:

https://saasapi.zhugeio.com/v2/app_users/35510/user/infos?conditions={"$
birth_day":["between","2017-07-01","2017-07-07"],"event.查看商品详情":{},"relation":"and"}&sort_by=-$birth_day&start_index=1&limit=20

3. 用户属性条件

支持以下用户属性作为筛选条件:

• $birth_day:用户的新增日期，或会话的开始日期。
• $birth_week:用户的新增周，或会话的开始周。
• $birth_month:用户的新增月份，或会话的开始月份。
• $is_anonymous:是否匿名。
• $user_id:用户id。
• $zg_id:用户的诸葛id。
• user.<attribute_name>:用户自定义属性。 单个属性上支持的运算符与统计API支持的运算符相同。

示例:

"$birth_day":["between","2017-01-01","2017-01-31"]

4. 事件条件

事件条件是使用用户曾经发生过的行为（事件）及其特点作为条件查询用户。

事件条件除了可以用事件和会话的属性作为筛选之外，还支持两个特殊的筛选条件:

• occurrences:事件触发次数
• occurrence_days:事件触发过的天数

示例:

"event.查看商品详情": {
    "商品分类": ["in","手机","耳机"],
"$occurrences": [">=",3]
}

5. 组合条件

多个条件可以用and、or、not逻辑运算符进行连接组合使用，如:

{
    "relation": "and",
    "$birth_day":["between","2017-01-01","2017-01-31"],
"event.查看商品详情": {
    "商品分类": ["in","手机","耳机"],
"$occurrences": [">=",3]
},
"event.加入购物车": {
"$occurrences": [">=",1]
}
}

也可以嵌套使用（最多3级），如:

{
    "relation": "and",
    "$birth_day":["between","2017-01-01","2017-01-31"],
"event.查看商品详情": {"商品分类": ["in","手机","耳机"]},
"composed": {
    "relation": "or",
"event.分享": {"$day":["between","2017-01-01","2017-01-31"]},
"event.点赞": {"$day":["between","2017-01-01","2017-01-31"]}
}
}

6. 排序及其它

可以按用户属性（最多3个）进行排序，需要指定用来排序的属性和顺序。如:

[
    "+$birth_day",    // +号代表正序
    "-会员等级"    // -号代表到序
]

每次查询应指定返回结果列表中用户的起始位置(start_index)和个数(limit)。

完整的查询请求（样例）

{
"conditions": {
    "relation": "and",
    "$birth_day":["between","2017-01-01","2017-01-31"],
"event.查看商品详情": {"商品分类": ["in","手机","耳机"]},
"composed": {
    "relation": "or",
"event.分享": {"$day":["between","2017-01-01","2017-01-31"]},
"event.点赞": {"$day":["between","2017-01-01","2017-01-31"]}
}
},
"sort_by": [
    "+$birth_day",
    "-会员等级"
],
"start_index": 1,
"limit": 200
}

查询结果

{
  "results": [
    {
      "$user_id": "zhugejun@zhugeio.com",
      "$zg_id": 3112,
      "name": "诸葛君",
      "$first_visit_time": "2014-09-01 00:00:00",
      "$last_active_day": "2017-02-23",
      ...
      "name": "诸葛君"
    },
    {
      "$user_id": "zhugejun@zhugeio.com",
      "$zg_id": 3112,
      "name": "诸葛君",
      "$first_visit_time": "2014-09-01 00:00:00",
      "$last_active_day": "2017-02-23",
      ...
      "name": "诸葛君"
    },
    {
      "$user_id": "zhugejun@zhugeio.com",
      "$zg_id": 3112,
      "name": "诸葛君",
      "$first_visit_time": "2014-09-01 00:00:00 ",
      "$last_active_day": "2017-02-23",
      ...
      "name": "诸葛君"
    },
    ...
  ],
  "count": 200,
  "app_id": [
    "461"
  ],
  "created_at": "2015-09-08T14:30:29Z",
  "expires_at": "2015-09-16T05:17:55Z",
  "query": {
"conditions": {
    "relation": "and",
    "$birth_day":["between","2017-01-01","2017-01-31"],
"event.查看商品详情": {"商品分类": ["in","手机","耳机"]},
"composed": {
    "relation": "or",
"event.分享": {"$day":["between","2017-01-01","2017-01-31"]},
"event.点赞": {"$day":["between","2017-01-01","2017-01-31"]}
}
},
"sort_by": [
    "$birth_day":"desc",
    "会员等级": "desc"
],
"start_index": 1,
"limit": 200
}
}

五、用户行为轨迹API

查询单个用户的行为轨迹。

1. 调用方法

调用URL地址为:

https://saasapi.zhugeio.com/v2/users/{app_id}/behavior?$user_id=?&$begin_day=?&$end_day=?&$event_name=?

参数说明:

注*:请求的参数值需做UrlEncode。

URL请求示例:

以诸葛io官网京北商城DEMO为例，请求2017-07-01到2017-07-07事件范围为注册、登录、加入购物车、支付成功的用户行为信息:

https://saasapi.zhugeio.com/v2/users/35510/behavior?$user_id=demo@zhugeio.com&$begin_day=2017-07-01&$end_day=2017-07-07&$event_name=注册&$event_name=登录&$event_name=加入购物车&$event_name=支付成功

2. 查询条件

需指定以下条件进行查询:

• $user_id（或$zg_id）
• $begin_day、$end_day:指定的日期范围，每次请求最大能查连续14天的行为轨迹。可选，默认为最近1天
• $event_name:事件范围。可选，默认为全部事件

举例:

{
"$user_id": "zhugejun@zhugeio.com",
"$begin_day":"2017-02-01",
"$end_day: "2017-02-14",
"$event_name":["注册","登录","加入购物车","支付成功"],
}

查询结果

{
  "results": {
    "user_profile": {
      "$user_id": "zhugejun@zhugeio.com",
      "$zg_id": 3112,
      "name": "诸葛君",
      "$birth_day": "2014-09-01",
      "$last_active_day": "2017-02-23",
      ...
      "name": "诸葛君"
    },
    "events": [
    {
      "$event_name": "登录",
      "$date_time": "2014-09-01 12:01:21.1234",
      "手机号": "13888888888",
      "结果": "成功",
      ...
      "$current_page_url": "http://akdjdkf/adjfdlf",
      "$ip_address": "121.121.121.121",
      "$country": "中国",
      "$province": "北京",
      "$city": "朝阳区"
},
    {
      "$event_name": "加入购物车",
      "$date_time": "2014-09-01 12:01:21.1234",
      "商品名称": "苹果 iPhone 9",
      "商品分类": "手机",
      ...
      "$current_page_url": "http://akdjdkf/adjfdlf",
      "$ip_address": "121.121.121.121",
      "$country": "中国",
      "$province": "北京",
      "$city": "朝阳区"
},
    {
      "$event_name": "支付成功",
      "$date_time": "2014-09-01 12:01:21.1234",
      "订单号": "888888",
      "金额": 9999.00,
      ...
      "$current_page_url": "http://akdjdkf/adjfdlf",
      "$ip_address": "121.121.121.121",
      "$country": "中国",
      "$province": "北京",
      "$city": "朝阳区"
}
    ]
  },
  "app_id": [
    "461"
  ],
  "created_at": "2015-09-08T14:30:29Z",
  "expires_at": "2015-09-16T05:17:55Z",
  "query": {
"$user_id": "zhugejun@zhugeio.com",
"$begin_day":"2017-02-01",
"$end_day: "2017-02-14",
"$event_name":["注册","登录","加入购物车","支付成功"],
   }
}

六、用户群查询API

用户群查询API用来查询在分析平台中创建的用户群；获取用户群列表和用户群用户。

1. 获取用户群列表

1. 1调用方法

调用URL地址为：

https://saasapi.zhugeio.com/v2/api_user_groups/{app_id}/user/groups?group_name=?&start_index=?&limit=?

参数说明:

注:请求的参数值需做UrlEncode。

URL请求示例:

以诸葛io官网电商DEMO为例，请求获取用户群列表:

https://saasapi.zhugeio.com/v2/api_user_groups/35510/user/groups?start_index=1&limit=5

查询结果样例：

{
    "results": [
        {
            "group_id": 102491,
            "group_name": "付费购买客户",
            "user_count": 2729,
            "create_time": "2020-04-13 15:10:06"
        },
        {
            "group_id": 102490,
            "group_name": "匿名访客",
            "user_count": 64172,
            "create_time": "2020-04-13 15:09:40"
        },
      ...
    ],
    "count": 78,
    "app_id": [
        "35510"
    ],
    "created_at": "2020-04-24T10:50:59Z",
    "expires_at": "2020-04-24T10:50:59Z",
    "start_index": 1,
    "limit": 5
}

2.获取用户群用户

2.1调用方法

调用URL地址为：

https://saasapi.zhugeio.com/v2/api_app_users/{app_id}/user/infos?group_id=?&start_index=?&limit=?

参数说明:

注:请求的参数值需做UrlEncode。

URL请求示例:

以获取用群列表的返回结果样例中的用户群为例，请求获取用户群用户:

https://saasapi.zhugeio.com/v2/api_app_users/35510/user/infos?group_id=102491&start_index=1&limit=1000

查询结果样例：

{

    "results": [
        {
            "Add": null,
            "first_utm_content": "sogo_CPL存储卡",
            "白条": "5849.7",
            "京北豆": "1516",
            "zg_id": 7228996,
            "current_area": "上海",
            "first_utm_campaign": "sogo_CPL",
            "current_browser_brand": "Chrome",
            "user_referer_url": "合作渠道1",
            "小白信用": null,
            "community": null,
            "current_browser_version": "21",
            "first_utm_medium": "CPL",
            "current_resolution_h": "1050",
            "weixin": null,
            "信用等级": "94.8",
            "user_id": "c27ada9c-ccd2-11e6-acca-90b11c1820bf",
            "first_utm_source": "sogo",
            "current_resolution_l": "1400",
            "current_app_channel": "server",
            "name": "朱淑咏",
            "会员等级": "金牌会员",
            "last_visit_time": "2020-04-23 12:39:14",
            "birthday": null,
            "first_utm_term": "存储卡",
            "first_visit_time": "2020-03-24 03:42:35",
            "current_country": "中国",
            "duration": "1606000",

          ...
        },
       ...
    ], 
    "expires_at": "2020-04-24T10:55:41Z",
    "start_index": 1,
    "query": {
        "group_id": [
            "102491"
        ]
    },
    "count": 2729,
    "limit": 1000,
    "created_at": "2020-04-24T10:55:15Z",
    "app_id": 35510
}

七、错误提示

当请求或执行出现错误时，采用http状态码、错误编码、错误信息等方式进行友好的错误提示。

八、限制