Umami API 完全指南：自托管网站分析接口详解

前言

Umami 是一款开源的网站分析工具，主打隐私优先。除了通过 Web 界面查看数据，Umami 还提供了完整的 REST API，让你可以程序化地获取和管理分析数据。本文将详细介绍 Umami 自托管版的所有 API 接口及使用方法。

认证方式

自托管版 Umami 需要先登录获取 Token，然后在后续请求中携带 Token。

获取 Token

curl -X POST https://你的umami域名/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "你的密码"}'

返回示例：

{
  "token": "eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A",
  "user": {
    "id": "xxx",
    "username": "admin",
    "role": "admin"
  }
}

使用 Token

在后续所有 API 请求中添加 Authorization 头：

curl https://你的umami域名/api/websites \
  -H "Authorization: Bearer <token>"

验证 Token

curl -X POST https://你的umami域名/api/auth/verify \
  -H "Authorization: Bearer <token>"

网站管理 API

获取所有网站

GET /api/websites

参数：

• includeTeams - 是否包含团队网站
• search - 搜索关键词
• page - 页码
• pageSize - 每页数量

创建网站

POST /api/websites
Content-Type: application/json

{
  "name": "我的网站",
  "domain": "example.com"
}

获取/更新/删除网站

GET    /api/websites/:websiteId      # 获取详情
POST   /api/websites/:websiteId      # 更新
DELETE /api/websites/:websiteId      # 删除
POST   /api/websites/:websiteId/reset # 重置数据

会话统计 API

这是最常用的 API，用于获取访问统计数据。

获取会话列表

GET /api/websites/:websiteId/sessions?startAt=1704067200000&endAt=1704153600000

返回每个访客的详细信息：浏览器、操作系统、设备、国家、城市、访问次数等。

获取统计摘要

GET /api/websites/:websiteId/sessions/stats?startAt=xxx&endAt=xxx

返回：

{
  "pageviews": {"value": 2924},
  "visitors": {"value": 905},
  "visits": {"value": 1050},
  "countries": {"value": 84},
  "events": {"value": 517}
}

按时段统计

GET /api/websites/:websiteId/sessions/weekly?timezone=Asia/Shanghai

单个会话详情

GET /api/websites/:websiteId/sessions/:sessionId           # 会话信息
GET /api/websites/:websiteId/sessions/:sessionId/activity   # 活动记录
GET /api/websites/:websiteId/sessions/:sessionId/properties # 会话属性

事件 API

用于追踪自定义事件（如按钮点击、表单提交等）。

获取事件列表

GET /api/websites/:websiteId/events?startAt=xxx&endAt=xxx

事件数据分析

GET /api/websites/:websiteId/event-data              # 按事件分组
GET /api/websites/:websiteId/event-data/events       # 事件名统计
GET /api/websites/:websiteId/event-data/fields       # 事件字段
GET /api/websites/:websiteId/event-data/properties   # 属性统计
GET /api/websites/:websiteId/event-data/values       # 属性值统计
GET /api/websites/:websiteId/event-data/stats        # 聚合统计

团队管理 API

团队操作

GET    /api/teams                    # 获取所有团队
POST   /api/teams                    # 创建团队
POST   /api/teams/join               # 加入团队（需要 accessCode）
GET    /api/teams/:teamId            # 获取团队
POST   /api/teams/:teamId            # 更新团队
DELETE /api/teams/:teamId            # 删除团队

团队成员

GET    /api/teams/:teamId/users           # 成员列表
POST   /api/teams/:teamId/users           # 添加成员
POST   /api/teams/:teamId/users/:userId   # 更新角色
DELETE /api/teams/:teamId/users/:userId   # 移除成员

角色类型：team-owner、team-manager、team-member、team-view-only

用户管理 API

仅自托管版管理员可用。

POST   /api/users                      # 创建用户
GET    /api/users/:userId              # 获取用户
POST   /api/users/:userId              # 更新用户
DELETE /api/users/:userId              # 删除用户
GET    /api/users/:userId/websites     # 用户网站
GET    /api/users/:userId/teams        # 用户团队

角色类型：admin、user、view-only

通用过滤参数

大部分统计接口支持以下过滤参数：

参数	说明
startAt	开始时间（毫秒时间戳）
endAt	结束时间（毫秒时间戳）
path	URL 路径
referrer	来源
browser	浏览器
os	操作系统
device	设备类型（Mobile/Desktop）
country	国家
city	城市
page	页码
pageSize	每页数量

实战示例

获取昨天到今天的访问统计：

#!/bin/bash

# 配置
UMAMI_URL="https://your-umami.example.com"
USERNAME="admin"
PASSWORD="your-password"
WEBSITE_ID="your-website-id"

# 登录获取 Token
TOKEN=$(curl -s -X POST "$UMAMI_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -d "{\"username\": \"$USERNAME\", \"password\": \"$PASSWORD\"}" \
  | jq -r '.token')

# 计算时间范围（昨天到现在）
START_AT=$(date -d "yesterday" +%s)000
END_AT=$(date +%s)000

# 获取统计
curl -s "$UMAMI_URL/api/websites/$WEBSITE_ID/sessions/stats?startAt=$START_AT&endAt=$END_AT" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.'

小结

Umami 的 API 设计简洁直观，覆盖了从认证、网站管理、数据统计到团队协作的全部功能。你可以用它来：

• 构建自定义数据看板
• 定时导出分析报告
• 与其他系统集成
• 自动化网站管理

完整 API 文档：https://umami.is/docs/api