**版本：202601**

# 查询 UTM 数据分析

**POST** `/openapi/2026-01/data-analysis/utm`

按 UTM 参数（来源、媒介、活动名称、关键词、活动内容）分组获取流量来源分析数据，并包含随时间变化的趋势数据。

## 请求

**application/json**

**请求体 | 示例**

**请求体 (required)**

- `begin_time` string (required)

  开始时间，Unix 时间戳（秒），以字符串形式传递，例如 "1748736000"
- `end_time` string (required)

  结束时间，Unix 时间戳（秒），以字符串形式传递，例如 "1781481600"；应大于 begin\_time
- `time_zone` int32

  时区偏移（小时）；推荐范围 -12 至 14
- `cursor` string

  分页游标
- `page_size` int32

  每页记录数

  **默认值：** `10`
- `page` int32

  页码（从 1 开始），与 cursor 互斥
- `sort_by` string

  排序字段，可选值：

  *   `view_client_count`：独立访客数
  *   `uv_rate`：独立访客占比
  *   `product_views_count`：商品详情页浏览次数
  *   `add_to_cart_count`：加购次数
  *   `begin_checkout_count`：发起结账次数
  *   `orders_count`：订单数量
  *   `orders_count_rate`：订单数量占比
  *   `transform_rate`：整体转化率
  *   `product_sales`：商品销售额
  *   `product_sales_rate`：商品销售额占比
  *   `per_customer_sales`：客单价
  *   `avg_elapse`：平均会话时长
  *   `avg_depth`：每次会话平均浏览页数
  *   `place_order_client_count`：下单用户数
  *   `first_order_customers`：首单顾客数
  *   `first_order_customers_rate`：首单顾客占比
  *   `date`：日期
  *   `escape_rate`：跳出率
- `sort_direction` string

  排序方向，可选值：`asc`（升序）、`desc`（降序）
- `date_by` string

  日期分组方式，可选值：空字符串（汇总）、`day`（按天）
- `filters` object[]

  结构化筛选条件列表（可选），按 UTM 维度值筛选结果；列表中各条目之间为 AND 例如：\[{"title": "utm\_medium", "prerequisite": "includes", "values": \["123"\]}\]

  *   Array \[

  - `title` string (required)

    筛选字段名，从 `metrics` 字段获取（需与所请求的 metrics 字段名对应），可选值：

    *   `utm_source`：UTM 来源
    *   `utm_medium`：UTM 媒介
    *   `utm_campaign`：UTM 活动名称
    *   `utm_content`：UTM 活动内容
    *   `utm_term`：UTM 关键词
    *   `country`：国家或地区
    *   `land_url_path`：落地页 URL 路径
  - `prerequisite` string (required)

    筛选运算符，可选值：

    *   `includes`：包含
    *   `equal_to`：是
    *   `not_equal_to`：不是
  - `values` string[]

    筛选值列表
  *   \]
- `filter_crawler_type` string

  爬虫过滤策略，控制统计是否剔除爬虫/机器人流量。可选值：

  *   `no_filter_crawler`：不过滤，统计全部流量（默认）
  *   `official_crawler`：过滤掉已知爬虫/机器人

```json
{
  "begin_time": "string",
  "end_time": "string",
  "time_zone": 0,
  "cursor": "string",
  "page_size": 10,
  "page": 0,
  "sort_by": "string",
  "sort_direction": "string",
  "date_by": "string",
  "filters": [
    {
      "title": "string",
      "prerequisite": "string",
      "values": [
        "string"
      ]
    }
  ],
  "filter_crawler_type": "string"
}
```

## 响应

**200**

OK

**application/json**

**数据结构 | 示例**

**数据结构**

- `code` string

  错误码
- `message` string

  错误信息
- `data` object

  - `count` int32

    记录总数
  - `cursor` string

    分页游标
  - `has_more` boolean

    是否有更多记录
  - `data` object[]

    UTM 报表数据列表

    *   Array \[

    - `date` string

      记录日期，如 "2026-03-30"
    - `utm_source` string

      UTM 活动来源，如 "linkedin"
    - `utm_medium` string

      UTM 活动媒介
    - `utm_campaign` string

      UTM 活动名称
    - `utm_content` string

      UTM 活动内容
    - `utm_term` string

      UTM 活动关键词
    - `country` string

      国家或地区显示名称，如 "中国内地"
    - `country_abbr` string

      国家或地区 ISO 缩写，如 "CN"
    - `land_url_path` string

      落地页 URL 路径，如 "/"
    - `page_views_total` int64

      总页面浏览量
    - `view_client_count` int32

      唯一访客数
    - `uv_rate` float

      唯一访客占总访客的比例，如 50（表示 50%）
    - `product_views_count` int32

      商品详情页浏览次数
    - `add_to_cart_count` int32

      已将商品加入购物车的用户数
    - `begin_checkout_count` int32

      已发起结账的用户数
    - `orders_count` int32

      下单数量
    - `orders_count_rate` float

      订单占总订单的比例，如 0（表示 0%）
    - `transform_rate` float

      访问到下单的转化率，如 0（表示 0%）
    - `product_sales` float

      总销售金额
    - `product_sales_rate` float

      销售额占总销售额的比例，如 0（表示 0%）
    - `per_customer_sales` float

      平均订单价值（每位下单顾客的销售额）
    - `avg_elapse` float

      平均会话时长（微秒）
    - `avg_depth` float

      每次会话平均浏览页数
    - `place_order_client_count` int32

      已下单的唯一用户数
    - `first_order_customers` int32

      新顾客数量（该时期内首次下单）
    - `first_order_customers_rate` float

      新顾客在所有下单顾客中的占比，如 0（表示 0%）
    - `escape_rate` float

      跳出率，如 25（表示 25%）
    *   \]
  - `summary` object

    所有数据项的汇总（摘要行）

    - `page_views_total` int64

      所有行的总页面浏览量
    - `view_client_count` int32

      总唯一访客数
    - `uv_rate` float

      整体访客占比（汇总时始终为 100）
    - `product_views_count` int32

      商品详情页总浏览量
    - `add_to_cart_count` int32

      加购用户总数
    - `begin_checkout_count` int32

      发起结账的用户总数
    - `orders_count` int32

      订单总数
    - `orders_count_rate` float

      订单占比（汇总时始终为 100）
    - `transform_rate` float

      整体转化率
    - `product_sales` float

      总销售金额
    - `product_sales_rate` float

      销售额占比（汇总时始终为 100）
    - `per_customer_sales` float

      所有顾客的平均订单价值
    - `avg_elapse` float

      平均会话时长（微秒）
    - `avg_depth` float

      每次会话平均浏览页数
    - `place_order_client_count` int32

      已下单的总唯一用户数
    - `first_order_customers` int32

      新顾客总数
    - `first_order_customers_rate` float

      新顾客占比
    - `escape_rate` float

      整体跳出率

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "count": 0,
    "cursor": "string",
    "has_more": true,
    "data": [
      {
        "date": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_content": "string",
        "utm_term": "string",
        "country": "string",
        "country_abbr": "string",
        "land_url_path": "string",
        "page_views_total": 0,
        "view_client_count": 0,
        "uv_rate": 0,
        "product_views_count": 0,
        "add_to_cart_count": 0,
        "begin_checkout_count": 0,
        "orders_count": 0,
        "orders_count_rate": 0,
        "transform_rate": 0,
        "product_sales": 0,
        "product_sales_rate": 0,
        "per_customer_sales": 0,
        "avg_elapse": 0,
        "avg_depth": 0,
        "place_order_client_count": 0,
        "first_order_customers": 0,
        "first_order_customers_rate": 0,
        "escape_rate": 0
      }
    ],
    "summary": {
      "page_views_total": 0,
      "view_client_count": 0,
      "uv_rate": 0,
      "product_views_count": 0,
      "add_to_cart_count": 0,
      "begin_checkout_count": 0,
      "orders_count": 0,
      "orders_count_rate": 0,
      "transform_rate": 0,
      "product_sales": 0,
      "product_sales_rate": 0,
      "per_customer_sales": 0,
      "avg_elapse": 0,
      "avg_depth": 0,
      "place_order_client_count": 0,
      "first_order_customers": 0,
      "first_order_customers_rate": 0,
      "escape_rate": 0
    }
  }
}
```