Skip to content

reference.md

Latest commit

 

History

History
167 lines (131 loc) · 4.03 KB

reference.md

File metadata and controls

167 lines (131 loc) · 4.03 KB
Raw

Umami API Reference

CLI 封装了常用读接口。参数细节以 Umami 官方文档为准：Website statistics。

认证

自托管实例需要：

环境变量 说明
UMAMI_API_CLIENT_ENDPOINT API 根路径，如 https://analytics.example.com/api
UMAMI_USERNAME 登录用户名
UMAMI_PASSWORD 登录密码
UMAMI_API_CLIENT_SECRET 可选；仅在使用 USER_ID + APP_SECRET 无密码鉴权时需要

CLI 流程：login(username, password) → 获取 Bearer token → 调用读接口。

时间参数

参数 类型 说明
startAt number 起始时间戳（毫秒）
endAt number 结束时间戳（毫秒）
timezone string 时区，如 Asia/Shanghai
unit string 时间桶：minute | hour | day | month | year

unit 上限

unit 最大范围
minute 60 分钟
hour 30 天
day 6 个月
month 无限制
year 无限制

Metric Types（--type）

type 说明
path URL 路径
entry 入口页
exit 退出页
title 页面标题
query URL 查询参数
referrer 来源 URL
channel 渠道（Direct / Organic / Referral 等）
domain 来源域名
country 国家
region 省/州
city 城市
browser 浏览器
os 操作系统
device 设备类型
language 浏览器语言
screen 屏幕分辨率
event 自定义事件名
hostname 主机名
tag 标签
distinctId distinct ID

过滤器（高级）

部分 API 支持 filters 对象，CLI 首版未暴露全部 filter 参数。若需按 UTM、path 等过滤，可扩展 CLI 或使用 executeRoute。

常用 filter 字段：

字段 说明
path URL 路径
referrer 来源
browser / os / device 客户端环境
country / region / city 地域
utmSource / utmMedium / utmCampaign UTM 参数
event 事件名
segment / cohort 分段/群组 UUID

响应字段

GET /websites/:id/stats

{
  "pageviews": { "value": 15171, "prev": 38675 },
  "visitors": { "value": 4415, "prev": 10568 },
  "visits": { "value": 5680, "prev": 14595 },
  "bounces": { "value": 3567, "prev": 9364 },
  "totaltime": { "value": 809968, "prev": 2182387 }
}
  • value：当前周期
  • prev：上一等长周期（用于环比）

GET /websites/:id/metrics

[{ "x": "Mac OS", "y": 1918 }]
  • x：维度值
  • y：访客数

GET /websites/:id/metrics/expanded

[{
  "name": "Mac OS",
  "pageviews": 74020,
  "visitors": 16982,
  "visits": 24770,
  "bounces": 15033,
  "totaltime": 149156302
}]

GET /websites/:id/pageviews

{
  "pageviews": [{ "x": "2025-10-19T07:00:00Z", "y": 4129 }],
  "sessions": [{ "x": "2025-10-19T07:00:00Z", "y": 1397 }]
}

注：SDK 类型定义使用 t/y，实际 API 可能返回 x/y，解析时两种都兼容。

GET /websites/:id/active

{ "visitors": 5 }

或 SDK 类型 { "x": 5 } — 以实际返回为准。

GET /websites/:id/daterange

{
  "startDate": "2025-12-06T00:00:00Z",
  "endDate": "2026-03-11T21:00:00Z"
}

CLI 命令 ↔ API

CLI API
websites GET /me/websites
stats GET /websites/:id/stats
pageviews GET /websites/:id/pageviews
metrics GET /websites/:id/metrics
metrics --expanded GET /websites/:id/metrics/expanded
active GET /websites/:id/active
events GET /event-data/stats, /events, /fields
daterange GET /websites/:id/daterange

术语

术语 含义
Pageviews (PV) 页面被加载的总次数
Visitors (UV) 独立访客数
Visits 会话/访问次数
Bounces 只访问一个页面就离开的会话
Bounce rate 跳出率 = bounces / visits
Total time 所有会话停留时间之和（秒）