如何通过GA4 API获取自定义事件参数‘term’的搜索词及搜索次数？

先排查当前代码返回空的核心原因 #

• 维度名称错误：GA4自定义维度的API名称并非直接使用参数名term，而是你在GA4后台创建自定义维度时设置的专属API标识。比如你创建时将API名称设为search_term，那维度名应为customEvent:search_term，而非customEvent:term。
• 数据延迟：GA4数据通常存在24-48小时的处理延迟，需确认你的事件数据已被GA4完全收集并处理。
• 未过滤目标事件：如果你的搜索行为对应特定事件名称（如site_search），需添加事件名称过滤，否则eventCount会统计所有事件，导致维度与指标无法匹配返回空结果。

修复后的GA4 API代码示例 #

假设你的自定义事件名称为site_search，自定义维度的API名称为search_term（关联了term参数），修改代码如下：

async function runReport() {
  const [response] = await analyticsDataClient.runReport({
    property: `properties/${propertyId}`,
    dateRanges: [
      {
        startDate: '2021-03-31',
        endDate: 'today',
      },
    ],
    dimensions: [
      {
        name: 'customEvent:search_term', // 替换为你的自定义维度API名称
      }
    ],
    metrics: [
      {
        name: 'eventCount',
      },
    ],
    // 过滤仅统计目标搜索事件
    dimensionFilter: {
      filter: {
        fieldName: 'eventName',
        stringFilter: {
          matchType: 'EXACT',
          value: 'site_search' // 替换为你的自定义事件名称
        }
      }
    }
  });

  console.log('Report result:');
  if (response.rows.length === 0) {
    console.log('无数据返回，请检查维度名称、事件名称或等待数据延迟结束');
  } else {
    response.rows.forEach(row => {
      console.log(`搜索词: ${row.dimensionValues[0].value}, 搜索次数: ${row.metricValues[0].value}`);
    });
  }
}

其他可行实现方法 #

方法1：直接使用事件参数作为维度（无需提前配置自定义维度） #

GA4支持直接调用事件参数作为维度，无需提前创建自定义维度，只要事件确实携带了term参数即可：

async function runReport() {
  const [response] = await analyticsDataClient.runReport({
    property: `properties/${propertyId}`,
    dateRanges: [
      {
        startDate: '2021-03-31',
        endDate: 'today',
      },
    ],
    dimensions: [
      {
        name: 'eventParams.term', // 直接引用事件参数
      },
    ],
    metrics: [
      {
        name: 'eventCount',
      },
    ],
    dimensionFilter: {
      filter: {
        fieldName: 'eventName',
        stringFilter: {
          matchType: 'EXACT',
          value: 'site_search' // 替换为你的自定义事件名称
        }
      }
    }
  });

  console.log('Report result:');
  response.rows.forEach(row => {
    console.log(`搜索词: ${row.dimensionValues[0].value}, 搜索次数: ${row.metricValues[0].value}`);
  });
}

方法2：GA4后台探索报表导出 #

如果编程方式暂时受阻，可直接通过GA4后台生成报表并导出：

• 进入GA4后台，点击「探索」→「空白探索」
• 添加维度：事件参数 > term，指标：事件数
• 添加过滤器：事件名称等于你的搜索事件名
• 生成报表后，点击右上角「导出」→「CSV」获取数据

方法3：BigQuery查询（需已关联GA4属性） #

若你的GA4已链接到BigQuery，可直接查询原始数据：

SELECT
  event_params.value.string_value AS search_term,
  COUNT(*) AS search_count
FROM
  `your-project-id.analytics_xxxxxx.events_*`
WHERE
  event_name = 'site_search' -- 替换为你的事件名称
  AND _TABLE_SUFFIX BETWEEN '20210331' AND FORMAT_DATE('%Y%m%d', CURRENT_DATE())
  AND EXISTS (SELECT 1 FROM UNNEST(event_params) WHERE key = 'term')
GROUP BY
  search_term
ORDER BY
  search_count DESC

内容的提问来源于stack exchange，提问作者Antonio Lok