本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑惑，请咨询您的数据咨询顾问获取一对一的协助。

查询 API 主要用于获取各种数据分析报告。

1. 调用方法

请参见 API 文档 中的调用方法描述。

2.  通用参数

2.1. 属性表达式

几乎所有的 API 都会用到属性表达式，例如按照某个属性进行过滤、分组或者聚合等等。属性包括事件属性和用户属性，事件属性使用 event.事件名.属性名 的方式，例如表示 注册渠道 这个属性的表达式如下:

event.Signup.Channel

用户属性类似，例如表示 用户性别:

user.Gender

2.2. 筛选表达式

筛选表达式同样适用于绝大多数 API，用于表示对某些事件或者用户的筛选操作，使用如下格式的 JSON 表示:

{
  // 表示 conditions 里的各个条件的关系是 或 还是 且
  "relation": "and",
  // 具体的条件列表，可以有多个
  "conditions": [{
    // 条件的左值，是一个属性表达式
    "field": "event.BuyGold.$os",
    // 条件的操作符，这里表示等于
    "function": "equal",
    // 条件的参数，根据不同的操作符可以有一个或者多个
    "params": [
      "iOS"
    ]
    }, {
    "field": "user.Gender",
    "function": "equal",
    "params": [
      "男"
    ]
  }]
}

目前支持的操作符如下:

  • equal / notEqual

        表示等于/不等于，对字符串、数值类型有效。如果 Params 有多个，则相当于 In 或者 Not In。例如想筛选出来自北京或者上海的用户:

{
  "field": "user.$city",
  "function": "equal",
  "params": ["北京", "上海"]
}
  •  isTrue / isFalse

        只对布尔类型有效。

  •  isSet / notSet

        某个属性是否有值，对字符串、数值类型有效。

  •  include

        针对集合的操作，表示包含某个元素，例如筛选出所有喜欢苹果的用户:

{
  "field": "user.FavoriteFruits",
  "function": "include",
  "params": ["Apple"]
}
  •  less / greater / between：表示小于/大于/小于且大于，其中 between 是前闭后闭的区间，只对数值类型有效。例如筛选买入黄金的价格在 230 和 232 之间的所有事件:
{
  "field": "event.BuyGold.GoldPrice",
  "function": "between",
  "params": [230, 232]
}

  • contain / notContain

        包含或者不包含，表示字符串的部分匹配，只对字符串类型有效。

  • absoluteBetween / relativeBefore / relativeWithin

        针对日期类型的操作符，分别表示在一个绝对日期范围/在 N 天之前/在 N 天之内。例如想筛选所有注册时间在 3 天之内的用户:

{
  "field": "user.$signup_time",
  "function": "relativeWithin",
  "params": [3]
}

        或者筛选所有在 2015-1-1~2015-1-10 注册的用户:

{
  "field": "user.$signup_time",
  "function": "absoluteBetween",
  "params": ["2015-01-01", "2015-01-10"]
}

3. 行为分析报告

所有的分析报告均有 JSON 和 CSV 两种格式，默认是 JSON 格式，如果需要 CSV 格式的数据可以手动指定 format 参数。例如事件分析报告对应的 CSV 格式的 URL 为: /events/report?format=csv 。

3.1. 事件分析报告

[POST /events/report]

{
  "measures":[
    {
      // 事件名称，特别的，可以使用 $Anything 表示任意事件
      "event_name":"payOrder",
      // 聚合操作符
      "aggregator":"uniq_count",
      //（可选）对于指标的筛选条件
      "filter": {
        "conditions": [
          {
            "field": "user.sex",
            "function": "equal",
            "params": [
              "男"
            ]
          }
        ]
      }
    }
  ],
  // 起始日期
  "from_date":"2018-04-30",
  // 结束日期
  "to_date":"2018-05-02",
  // 时间单位，可以是 hour/day/week/month
  "unit":"day",
  //（可选）筛选条件
  "filter":{
    "relation":"and",
    "conditions":[
      {
        "field":"event.payOrder.$lib_version",
        "function":"equal",
        "params":[
          "1.6.18"
        ]
      },
      {
        "field":"event.payOrder.$lib",
        "function":"equal",
        "params":[
          "Android"
        ]
      }
    ]
  },
  //（可选）分组属性，可以有零个或者多个
  "by_fields":[
    "event.payOrder.$screen_width",
    "event.payOrder.$screen_height"
  ],
  //（可选）分桶条件，对数值型属性进行分组时，可以自定义分桶条件
  "bucket_params":{
    "event.payOrder.$screen_width":[2000,3000],
    "event.payOrder.$screen_height":[2000]
  },
  // 是否计算合计值
  "detail_and_rollup":true,
  //（可选）抽样因子，64为全量，32为2分之1抽样
  "sampling_factor":64,
  //（可选）使用近似计算
  "approx":true,
  //（可选）基数计算算法hyperloglog的精度，值越大精度越高，但对应内存占用也会变高，推荐用12。
  "hll_precision":12,
  //（可选）使用近似计算合计，当“approx”为true时，“approx_total”也设为true，当“approx”为false时，如果“approx_total”为true，那合计会以近似计算算法得出
  "approx_total":false,
  //（可选）最大分组个数
  "limit":1000,
  //（可选）使用缓存，若缓存中找不到相应数据，则从数据库读出
  "use_cache":true
} 
{
  "by_fields":[
    "event.$Anything.$screen_width",
    "event.$Anything.$screen_height"
  ],
  "series":[
    "2018-04-30 00:00:00",
    "2018-05-01 00:00:00",
    "2018-05-02 00:00:00"
  ],
  "rows":[
    {
      "values":[
        [57],
        [60],
        [38]
      ],
      "by_values":[
        "-INF~2000",
        "-INF~2000"
      ]
    },
    {
      "values":[
        [7],
        [7],
        [2]
      ],
      "by_values":[
        "2000~3000",
        "-INF~2000"
      ]
    }
  ],
  "num_rows": 2,
  "total_rows": 2,
  "report_update_time": "2018-05-02 13:51:08.356",
  "data_update_time": "2018-05-02 16:03:32.000",
  "data_sufficient_update_time": "2018-05-02 16:03:32.000",
  "truncated": false
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/events/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
  "measures": [
    {
      "event_name": "payOrder",
      "aggregator": "unique",
      "filter": {
        "conditions": [
          {
            "field": "user.sex",
            "function": "equal",
            "params": [
              "男"
            ]
          }
        ]
      }
    }
  ],
  "from_date": "2018-04-30",
  "to_date": "2018-05-02",
  "unit": "day",
  "filter": {
    "relation": "and",
    "conditions": [
      {
        "field": "event.payOrder.$lib_version",
        "function": "equal",
        "params": [
          "1.6.18"
        ]
      },
      {
        "field": "event.payOrder.$lib",
        "function": "equal",
        "params": [
          "Android"
        ]
      }
    ]
  },
  "by_fields": [
    "event.payOrder.$screen_width",
    "event.payOrder.$screen_height"
  ],
  "bucket_params": {
    "event.payOrder.$screen_width": [
      2000,
      3000
    ],
    "event.payOrder.$screen_height": [
      2000
    ]
  },
  "unit":"day",
  "detail_and_rollup": true,
  "sampling_factor": 64,
  "approx": true,
  "hll_precision": 12,
  "approx_total": false,
  "limit": 1000,
  "use_cache": true
}

'

关键参数说明：

  • **aggregator: **聚合操作符，可取值为：
  • general:事件触发次数
  • unique:触发用户数
  • average/uniqAvg:人均次数/人均值
  • sum: 数值总和
  • max:数值最大值
  • min:数值最小值
  • avg:数值平均值
  • **field: **若aggregator为sum/max/min/avg，需要添加field字段，即聚合的字段名，与aggregator同级，例如：“field" : "event.payOrder.discountAmount"
  • **bucket_params: **分桶条件，对数值型属性进行分组时，可以自定义分桶条件，分桶条件里所包含的属性必须全包含在分组属性“by_fields”
  • **limit: **最大分组个数，如果limit较大（超过1W之后，可能引发服务器OOM）。如果不传入该字段，返回的分组数量将根据以下规则计算：10000 / 时间段个数 / 指标个数，时间段个数为 from_date 和 to_date 包含多少个单位为 unit 的时间段，指标个数即 measures 数组个数

3.2. 漏斗分析报告

[POST /funnels/report]

{
  // 漏斗 ID
  "funnel_id": 158,
  // 起始日期
  "from_date": "2015-04-17",
  // 结束日期
  "to_date": "2015-04-19",
  // 筛选条件
  "filter": {
    "conditions": [
      {
        "field": "event.$AppStart.$lib_version",
        "function": "contain",
        "params": [
          "0.1.0"
        ]
      },
      {
        "field": "event.$AppEnd.$lib",
        "function": "contain",
        "params": [
          "python"
        ]
      },
      {
        "field": "user.Gender",
        "function": "equal",
        "params": [
          "男"
        ]
      }
    ],
    "relation": "and"
  },
  // （可选）分组属性，按指定步骤事件属性、用户属性或分群名进行分组
  "by_field": "event.$AppStart.$os",
  // 是否限制漏斗所有步骤在事件窗口内，true:不限制，false:限制
  "extend_over_end_date": true,
  // （可选）分组的步骤 id，如果为 -1 表示用户属性/分群名，0 表示第一步骤事件属性，若 ”by_field” 中能明确看出为第几步的事件属性/用户属性，则此参数可以不用配置。否则需要配置相应参数值，并且和 ”by_field” 请求参数保持一致
  "by_field_step": -1,
  // （可选）抽样
  "sampling_factor": 64,
  // 指定筛选条件针对的步骤，0 为第一步骤，-1 为用筛选条件为用户属性/用户分群。在请求参数中 "filter" "conditions"中 “field”中指定了每一步骤的事件名及筛选条件，”filter_field_steps”参数可以不用配置。如果配置此参数，需要和 “field” 请求参数中的步骤保持一致。
  "filter_field_steps": [
      0，
      1，
     -1
    ]
}

在 1.13 及以上的版本中，我们支持 "from_date" 与 "to_date" 使用"秒级精度"或"天级精度"进行筛选

示例：

// 使用秒级精度
"from_date": "2015-04-17 22:00:00",
"to_date" : "2015-04-18 22:00:00",
  • 系统将会匹配出时间范围为 2015-04-17 22:00:00.000 至 2015-04-18 22:00:00.999 的全部数据
// 使用天级精度
"from_date": "2015-04-17",
"to_date" : "2015-04-18",
  • 系统将会匹配出时间范围为 2015-04-17 00:00:00.000 至 2015-04-18 23:59:59.999 的全部数据
{
  "date_list": [
    "$ALL",
    "2017-04-17",
    "2017-04-18",
    "2017-04-19"
  ],
  "funnel_detail": [
    {
      "steps": [
        {
          "event_name": "ViewHomePage",
          "converted_user": 98726,
          "conversion_rate": 100,
          "rows": [
            {
              "converted_user": 76110,
              "conversion_rate": 77.09,
              "wastage_user": 22616,
              "median_converted_time": 1505
            },
            {
              "converted_user": 76110,
              "conversion_rate": 77.09,
              "wastage_user": 22616,
              "median_converted_time": 1505
            }
          ]
        },
        {
          "event_name": "ViewProduct",
          "converted_user": 76110,
          "conversion_rate": 77.09,
          "rows": [
            {
              "converted_user": 21266,
              "conversion_rate": 27.94,
              "wastage_user": 54844,
              "median_converted_time": 2530
            },
            {
              "converted_user": 21266,
              "conversion_rate": 27.94,
              "wastage_user": 54844,
              "median_converted_time": 2530
            }
          ]
        },
        {
          "event_name": "SubmitOrder",
          "converted_user": 21266,
          "conversion_rate": 27.94,
          "rows": [
            {
              "converted_user": 17522,
              "conversion_rate": 82.39,
              "wastage_user": 3744,
              "median_converted_time": 939
            },
            {
              "converted_user": 17522,
              "conversion_rate": 82.39,
              "wastage_user": 3744,
              "median_converted_time": 939
            }
          ]
        },
        {
          "event_name": "PayOrder",
          "converted_user": 17522,
          "conversion_rate": 82.39,
          "rows": []
        }
      ],
      "completion_rate": 17.75,
      "overview": [
        [
          {
            "converted_user": 98726,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 76110,
            "conversion_rate": 77.09,
            "completion_rate": 77.09
          },
          {
            "converted_user": 21266,
            "conversion_rate": 27.94,
            "completion_rate": 21.54
          },
          {
            "converted_user": 17522,
            "conversion_rate": 82.39,
            "completion_rate": 17.75
          }
        ],
        [
          {
            "converted_user": 98726,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 76110,
            "conversion_rate": 77.09,
            "completion_rate": 77.09
          },
          {
            "converted_user": 21266,
            "conversion_rate": 27.94,
            "completion_rate": 21.54
          },
          {
            "converted_user": 17522,
            "conversion_rate": 82.39,
            "completion_rate": 17.75
          }
        ]
      ]
    },
    {
      "steps": [
        {
          "event_name": "ViewHomePage",
          "converted_user": 34099,
          "conversion_rate": 100,
          "rows": [
            {
              "converted_user": 26813,
              "conversion_rate": 78.63,
              "wastage_user": 7286,
              "median_converted_time": 1537
            },
            {
              "converted_user": 26813,
              "conversion_rate": 78.63,
              "wastage_user": 7286,
              "median_converted_time": 1537
            }
          ]
        },
        {
          "event_name": "ViewProduct",
          "converted_user": 26813,
          "conversion_rate": 78.63,
          "rows": [
            {
              "converted_user": 7787,
              "conversion_rate": 29.04,
              "wastage_user": 19026,
              "median_converted_time": 2710
            },
            {
              "converted_user": 7787,
              "conversion_rate": 29.04,
              "wastage_user": 19026,
              "median_converted_time": 2710
            }
          ]
        },
        {
          "event_name": "SubmitOrder",
          "converted_user": 7787,
          "conversion_rate": 29.04,
          "rows": [
            {
              "converted_user": 6449,
              "conversion_rate": 82.82,
              "wastage_user": 1338,
              "median_converted_time": 942
            },
            {
              "converted_user": 6449,
              "conversion_rate": 82.82,
              "wastage_user": 1338,
              "median_converted_time": 942
            }
          ]
        },
        {
          "event_name": "PayOrder",
          "converted_user": 6449,
          "conversion_rate": 82.82,
          "rows": []
        }
      ],
      "completion_rate": 18.91,
      "overview": [
        [
          {
            "converted_user": 34099,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 26813,
            "conversion_rate": 78.63,
            "completion_rate": 78.63
          },
          {
            "converted_user": 7787,
            "conversion_rate": 29.04,
            "completion_rate": 22.84
          },
          {
            "converted_user": 6449,
            "conversion_rate": 82.82,
            "completion_rate": 18.91
          }
        ],
        [
          {
            "converted_user": 34099,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 26813,
            "conversion_rate": 78.63,
            "completion_rate": 78.63
          },
          {
            "converted_user": 7787,
            "conversion_rate": 29.04,
            "completion_rate": 22.84
          },
          {
            "converted_user": 6449,
            "conversion_rate": 82.82,
            "completion_rate": 18.91
          }
        ]
      ]
    },
    {
      "steps": [
        {
          "event_name": "ViewHomePage",
          "converted_user": 34445,
          "conversion_rate": 100,
          "rows": [
            {
              "converted_user": 26701,
              "conversion_rate": 77.52,
              "wastage_user": 7744,
              "median_converted_time": 1521
            },
            {
              "converted_user": 26701,
              "conversion_rate": 77.52,
              "wastage_user": 7744,
              "median_converted_time": 1521
            }
          ]
        },
        {
          "event_name": "ViewProduct",
          "converted_user": 26701,
          "conversion_rate": 77.52,
          "rows": [
            {
              "converted_user": 7407,
              "conversion_rate": 27.74,
              "wastage_user": 19294,
              "median_converted_time": 2594
            },
            {
              "converted_user": 7407,
              "conversion_rate": 27.74,
              "wastage_user": 19294,
              "median_converted_time": 2594
            }
          ]
        },
        {
          "event_name": "SubmitOrder",
          "converted_user": 7407,
          "conversion_rate": 27.74,
          "rows": [
            {
              "converted_user": 6111,
              "conversion_rate": 82.5,
              "wastage_user": 1296,
              "median_converted_time": 956
            },
            {
              "converted_user": 6111,
              "conversion_rate": 82.5,
              "wastage_user": 1296,
              "median_converted_time": 956
            }
          ]
        },
        {
          "event_name": "PayOrder",
          "converted_user": 6111,
          "conversion_rate": 82.5,
          "rows": []
        }
      ],
      "completion_rate": 17.74,
      "overview": [
        [
          {
            "converted_user": 34445,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 26701,
            "conversion_rate": 77.52,
            "completion_rate": 77.52
          },
          {
            "converted_user": 7407,
            "conversion_rate": 27.74,
            "completion_rate": 21.5
          },
          {
            "converted_user": 6111,
            "conversion_rate": 82.5,
            "completion_rate": 17.74
          }
        ],
        [
          {
            "converted_user": 34445,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 26701,
            "conversion_rate": 77.52,
            "completion_rate": 77.52
          },
          {
            "converted_user": 7407,
            "conversion_rate": 27.74,
            "completion_rate": 21.5
          },
          {
            "converted_user": 6111,
            "conversion_rate": 82.5,
            "completion_rate": 17.74
          }
        ]
      ]
    },
    {
      "steps": [
        {
          "event_name": "ViewHomePage",
          "converted_user": 33579,
          "conversion_rate": 100,
          "rows": [
            {
              "converted_user": 25271,
              "conversion_rate": 75.26,
              "wastage_user": 8308,
              "median_converted_time": 1485
            },
            {
              "converted_user": 25271,
              "conversion_rate": 75.26,
              "wastage_user": 8308,
              "median_converted_time": 1485
            }
          ]
        },
        {
          "event_name": "ViewProduct",
          "converted_user": 25271,
          "conversion_rate": 75.26,
          "rows": [
            {
              "converted_user": 6845,
              "conversion_rate": 27.09,
              "wastage_user": 18426,
              "median_converted_time": 2469
            },
            {
              "converted_user": 6845,
              "conversion_rate": 27.09,
              "wastage_user": 18426,
              "median_converted_time": 2469
            }
          ]
        },
        {
          "event_name": "SubmitOrder",
          "converted_user": 6845,
          "conversion_rate": 27.09,
          "rows": [
            {
              "converted_user": 5599,
              "conversion_rate": 81.8,
              "wastage_user": 1246,
              "median_converted_time": 928
            },
            {
              "converted_user": 5599,
              "conversion_rate": 81.8,
              "wastage_user": 1246,
              "median_converted_time": 928
            }
          ]
        },
        {
          "event_name": "PayOrder",
          "converted_user": 5599,
          "conversion_rate": 81.8,
          "rows": []
        }
      ],
      "completion_rate": 16.67,
      "overview": [
        [
          {
            "converted_user": 33579,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 25271,
            "conversion_rate": 75.26,
            "completion_rate": 75.26
          },
          {
            "converted_user": 6845,
            "conversion_rate": 27.09,
            "completion_rate": 20.38
          },
          {
            "converted_user": 5599,
            "conversion_rate": 81.8,
            "completion_rate": 16.67
          }
        ],
        [
          {
            "converted_user": 33579,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 25271,
            "conversion_rate": 75.26,
            "completion_rate": 75.26
          },
          {
            "converted_user": 6845,
            "conversion_rate": 27.09,
            "completion_rate": 20.38
          },
          {
            "converted_user": 5599,
            "conversion_rate": 81.8,
            "completion_rate": 16.67
          }
        ]
      ]
    }
  ],
  "by_field": "event.$Anything.$os",
  "by_values": [
    "$ALL",
    "iOS"
  ],
  "event_names": [
    "ViewHomePage",
    "ViewProduct",
    "SubmitOrder",
    "PayOrder"
  ],
  "report_update_time": "2017-04-21 11:13:47.703",
  "data_update_time": "2017-04-21 11:12:56.000",
  "data_sufficient_update_time": "2017-04-21 11:12:56.000"
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/funnels/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \

--data-binary '{
    "from_date":"2015-04-17",
    "to_date":"2015-04-19",
    "funnel_id":"158",
    "filter":{
        "conditions":[
            {
                "field":"event.$AppStart.$lib_version",
                "function":"equal",
                "params":[
                    "0.1.0"
                ]
            },
            {
                "field":"event.$AppEnd.$libe",
                "function":"equal",
                "params":[
                    "python"
                ]
            }，
            {
                "field": "user.Gender",
                "function": "equal",
                "params": [
                    "男"
                ]
            }
        ],
        "relation":"and"
    },
    "by_field":"event.$AppStart.$os"
}'



3.3.  留存分析报告

[POST /retentions/report]

{
  // 起始日期
  "from_date": "2018-04-30",
  // 结束日期
  "to_date": "2018-05-02",
  // 表示获取往后 N 个单位的留存
  "duration": "7",
  // 第一个事件的信息
  "first_event": {
    // 事件名
    "event_name": "login"
  },
  // 第二个事件的信息
  "second_event": {
    // 事件名
    "event_name": "submitOrder",
    // 事件的筛选条件
    "filter": {
      "conditions": [
        {
          "field": "event.submitOrder.$lib",
          "function": "equal",
          "params": [
            "Android"
          ]
        }
      ],
      "relation":"and"
    }
  },
  // （可选）同时显示第三个指标
  "measures": [
    {
      "event_name": "payOrder",
      "aggregator": "unique"
    }
  ],
  // （可选）用户的筛选条件
  "user_filter": {
    "conditions": [
      {
        "field": "user.sex",
        "function": "equal",
        "params": [
          "男"
        ]
      }
    ],
    "relation":"and"
  },
  // （可选）时间标识，例如上周，优先级高于 from_date 和 to_date
  "rangeText": "上周"
  // （可选）留存的单位，可以是 day/week/month
  "unit": "day",
  // （可选）后续事件是否可以超出时间区间
  "extend_over_end_date": true,
  // （可选）抽样因子，64为全量，32为2分之1抽样
  "sampling_factor": 64,
  // （可选）是否计算流失，false为计算留存，true为计算流失
  "is_wastage": false,
  "use_cache": true
}
{
  "by_field": "",
  "has_first_day": false,
  "rows": [
    {
      "by_value": "2018-04-30",
      "total_people": 95,
      "cells": [
        {
          "people": 36,
          "percent": 37.89,
          // 选择同时显示后，values 的值即为同时显示的指标的值
          "values": [
            0
          ]
        },
        {
          "people": 6,
          "percent": 6.32,
          "values": [
            5
          ]
        }
      ]
    },
    {
      "by_value": "2018-05-01",
      "total_people": 91,
      "cells": [
        {
          "people": 25,
          "percent": 27.47,
          "values": [
            0
          ]
        },
        {
          "people": 1,
          "percent": 1.1,
          "values": [
            1
          ]
        }
      ]
    },
    {
      "by_value": "2018-05-02",
      "total_people": 62,
      "cells": [
        {
          "people": 25,
          "percent": 40.32,
          "values": [
            0
          ]
        }
      ]
    }
  ],
  "report_update_time": "2018-05-02 17:00:21.355",
  "data_update_time": "2018-05-02 16:59:43.000",
  "data_sufficient_update_time": "2018-05-02 16:59:43.000",
  "truncated": false
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/retentions/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
  "from_date": "2018-04-30",
  "to_date": "2018-05-02",
  "duration": "7",
  "first_event": {
    "event_name": "login"
  },
  "second_event": {
    "event_name": "submitOrder",
    "filter": {
      "conditions": [
        {
          "field": "event.submitOrder.$lib",
          "function": "equal",
          "params": [
            "Android"
          ]
        }
      ],
      "relation": "and"
    }
  },
  "measures": [
    {
      "event_name": "payOrder",
      "aggregator": "unique"
    }
  ],
  "user_filter": {
    "conditions": [
      {
        "field": "user.sex",
        "function": "equal",
        "params": [
          "男"
        ]
      }
    ],
    "relation": "and"
  },
  "unit": "day",
  "extend_over_end_date": true,
  "sampling_factor": 64,
  "is_wastage": false,
  "use_cache": true
}

'

3.4. 分布分析报告

[POST /addictions/report]

{
  // 事件名称
  "event_name": "submitOrder",
  // 起始时间
  "from_date": "2018-04-30",
  // 结束时间
  "to_date": "2018-05-02",
  // 事件筛选条件
  "filter": {
    "conditions": [
      {
        "field": "event.submitOrder.$lib",
        "function": "equal",
        "params": [
          "Android"
        ]
      }
    ],
    "relation":"and"
  },
  // 用户筛选条件
  "user_filter": {
    "conditions": [
      {
        "field": "user.sex",
        "function": "equal",
        "params": [
          "男"
        ]
      }
    ],
    "relation":"and"
  },
  // （可选）时间标识，如：上周，优先级高于from_date、to_date
  "rangeText":"上周",
  // 抽样因子，64为全量，32为2分之1抽样
  "sampling_factor":64,
  // 事件单位，可以是 day/week/month
  "unit": "day",
  // 测量类型,可以是times/period, period是当按小时数或者天数进行分布分析时使用
  "measure_type":"times",
  //测量类型如果是times，即可以自定义分桶，可省略
  "result_bucket_param": [
    2,
    3
  ]
}
{
  "by_field": "",
  "rows": [
    {
      "by_value": "2018-04-30",
      "total_people": 455,
      "cells": [
        {
          "people": 436,
          "percent": 95.82,
          "bucket_end": 2
        },
        {
          "people": 19,
          "percent": 4.18,
          "bucket_start": 2,
          "bucket_end": 3
        }
      ]
    },
    {
      "by_value": "2018-05-01",
      "total_people": 499,
      "cells": [
        {
          "people": 484,
          "percent": 96.99,
          "bucket_end": 2
        },
        {
          "people": 15,
          "percent": 3.01,
          "bucket_start": 2,
          "bucket_end": 3
        }
      ]
    },
    {
      "by_value": "2018-05-02",
      "total_people": 280,
      "cells": [
        {
          "people": 273,
          "percent": 97.5,
          "bucket_end": 2
        },
        {
          "people": 7,
          "percent": 2.5,
          "bucket_start": 2,
          "bucket_end": 3
        }
      ]
    }
  ],
  "report_update_time": "2018-05-02 17:15:26.739",
  "data_update_time": "2018-05-02 17:14:10.000",
  "data_sufficient_update_time": "2018-05-02 17:14:10.000",
  "truncated": false
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/addictions/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
  "event_name": "submitOrder",
  "from_date": "2018-04-30",
  "to_date": "2018-05-02",
  "filter": {
    "conditions": [
      {
        "field": "event.submitOrder.$lib",
        "function": "equal",
        "params": [
          "Android"
        ]
      }
    ],
    "relation": "and"
  },
  "user_filter": {
    "conditions": [
      {
        "field": "user.sex",
        "function": "equal",
        "params": [
          "男"
        ]
      }
    ],
    "relation": "and"
  },
  "sampling_factor": 64,
  "unit": "day",
  "measure_type": "times",
  "result_bucket_param": [
    2,
    3
  ]
}

'

3.5. 用户路径分析报告

[POST /path/analytics/report]

{
  // 起始事件是initial_event, 结束事件是termination_event
  "source_type": "initial_event",
  // 起始事件和对起始事件的过滤
  "source_event": {
    "event_name": "StartApp",
    "filter": {
      "conditions": [
        {
          "field": "event.StartApp.$wifi",
          "function": "isTrue",
          "params": []
        }
      ]
    }
  },
  "event_names": [
    "BuyBullion",
    "BuyGold",
    "SaleGold",
    "StartApp"
  ],
  "by_fields": [
    "event.BuyBullion.$country"
  ],
  // （可选）列数量的限制
  "col_limit": 20,
  // （可选）每列节点数限制
  "row_limit": 7,
  "from_date": "2017-05-01",
  "to_date": "2017-05-22",
  "user_filter": {},
  "bucket_params": {},
  "sampling_factor": 64,
  "session_interval": 1200,
  "use_cache": true
} 
{
  "nodes": [
    [
      {
        "id": "0_StartApp",
        "event_name": "StartApp",
        "times": 27336
      }
    ],
    [
      {
        "id": "1_StartApp",
        "event_name": "StartApp",
        "times": 163
      },
      {
        "id": "1_BuyGold",
        "event_name": "BuyGold",
        "times": 118
      },
      {
        "id": "1_SaleGold",
        "event_name": "SaleGold",
        "times": 104
      },
      {
        "id": "1_BuyBullion_$country_3392903",
        "event_name": "BuyBullion",
        "times": 37
      }
    ],
    [
      {
        "id": "2_SaleGold",
        "event_name": "SaleGold",
        "times": 68
      },
      {
        "id": "2_BuyGold",
        "event_name": "BuyGold",
        "times": 50
      },
      {
        "id": "2_BuyBullion_$country_3392903",
        "event_name": "BuyBullion",
        "times": 18
      },
      {
        "id": "2_StartApp",
        "event_name": "StartApp",
        "times": 2
      }
    ],
    [
      {
        "id": "3_SaleGold",
        "event_name": "SaleGold",
        "times": 39
      },
      {
        "id": "3_BuyGold",
        "event_name": "BuyGold",
        "times": 23
      },
      {
        "id": "3_BuyBullion_$country_3392903",
        "event_name": "BuyBullion",
        "times": 1
      }
    ],
    [
      {
        "id": "4_StartApp",
        "event_name": "StartApp",
        "times": 1
      }
    ]
  ],
  "links": [
    [
      {
        "source": "0_StartApp",
        "target": "1_wastage",
        "is_wastage": true,
        "times": 26914
      },
      {
        "source": "0_StartApp",
        "target": "1_StartApp",
        "times": 163
      },
      {
        "source": "0_StartApp",
        "target": "1_BuyGold",
        "times": 118
      },
      {
        "source": "0_StartApp",
        "target": "1_SaleGold",
        "times": 104
      },
      {
        "source": "0_StartApp",
        "target": "1_BuyBullion_$country_3392903",
        "times": 37
      }
    ],
    [
      {
        "source": "1_StartApp",
        "target": "2_wastage",
        "is_wastage": true,
        "times": 160
      },
      {
        "source": "1_StartApp",
        "target": "2_StartApp",
        "times": 2
      },
      {
        "source": "1_StartApp",
        "target": "2_BuyBullion_$country_3392903",
        "times": 1
      },
      {
        "source": "1_BuyGold",
        "target": "2_wastage",
        "is_wastage": true,
        "times": 68
      },
      {
        "source": "1_BuyGold",
        "target": "2_BuyGold",
        "times": 50
      },
      {
        "source": "1_SaleGold",
        "target": "2_SaleGold",
        "times": 68
      },
      {
        "source": "1_SaleGold",
        "target": "2_wastage",
        "is_wastage": true,
        "times": 36
      },
      {
        "source": "1_BuyBullion_$country_3392903",
        "target": "2_wastage",
        "is_wastage": true,
        "times": 20
      },
      {
        "source": "1_BuyBullion_$country_3392903",
        "target": "2_BuyBullion_$country_3392903",
        "times": 17
      }
    ],
    [
      {
        "source": "2_SaleGold",
        "target": "3_SaleGold",
        "times": 39
      },
      {
        "source": "2_SaleGold",
        "target": "3_wastage",
        "is_wastage": true,
        "times": 29
      },
      {
        "source": "2_BuyGold",
        "target": "3_wastage",
        "is_wastage": true,
        "times": 27
      },
      {
        "source": "2_BuyGold",
        "target": "3_BuyGold",
        "times": 23
      },
      {
        "source": "2_BuyBullion_$country_3392903",
        "target": "3_wastage",
        "is_wastage": true,
        "times": 17
      },
      {
        "source": "2_BuyBullion_$country_3392903",
        "target": "3_BuyBullion_$country_3392903",
        "times": 1
      },
      {
        "source": "2_StartApp",
        "target": "3_wastage",
        "is_wastage": true,
        "times": 2
      }
    ],
    [
      {
        "source": "3_SaleGold",
        "target": "4_wastage",
        "is_wastage": true,
        "times": 38
      },
      {
        "source": "3_SaleGold",
        "target": "4_StartApp",
        "times": 1
      },
      {
        "source": "3_BuyGold",
        "target": "4_wastage",
        "is_wastage": true,
        "times": 23
      },
      {
        "source": "3_BuyBullion_$country_3392903",
        "target": "4_wastage",
        "is_wastage": true,
        "times": 1
      }
    ],
    [
      {
        "source": "4_StartApp",
        "target": "5_wastage",
        "is_wastage": true,
        "times": 1
      }
    ]
  ],
  "truncate_row": [],
  "truncate_col": false,
  "report_update_time": "2017-05-22 11:07:40.544",
  "data_update_time": "2017-05-22 11:06:54.000",
  "data_sufficient_update_time": "2017-05-22 11:06:54.000"
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/path/analytics/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
  "source_type": "initial_event",
  "source_event": {
    "event_name": "StartApp",
    "filter": {
      "conditions": [
        {
          "field": "event.StartApp.$wifi",
          "function": "isTrue",
          "params": []
        }
      ]
    }
  },
  "event_names": [
    "BuyBullion",
    "BuyGold",
    "SaleGold",
    "StartApp"
  ],
  "by_fields": [
    "event.BuyBullion.$country"
  ],
  "col_limit": 20,
  "row_limit": 7,
  "from_date": "2017-05-01",
  "to_date": "2017-05-22",
  "user_filter": {},
  "bucket_params": {},
  "sampling_factor": 64,
  "session_interval": 1200,
  "use_cache": true
}

'

3.6. 属性分析报告

[POST /user/analytics/report]

{
  "measures": [
    {
      "aggregator": "count",
      "field": ""
    }
  ],
  "filter": {
    "conditions": [
      {
        "field": "user.HasByGold",
        "function": "isTrue",
        "params": []
      }
    ]
  },
  "by_fields": [
    "user.IncomeLevel",
    "user.Gender"
  ],
  "sampling_factor": null,
  // 横轴分组指标
  "x_axis_field": "user.IncomeLevel",
  "use_cache": false
} 
{
  "by_fields": [
    "user.Gender"
  ],
  "series": [
    "5000~10000",
    "3000~5000",
    "10000~20000",
    "0~3000",
    null
  ],
  "rows": [
    {
      "values": [
        [
          83169
        ],
        [
          27776
        ],
        [
          55699
        ],
        [
          27892
        ],
        [
          36106
        ]
      ],
      "by_values": [
        "男"
      ]
    },
    {
      "values": [
        [
          55363
        ],
        [
          18208
        ],
        [
          37030
        ],
        [
          18668
        ],
        [
          24090
        ]
      ],
      "by_values": [
        "女"
      ]
    },
    {
      "values": [
        [
          25864
        ],
        [
          8490
        ],
        [
          17327
        ],
        [
          8628
        ],
        [
          17353
        ]
      ],
      "by_values": [
        null
      ]
    }
  ],
  "num_rows": 3,
  "report_update_time": "2017-05-22 14:16:03.595",
  "data_update_time": "1970-01-01 08:00:00.000",
  "data_sufficient_update_time": "1970-01-01 08:00:00.000"
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/user/analytics/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
  "measures": [
    {
      "aggregator": "count",
      "field": ""
    }
  ],
  "filter": {
    "conditions": [
      {
        "field": "user.HasByGold",
        "function": "isTrue",
        "params": []
      }
    ]
  },
  "by_fields": [
    "user.IncomeLevel",
    "user.Gender"
  ],
  "sampling_factor": null,
  "x_axis_field": "user.IncomeLevel",
  "request_id": 1495433768121,
  "use_cache": false
}

'

3.7. 归因分析报告

需要注意的是归因分析报告不支持csv

[POST /attribution/report]

{
  // 开始时间
  "from_date": "2020-06-08",
  // 结束时间
  "to_date": "2020-06-12",
  // 是否使用缓存
  "use_cache": false,
  // 直接转化是否参与归因计算
  "direct_conversion": true,
  // 抽样系数
  "sampling_factor": 64,
  // 目标事件
  "target_event": {
    "event_name": "UserLogin",
    // 聚合操作符 可选常规、求和 ["general", "SUM"]
    "aggregator": "SUM",
    // 聚合字段 操作符为SUM时 此项必填
    "field": "event.AddToShoppingCart.$viewport_position",
    // 目标事件过滤条件
    "filter": {}
  },
  // 前向事件 可配置多个
  "link_events": [
    {
      // 前向事件名称
      "event_name": "UserLogin",
      // 前向事件关联属性
      "link_properties": {
        // 当前前向事件属性
        "current_event_property": "event.UserLogin.$ip",
        // 目标事件属性
        "target_event_property": "event.watch.$distinct_id"
      },
      // 前向事件筛选条件
      "filter": {}
    }
  ],
  // 待归因事件
  "attribution_events": {
    // 事件集合
    "events": [
      {
        "event_name": "watch"
      }
    ],
    // 筛选条件
    "filter": {},
    // 分组
    "by_fields": [
      "event.$Anything.MovieName"
    ]
  },
  // 筛选条件
  "filter": {
    "relation": "and",
    "conditions": []
  },
  // 归因分析模型可选首次触点归因、末次触点归因、线性归因、位置归因、时间衰减归因 ["first","last","linear","position","time_decay"]
  "model_type": "first",
  // 归因窗口期
  "lookback_window": {
    // 窗口期单位可选分钟、小时、天 ["minute","hour","day"]
    "unit": "day",
    "value": 1
  }
}
{
  "detail_result": {
    "rows": [
      {
        // 没有【待归因事件】代表【直接转换】
        "groups": [
          {
            "by_values": [
              "$ALL"
            ],
            // 待归因事件总点击数
            "value": 5,
            // 待归因事件转化数量
            "converted_number": 5,
            // 转化用户数
            "converted_user_number": 0,
            // 对目标事件的贡献得分
            "goal_conversion": 5,
            // 对目标事件的贡献度
            "conversion_value_rate": 100.0
          }
        ]
      },
      {
        // 待归因事件
        "event_name": "$AppClick",
        "groups": [
          {
            "by_values": [
              "$ALL"
            ],
            "value": 66809,
            "converted_number": 10549,
            "converted_user_number": 8046,
            "goal_conversion": 9991,
            "conversion_value_rate": 100
          }
        ]
      }
    ]
  },
  // 全量缓存更新时间
  "report_update_time": "2020-06-12 19:38:29.861",
  // 查询涉及事件数据的最后更新时间
  "data_update_time": "2020-06-12 10:39:29.000",
  // 查询涉及事件数据量变化超过 5% 的最后更新时间
  "data_sufficient_update_time": "2020-06-12 10:39:29.000",
  // 查询是否截断
  "truncated": false,
  // 抽样系数
  "sampling_factor": 64
}
curl 'https://golddemo.cloud.sensorsdata.cn/api/attribution/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '
{
  "from_date": "2020-05-13",
  "to_date": "2020-06-11",
  "use_cache": false,
  "direct_conversion": true,
  "target_event": {
    "event_name": "AddToShoppingCart",
    "aggregator": "general",
    "field": "",
    "filter": {}
  },
  "link_events": [],
  "attribution_events": {
    "events": [
      {
        "event_name": "$AppClick"
      }
    ],
    "filter": {
      "relation": "and",
      "conditions": []
    },
    "by_fields": []
  },
  "filter": {
    "relation": "and",
    "conditions": []
  },
  "model_type": "first",
  "lookback_window": {
    "unit": "day",
    "value": 1
  }
}
'

使用curl时需注意 网址是 https 还是 http

4. 用户明细查询

用户明细系列接口用于查询某一个特定分析报告中的具体用户列表，请求的大部分参数与分析报告相同，新增的参数会在每个接口里具体说明。用户列表也支持 JSON 和 CSV 两种格式，默认式 JSON 格式，如果需要 CSV 格式的数据可以手动指定 format 参数。例如事件分析的用户列表对应的 CSV 格式的 URL 为: /events/user/list?format=csv。

4.1. 事件分析用户明细报告

[POST /events/user/list]

{
  "measures": [
    {
      "aggregator": "unique",
      "event_name": "SaleGold"
    }
  ],
  "filter": {
    "conditions": [
      {
        "field": "event.SaleGold.$city",
        "function": "equal",
        "params": [
          "厦门市"
        ]
      },
      {
        "field": "event.SaleGold.$app_version",
        "function": "equal",
        "params": [
          "1.7"
        ]
      }
    ]
  },
  "by_fields": [
    "event.SaleGold.$app_version",
    "event.SaleGold.$screen_width"
  ],
  "rollup_date": false,
  "unit": "week",
  // 查看哪个分组的用户明细
  "slice_by_values": [
    "1.7",
    1080
  ],
  // 查看哪天的用户明细,比如2015年8月18号当周
  "slice_date": "2015-08-18 00:00:00",
  // 是否展示详情，如果 true，则会按照 profile 中的列返回，false 则只返回基本的 id 列
  "detail": true,
  // 默认值30，表示每页展示用户数，可不加 
  "num_per_page": 10,
  // 请求的页数 
  "page":1,
  // 限制返回的条数
  "limit": 100000,
  // 是否返回所有用户，如果为 true，则会无视分页参数，否则需要加上分页参数 
  "all_page": true
}
{
  "users": [
    {
      "id": "1902482830",
      "first_id": "23e3ff2a3ff1e1bc",
      "second_id": "1696144579",
      "profiles": {
        "FavoriteFruits": [
          "Raspberry",
          "Orange"
        ],
        "$name": "陈爍簀",
        "IncomeLevel": "3000~5000",
        "$city": "德阳市",
        "$province": "四川省",
        "$signup_time": 1.432805251963E12,
        "Gender": "男",
        "Age": 20.0
      }
    },
    {
      "id": "3834577070",
      "first_id": "51b0fecc44b5c75b",
      "second_id": "1602971488",
      "profiles": {
        "FavoriteFruits": [
          "Cranberry",
          "Guava",
          "cantaloupe"
        ],
        "$name": "周瀌狙",
        "IncomeLevel": "10000~20000",
        "$city": "嘉峪关市",
        "$province": "甘肃省",
        "$signup_time": 1.432799799529E12,
        "Gender": "女",
        "Age": 20.0
      }
    }
  ],
  "size": 2,
  "page_num": 1, // 页数，总人数/每页展示用户数
  "column_name":[
    "FavoriteFruits",
    "$name",
    "Age",
    "Gender",
    "IncomeLevel",
    "$signup_time",
    "$city",
    "$province"
  ]
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/events/user/list?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
    "measures":[
        {
            "aggregator":"unique",
            "event_name":"SaleGold"
        }
    ],
    "filter":{
        "conditions":[
            {
                "field":"event.SaleGold.$city",
                "function":"equal",
                "params":[
                    "厦门市"
                ]
            },
            {
                "field":"event.SaleGold.$app_version",
                "function":"equal",
                "params":[
                    "1.7"
                ]
            }
        ]
    },
    "by_fields":[
        "event.SaleGold.$app_version",
        "event.SaleGold.$screen_width"
    ],
    "rollup_date":false,
    "unit":"week",
    "slice_by_values":[
        "1.7",
        1080
    ],
    "slice_date":"2015-08-18 00:00:00",
    "detail":true,
    "num_per_page":10,
    "page":1,
    "limit":100000,
    "all_page":true
}

'


4.2. 漏斗分析用户明细报告

[POST /funnels/user/list]

{
  "funnel_id": 158,
  "from_date": "2015-04-17",
  "to_date": "2015-07-16",
  "filter": {
    "conditions": [
      {
        "field": "event.$Anything.$lib_version",
        "function": "contain",
        "params": [
          "0.1.0"
        ]
      },
      {
        "field": "event.$Anything.$lib",
        "function": "contain",
        "params": [
          "python"
        ]
      },
      {
        "field": "user.Gender",
        "function": "equal",
        "params": [
          "男"
        ]
      }
    ],
    "relation": "and"
  },
  "by_field": "event.SaleGold.$lib_version",
  // 用户明细的分组值
  "slice_by_value": "0.1.0",
  // 用户明细的步骤
  "slice_step": 0,
  // true 表示查看流失用户明细，false 表示转化用户
  "slice_wastage_user": false,
  // 是否展示详情，如果 true，则会按照 profile 中的列返回，false 则只返回基本的 id 列
  "detail": true,
  // 请求的页数 
  "page":1,
  // 每页数据条数
  "num_per_page": 30,
  // 限制返回的条数
  "limit": 100000,
  // 是否返回所有用户，如果为 true，则会无视分页参数，否则需要加上分页参数
  "all_page": true
}
{
  "users": [
    {
      "id": "1902482830",
      "first_id": "23e3ff2a3ff1e1bc",
      "second_id": "1696144579",
      "profiles": {
        "FavoriteFruits": [
          "Raspberry",
          "Orange"
        ],
        "$name": "陈爍簀",
        "IncomeLevel": "3000~5000",
        "$city": "德阳市",
        "$province": "四川省",
        "$signup_time": 1.432805251963E12,
        "Gender": "男",
        "Age": 20.0
      }
    },
    {
      "id": "3834577070",
      "first_id": "51b0fecc44b5c75b",
      "second_id": "1602971488",
      "profiles": {
        "FavoriteFruits": [
          "Cranberry",
          "Guava",
          "cantaloupe"
        ],
        "$name": "周瀌狙",
        "IncomeLevel": "10000~20000",
        "$city": "嘉峪关市",
        "$province": "甘肃省",
        "$signup_time": 1.432799799529E12,
        "Gender": "女",
        "Age": 20.0
      }
    }
  ],
  "size": 2,
  "page_num": 1,
  "column_name":[
    "FavoriteFruits",
    "$name",
    "Age",
    "Gender",
    "IncomeLevel",
    "$signup_time",
    "$city",
    "$province"
  ]
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/funnels/user/list?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
    "funnel_id":158,
    "from_date":"2015-04-17",
    "to_date":"2015-07-16",
    "filter":{
        "conditions":[
            {
                "field":"event.$Anything.$lib_version",
                "function":"contain",
                "params":[
                    "0.1.0"
                ]
            },
            {
                "field":"event.$Anything.$lib",
                "function":"contain",
                "params":[
                    "python"
                ]
            },
            {
                "field":"user.Gender",
                "function":"equal",
                "params":[
                    "男"
                ]
            }
        ],
        "relation":"and"
    },
    "by_field":"event.SaleGold.$lib_version",
    "slice_by_value":"0.1.0",
    "slice_step":0,
    "slice_wastage_user":false,
    "detail":true,
    "page":1,
    "num_per_page":30,
    "limit":100000,
    "all_page":true
}

'

4.3. 留存分析用户明细报告

[POST /retentions/user/list]

{
  "first_event": {
    "event_name": "BuyGold",
    "filter": {
      "conditions": [
        {
          "field": "event.BuyGold.$lib_version",
          "function": "contain",
          "params": [
            "0.1.0"
          ]
        }
      ]
    }
  },
  "second_event": {
    "event_name": "StartApp"
  },
  //是否流失用户，默认留存用户
  "is_wastage": false,
  // 指定哪些用户属性，为空表示所有用户属性
  "profiles": [],
  "duration": 7,
  "from_date": "2015-07-21",
  "to_date": "2015-07-24",
  "unit": "day",
  "by_field": "event.SaleGold.$lib_version",
  // 用户明细分的分组值
  "slice_by_value": "0.1.0",
  // 查看第几天留存的用户明细，0 表示当天，null 表示全部
  // 表示随后第几天留存
  "slice_interval": 1,
  // 是否展示详情，如果 true，则会按照 profile 中的列返回，false 则只返回基本的 id 列
  "detail": true,
  // 请求的页数 
  "page":1,
  // 每页数据条数
  "num_per_page": 30,
  // 限制返回的条数
  "limit": 100000,
  // 是否返回所有用户，如果为 true，则会无视分页参数，否则需要加上分页参数
  "all_page": true
}
{
  "users": [
    {
      "id": "1902482830",
      "first_id": "23e3ff2a3ff1e1bc",
      "second_id": "1696144579",
      "profiles": {
        "FavoriteFruits": [
          "Raspberry",
          "Orange"
        ],
        "$name": "陈爍簀",
        "IncomeLevel": "3000~5000",
        "$city": "德阳市",
        "$province": "四川省",
        "$signup_time": 1.432805251963E12,
        "Gender": "男",
        "Age": 20.0
      }
    },
    {
      "id": "3834577070",
      "first_id": "51b0fecc44b5c75b",
      "second_id": "1602971488",
      "profiles": {
        "FavoriteFruits": [
          "Cranberry",
          "Guava",
          "cantaloupe"
        ],
        "$name": "周瀌狙",
        "IncomeLevel": "10000~20000",
        "$city": "嘉峪关市",
        "$province": "甘肃省",
        "$signup_time": 1.432799799529E12,
        "Gender": "女",
        "Age": 20.0
      }
    }
  ],
  "size": 2,
  "page_num": 1,
  "column_name":[
    "FavoriteFruits",
    "$name",
    "Age",
    "Gender",
    "IncomeLevel",
    "$signup_time",
    "$city",
    "$province"
  ]
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/retentions/user/list?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
    "first_event":{
        "event_name":"BuyGold",
        "filter":{
            "conditions":[
                {
                    "field":"event.BuyGold.$lib_version",
                    "function":"contain",
                    "params":[
                        "0.1.0"
                    ]
                }
            ]
        }
    },
    "second_event":{
        "event_name":"StartApp"
    },
    "is_wastage":false,
    "profiles":[

    ],
    "duration":7,
    "from_date":"2015-07-21",
    "to_date":"2015-07-24",
    "unit":"day",
    "by_field":"event.SaleGold.$lib_version",
    "slice_by_value":"0.1.0",
    "slice_interval":1,
    "detail":true,
    "page":1,
    "num_per_page":30,
    "limit":100000,
    "all_page":true
}

'

4.4. 分布分析用户明细报告

[POST /addictions/user/list]

{
  "event_name": "BuyGold",
  "filter": {
    "conditions": [
      {
        "field": "event.BuyGold.$lib_version",
        "function": "contain",
        "params": [
          "0.1.0"
        ]
      }
    ]
  },
  "rollup_date": false,
  "from_date": "2015-04-22",
  "to_date": "2015-04-22",
  "unit": "day",
  "by_field": "event.SaleGold.$lib_version",
  // 用户明细的分组信息
  "slice_by_value": "0.1.0",
  // 查看回访频率为多少的用户明细
  "slice_freq": 2,
  "detail": true,
  // 请求的页数 
  "page":1,
  // 每页数据条数
  "num_per_page": 30,
  // 限制返回的条数
  "limit": 100000,
  // 是否返回所有用户，如果为 true，则会无视分页参数，否则需要加上分页参数
  "all_page": true
}
{
  "users": [
    {
      "id": "1902482830",
      "first_id": "23e3ff2a3ff1e1bc",
      "second_id": "1696144579",
      "profiles": {
        "FavoriteFruits": [
          "Raspberry",
          "Orange"
        ],
        "$name": "陈爍簀",
        "IncomeLevel": "3000~5000",
        "$city": "德阳市",
        "$province": "四川省",
        "$signup_time": 1.432805251963E12,
        "Gender": "男",
        "Age": 20.0
      }
    },
    {
      "id": "3834577070",
      "first_id": "51b0fecc44b5c75b",
      "second_id": "1602971488",
      "profiles": {
        "FavoriteFruits": [
          "Cranberry",
          "Guava",
          "cantaloupe"
        ],
        "$name": "周瀌狙",
        "IncomeLevel": "10000~20000",
        "$city": "嘉峪关市",
        "$province": "甘肃省",
        "$signup_time": 1.432799799529E12,
        "Gender": "女",
        "Age": 20.0
      }
    }
  ],
  "size": 2,
  "page_num": 1,
  "column_name":[
    "FavoriteFruits",
    "$name",
    "Age",
    "Gender",
    "IncomeLevel",
    "$signup_time",
    "$city",
    "$province"
  ]
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/addictions/user/list?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
    "event_name":"BuyGold",
    "filter":{
        "conditions":[
            {
                "field":"event.BuyGold.$lib_version",
                "function":"contain",
                "params":[
                    "0.1.0"
                ]
            }
        ]
    },
    "rollup_date":false,
    "from_date":"2015-04-22",
    "to_date":"2015-04-22",
    "unit":"day",
    "by_field":"event.SaleGold.$lib_version",
    "slice_by_value":"0.1.0",
    "slice_freq":2,
    "detail":true,
    "page":1,
    "num_per_page":30,
    "limit":100000,
    "all_page":true
}

'

4.5. 用户列表明细报告

[POST /users/list]

{
  "filter": {
    "conditions": [
      {
        // 这里可以任意增加筛选条件
        // 可以指定指分群或标签名，如想获取某个分群的用户，则指定 为 'user.fenqun1'
        // 也可以指定普通属性名，如 'user.birthday'
        // 更多的用法请参考上面的筛选表达式说明
        "field": "user.test",
        "function": "isTrue"
      }
    ]
  },
  "profiles": [
    // 请求的用户属性列表
    "user.$utm_source"
  ],
  // 请求的页数，从 0 开始，0 代表第一页 
  "page":0,
  // 每页数据条数
  "num_per_page": 30,
  // 限制返回的条数
  "limit": 100000,
  // 是否返回所有用户，如果为 true，则会无视分页参数，否则需要加上分页参数
  "all_page": true
}
{
  "users": [
    {
      "id": "1902482830",
      "first_id": "23e3ff2a3ff1e1bc",
      "second_id": "1696144579",
      "profiles": {
        "FavoriteFruits": [
          "Raspberry",
          "Orange"
        ],
        "$name": "陈爍簀",
        "IncomeLevel": "3000~5000",
        "$city": "德阳市",
        "$province": "四川省",
        "$signup_time": 1.432805251963E12,
        "Gender": "男",
        "Age": 20.0
      }
    },
    {
      "id": "3834577070",
      "first_id": "51b0fecc44b5c75b",
      "second_id": "1602971488",
      "profiles": {
        "FavoriteFruits": [
          "Cranberry",
          "Guava",
          "cantaloupe"
        ],
        "$name": "周瀌狙",
        "IncomeLevel": "10000~20000",
        "$city": "嘉峪关市",
        "$province": "甘肃省",
        "$signup_time": 1.432799799529E12,
        "Gender": "女",
        "Age": 20.0
      }
    }
  ],
  "size": 2,
  "page_num": 1,
  "column_name":[
    "FavoriteFruits",
    "$name",
    "Age",
    "Gender",
    "IncomeLevel",
    "$signup_time",
    "$city",
    "$province"
  ]
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/users/list?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
    "filter":{
        "conditions":[
            {
                "field":"user.test",
                "function":"isTrue"
            }
        ]
    },
    "profiles":[
        "user.$utm_source"
    ],
    "page":0,
    "num_per_page":30,
    "limit":100000,
    "all_page":true
}

'

这个接口也可以指定要查询的用户id，这样能获取指定用户的属性信息。

{
  "filter":{
    "conditions":[
      {
        "field":"user.test",
        "function":"isTrue"
      }
    ]
  },
  "users":["1902482830", "3834577070"],
  "profiles":[
    "user.$utm_source"
  ]
}
{
  "users": [
    {
      "id": "1902482830",
      "first_id": "23e3ff2a3ff1e1bc",
      "second_id": "1696144579",
      "profiles": {
        "FavoriteFruits": [
          "Raspberry",
          "Orange"
        ],
        "$name": "陈爍簀",
        "IncomeLevel": "3000~5000",
        "$city": "德阳市",
        "$province": "四川省",
        "$signup_time": 1.432805251963E12,
        "Gender": "男",
        "Age": 20.0
      }
    },
    {
      "id": "3834577070",
      "first_id": "51b0fecc44b5c75b",
      "second_id": "1602971488",
      "profiles": {
        "FavoriteFruits": [
          "Cranberry",
          "Guava",
          "cantaloupe"
        ],
        "$name": "周瀌狙",
        "IncomeLevel": "10000~20000",
        "$city": "嘉峪关市",
        "$province": "甘肃省",
        "$signup_time": 1.432799799529E12,
        "Gender": "女",
        "Age": 20.0
      }
    }
  ],
  "size": 2,
  "page_num": 1,
  "column_name":[
    "FavoriteFruits",
    "$name",
    "Age",
    "Gender",
    "IncomeLevel",
    "$signup_time",
    "$city",
    "$province"
  ]
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/users/list?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
  "filter":{
    "conditions":[
      {
        "field":"user.test",
        "function":"isTrue"
      }
    ]
  },
  "users":["1902482830", "3834577070"],
  "profiles":[
    "user.$utm_source"
  ]
}

'

4.6. 用户路径用户明细报告

[POST /users/list]

{
  "slice_element_filter": [
    {
      "slice_event_name": "StartApp",
      "slice_by_value": "8.1"
    }
  ],
  "next_slice_element_filter": [
    {
      "slice_event_name": "SaleGold",
      "slice_by_value": "1"
    }
  ], // 合计，后续事件统计和流失不需要这个过滤条件
  "session_level": "0", // 源端的层数
  "source_type": "initial_event",
  "source_event": {
    "event_name": "StartApp",
    "filter": {
      "conditions": [
        {
          "field": "event.StartApp.$wifi",
          "function": "isTrue"
        }
      ]
    }
  },
  "event_names": [
    "BuyBullion",
    "BuyGold",
    "SaleGold",
    "StartApp"
  ],
  "by_fields": [
    "event.SaleGold.$wifi",
    "event.StartApp.$os_version"
  ],
  "session_interval": "1200",
  "from_date": "2017-05-01",
  "to_date": "2017-05-22",
  "detail": true,
  "col_limit": "20",
  "row_limit": "7",
  "sampling_factor": 64,
  "is_aggregate": "false", // 当前节点是否表示更多
  "edge_type": "ALL", // 可以是WASTAGE，RETENTION和ALL，分别表示流失节点，后续事件统计，该节点合计人数
  "is_next_aggregate": "false", // 后续节点是否表示更多
  "num_per_page": 50,
  "all_page": true,
  "filter": {},
  "use_cache": false
}
{
  "users": [
    {
      "id": "1902482830",
      "first_id": "23e3ff2a3ff1e1bc",
      "second_id": "1696144579",
      "profiles": {
        "FavoriteFruits": [
          "Raspberry",
          "Orange"
        ],
        "$name": "陈爍簀",
        "IncomeLevel": "3000~5000",
        "$city": "德阳市",
        "$province": "四川省",
        "$signup_time": 1.432805251963E12,
        "Gender": "男",
        "Age": 20.0
      }
    },
    {
      "id": "3834577070",
      "first_id": "51b0fecc44b5c75b",
      "second_id": "1602971488",
      "profiles": {
        "FavoriteFruits": [
          "Cranberry",
          "Guava",
          "cantaloupe"
        ],
        "$name": "周瀌狙",
        "IncomeLevel": "10000~20000",
        "$city": "嘉峪关市",
        "$province": "甘肃省",
        "$signup_time": 1.432799799529E12,
        "Gender": "女",
        "Age": 20.0
      }
    }
  ],
  "size": 2,
  "page_num": 1,
  "column_name":[
    "FavoriteFruits",
    "$name",
    "Age",
    "Gender",
    "IncomeLevel",
    "$signup_time",
    "$city",
    "$province"
  ]
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/users/list?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
    "slice_element_filter":[
        {
            "slice_event_name":"StartApp",
            "slice_by_value":"8.1"
        }
    ],
    "next_slice_element_filter":[
        {
            "slice_event_name":"SaleGold",
            "slice_by_value":"1"
        }
    ],
    "session_level":"0",
    "source_type":"initial_event",
    "source_event":{
        "event_name":"StartApp",
        "filter":{
            "conditions":[
                {
                    "field":"event.StartApp.$wifi",
                    "function":"isTrue"
                }
            ]
        }
    },
    "event_names":[
        "BuyBullion",
        "BuyGold",
        "SaleGold",
        "StartApp"
    ],
    "by_fields":[
        "event.SaleGold.$wifi",
        "event.StartApp.$os_version"
    ],
    "session_interval":"1200",
    "from_date":"2017-05-01",
    "to_date":"2017-05-22",
    "detail":true,
    "col_limit":"20",
    "row_limit":"7",
    "sampling_factor":64,
    "is_aggregate":"false",
    "edge_type":"ALL",
    "is_next_aggregate":"false",
    "num_per_page":50,
    "all_page":true,
    "filter":{

    },
    "use_cache":false
}

'

5. 自定义查询和用户行为列表

5.1. 自定义查询

[POST /sql/query]

通过 SQL 进行自定义查询，表结构及自定义查询方法详见 自定义查询 功能的介绍。

  • Parameters
  • q: 查询的 SQL，例如 SELECT event,time,user_id FROM events LIMIT 10。
  • format: 可能的值包括
    • csv：默认格式
    • json：每行一个 JSON
    • event_json：导出可以用于直接导入的 Event Track 格式的 Json，1.15 及之后的版本支持，且不支持使用别名（select $utm_source as utm_source ……）
    • profile_json：导出可以用于直接导入的 Profile Set/Track Signup 格式的 Json，1.15 及之后的版本支持，且不支持使用别名（select $utm_source as utm_source ……）
    • item_json: 导出可以用户直接导入神策系统的 item_set 格式的 Json，1.15.1646 及之后的版本才支，且不支持使用别名（select $utm_source as utm_source ……）
    • sql：不直接返回数据，而是翻译为一条可以直接在 Spark/Impala/Hive 里执行的 SQL

q=SELECT * FROM events LIMIT 10

format=csv

event time user_id
RechargeCash 2015-09-02 13:01:00.125336 1731174795
RechargeCash 2015-09-02 02:02:48.133002 1751664241
RechargeCash 2015-09-02 13:01:53.308174 1784316911
RechargeCash 2015-09-02 09:09:07.784417 1793667170
RechargeCash 2015-09-02 09:09:42.420781 1807294808
RechargeCash 2015-09-02 16:04:06.211421 1808422371
RechargeCash 2015-09-02 08:08:44.646672 1810351186
RechargeCash 2015-09-02 00:12:20.456509 1874214895
RechargeCash 2015-09-02 02:02:38.494175 1897237370
RechargeCash 2015-09-02 15:03:08.338102 2012805794

该接口和其它 API 的调用方式有所不同，q 参数直接用 GET/POST 参数传递即可，csv 格式返回的数据为 \t 分隔。一个使用 curl 的例子如下:

curl 'https://saasdemo.cloud.sensorsdata.cn/api/sql/query?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \

-X POST \

--data-urlencode "q=SELECT * FROM events LIMIT 10" \

--data-urlencode "format=csv"

注意： （1）如果查询的事件是预置事件，那么 $ 符号需要使用 \ 进行转义。 （2）如果是导出 items 表中的数据，需要保证神策系统版本为 1.15.1646 及之后的版本。

5.2. 用户行为列表

[POST /users/event/list]

获取一个或者多个用户在某一段时间内的详细行为信息。

{
  "users": [
    86015190,
    81952822,
    87961512
  ],
  "from_date": "2015-04-22",
  "to_date": "2015-04-22",
  // false 表示 users 参数指定的是内部的 user_id，true 表示传入的是 distinct_id
  "distinct_id": false
}
{
  "events": [
    {
      "user_id": "422337220",
      "event": "SaleGold",
      "time": 1432822231055,
      "properties": {
        "$province": "辽宁省",
        "$screen_height": 640.0,
        "$city": "大连市",
        "$os": "iOS",
        "$screen_width": 320.0,
        "$model": "iPhone 5",
        "$lib_version": "0.1.0",
        "$app_version": "1.3",
        "$manufacturer": "Apple",
        "$os_version": "7.0",
        "$wifi": 1.0,
        "$lib": "python",
        "SaleStep": 1.0
      }
    },
    {
      "user_id": "422337220",
      "event": "SaleGold",
      "time": 1432822232022,
      "properties": {
        "$province": "辽宁省",
        "$screen_height": 640.0,
        "$city": "大连市",
        "$os": "iOS",
        "$screen_width": 320.0,
        "$model": "iPhone 5",
        "$lib_version": "0.1.0",
        "$app_version": "1.3",
        "$manufacturer": "Apple",
        "$os_version": "7.0",
        "$wifi": 1.0,
        "$lib": "python",
        "GoldPrice": 240.34,
        "GoldWeight": 16153.0,
        "SaleStep": 2.0
      }
    }
  ]
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/users/event/list?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
    "users":[
        86015190,
        81952822,
        87961512
    ],
    "from_date":"2015-04-22",
    "to_date":"2015-04-22",
    "distinct_id":false
}

'

6. 常见问题

6.1. 查询 API 提示 {"error":"没有访问权限，请检查 project 和 token"} ？

首先：检查下数据接收地址的域名是不是客户系统自己环境登录系统的域名（注意，不是数据接收地址的域名哦）
其次：检查 project 和 token 是不是同一个项目的参数
最后：检查 token 是 admin 账号下的 API Secret 还是通过自己的账号密码获取的 Access token。如果是 API Secret ，token 直接放在 url 链接后面。如果是 Access token ，token 参数不能直接放在 url 链接后面 ，需要放在 Header 参数中，即添加参数：
-H 'sensorsdata-token: {获取的 Access token}'
具体可参考此文档：http://manual.sensorsdata.cn/sa/latest/page-1573880.html#id-.%E5%8A%9F%E8%83%BDAPIv1.13-%E8%8E%B7%E5%8F%96ACCESS_TOKEN

6.2. 查询引擎错误

可以检查下查询的 API 接口和参数名是否对应，以及设置的参数格式是否正确。

6.3. 报错API return 422

API SQL 查询时，$ 符号需要转译

6.4. API 查询或者下载用户列表等使用后台分析服务时，504报错

服务转发配置没有配置连接超时时间或者超时时间设置较短，让客户修改超时时间即可。一般我们建议数据接收地址超时时间为 60 ，后台分析服务超时时间为 1800。

6.5. 是否可以使用查询 API 将查询结果返回到客户线上的业务用于实时分析？查询 API 的请求频次有什么限制？

神策查询 API 只适合低频调用，相应速度取决如下两方面：

  1. 实际的查询场景：如数据量、查询数据的时间范围、所用的分析模型或 SQL 的复杂度等；
  2. 硬件和网络配置：如 CPU、内存、网卡、硬盘等

在查询场景和神策服务器配置匹配的前提下，神策建议 API 调用频率保持在分钟级，单次查询的数据范围在 1 万条以内，同一时间最大并发请求量不超过 10 个，以确保查询相应和神策服务性能稳定。如条件超出如上描述范围，可能出现无法响应/查询慢/甚至神策服务性能不稳定情况。
如上为神策根据历史对接经验给出，考虑到不同客户查询调用的场景各有差异，建议以实测为准，根据实际测试结果合理调整查询条件和调用频次。