Plausible Analytics 查询API JSON Schema详解

概述

Plausible Analytics 是一款轻量级的网站分析工具，其查询API提供了强大的数据检索能力。本文将从技术角度深入解析其查询API的JSON Schema设计，帮助开发者更好地理解和使用这套API。

核心结构

Plausible的查询API请求体采用JSON格式，遵循严格的Schema验证。主要包含以下几个核心部分：

1. 必填字段：

   • site_id: 要查询的网站域名
   • metrics: 要查询的指标列表
   • date_range: 查询的时间范围

2. 可选字段：

   • dimensions: 结果分组维度
   • filters: 数据过滤条件
   • order_by: 结果排序方式
   • include: 包含的额外信息
   • pagination: 分页设置

时间范围定义

时间范围支持多种灵活的表示方式：

"date_range": {
  "oneOf": [
    { "$ref": "#/definitions/date_range_shorthand" },
    { "$ref": "#/definitions/date_time_range" },
    { "$ref": "#/definitions/date_range" }
  ]
}

1. 简写形式：

   • day: 最近一天
   • 7d: 最近7天
   • month: 当前月
   • year: 今年至今
   • 也支持自定义格式如30d(30天)、6mo(6个月)等

2. 精确日期范围：

   • 支持ISO8601日期格式(如["2024-01-01", "2024-01-31"])
   • 支持带时间的ISO8601格式(如["2024-01-01T00:00:00+03:00", "2024-01-02T12:00:00+03:00"])

指标(Metrics)详解

Plausible支持丰富的分析指标，包括但不限于：

• visitors: 独立访客数
• visits: 访问次数(会话数)
• pageviews: 页面浏览量
• bounce_rate: 跳出率
• visit_duration: 访问时长(秒)
• conversion_rate: 转化率(需配合目标过滤)
• scroll_depth: 页面滚动深度(需配合页面过滤)

每个指标都有明确的业务含义，开发者可根据分析需求选择合适的指标组合。

维度(Dimensions)分析

维度用于对数据进行分组分析，主要分为几类：

1. 事件维度：

   • event:page: 页面URL
   • event:hostname: 主机名
   • event:props:*: 自定义属性

2. 访问维度：

   • visit:source: 流量来源
   • visit:device: 设备类型
   • visit:country: 国家/地区

3. 时间维度：

   • time:day: 按天分组
   • time:week: 按周分组
   • time:month: 按月分组

高级过滤功能

Plausible提供了强大的过滤系统，支持复杂的查询条件：

1. 基础过滤：

   • is/is_not: 精确匹配
   • contains/contains_not: 包含匹配

2. 高级过滤：

   • matches/matches_not: 正则匹配
   • matches_wildcard: 通配符匹配
   • has_done/has_not_done: 行为过滤

3. 逻辑组合：

   • and/or: 逻辑与/或
   • not: 逻辑非

示例：查找来自Google且使用Chrome浏览器的访问

"filters": [
  ["and", [
    ["is", "visit:source", ["google"]],
    ["is", "visit:browser", ["chrome"]]
  ]]
]

结果排序与分页

1. 排序：

   • 可按任意指标或维度排序
   • 支持升序(asc)和降序(desc)

2. 分页：

   • limit: 每页记录数(1-10000)
   • offset: 偏移量

高级功能

1. 时间标签：

   • 启用include.time_labels可获取时间维度的友好标签

2. 数据对比：

   • 支持与前期(previous_period)、去年同期(year_over_year)或自定义时间段对比

3. 总数统计：

   • 启用include.total_rows可获取未分页前的总记录数

最佳实践

1. 性能优化：

   • 尽量缩小时间范围
   • 避免同时查询过多指标
   • 合理使用分页

2. 数据准确性：

   • 注意指标间的兼容性(如conversion_rate需要目标过滤)
   • 理解各指标的计算逻辑

3. 错误处理：

   • 确保所有必填字段都已提供
   • 检查指标和维度的兼容性
   • 验证时间格式是否正确

总结

Plausible Analytics的查询API通过精心设计的JSON Schema，提供了强大而灵活的数据分析能力。理解这套Schema的结构和规则，可以帮助开发者构建出高效、准确的数据查询，从而更好地利用Plausible的分析功能来洞察网站访问情况。无论是简单的流量统计，还是复杂的用户行为分析，这套API都能提供有力的支持。