API参考
⚠️ 使用说明：
- API接口需要登录后通过后台「设置」→「API Token」页面获取API Token
- 部分管理接口仅限管理员账号使用
- 所有接口的请求速率限制为每分钟 100 次
- 私有化部署版本的接口地址请替换为你的自有域名
认证方式
所有需要认证的接口，必须在HTTP请求头中携带Bearer Token：
http
Authorization: Bearer {your_api_token}
请求示例（使用curl）：
bash
curl -X GET "https://your-domain/api/stats/tid_xxx/overview?period=7d" \ -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json"
基础接口前缀
所有API接口的基础URL为：
text
https://your-domain/api
数据查询接口
GET/api/stats/:siteId/overview
获取站点概览统计数据，包含PV、UV、跳出率、平均停留时长等核心指标。
路径参数：
siteId：站点ID（即Tracking ID，如 tid_xxxxxxxxxx）
查询参数：
period：时间范围，可选值：1d, 7d, 30d, 90d, 180d, 365d，默认 7dfrom：开始日期，格式 YYYY-MM-DD（与period二选一）to：结束日期，格式 YYYY-MM-DD
响应示例：
json
{
"code": 0,
"data": {
"pv": 125430,
"uv": 45210,
"bounce_rate": 0.42,
"avg_duration": 185,
"pageviews_growth": 0.12,
"visitors_growth": 0.08
}
}
GET/api/stats/:siteId/realtime
获取实时访客数据，包括当前在线人数、最近访问页面、来源等。
路径参数：
siteId：站点ID
查询参数：
limit：返回条数，默认 20，最大 100
响应示例：
json
{
"code": 0,
"data": {
"online": 128,
"recent_visitors": [
{
"visitor_id": "v_xxx",
"page": "/docs",
"referrer": "https://google.com",
"country": "CN",
"device": "desktop",
"browser": "Chrome",
"started_at": "2025-01-15T10:30:00Z"
}
]
}
}
GET/api/stats/:siteId/pages
获取页面访问统计，按页面路径聚合。
路径参数：
siteId：站点ID
查询参数：
period：时间范围，默认 7dlimit：返回条数，默认 20，最大 500offset：分页偏移量，默认 0
响应示例：
json
{
"code": 0,
"data": [
{
"path": "/",
"title": "首页",
"pv": 35420,
"uv": 28100,
"bounce_rate": 0.38,
"avg_duration": 95
},
{
"path": "/docs",
"title": "文档",
"pv": 18230,
"uv": 12500,
"bounce_rate": 0.28,
"avg_duration": 240
}
]
}
GET/api/stats/:siteId/sources
获取来源统计，包括来源域名、搜索引擎、UTM参数等。
路径参数：
siteId：站点ID
查询参数：
period：时间范围，默认 7dtype：来源类型，可选值：referrer, search, utm_source, utm_medium, utm_campaign
响应示例：
json
{
"code": 0,
"data": [
{
"source": "google",
"visitors": 8520,
"percentage": 0.24
},
{
"source": "baidu",
"visitors": 6210,
"percentage": 0.17
},
{
"source": "(direct)",
"visitors": 15800,
"percentage": 0.44
}
]
}
GET/api/stats/:siteId/devices
获取设备统计，包括设备类型、浏览器、操作系统。
GET/api/stats/:siteId/geo
获取地理位置统计，按国家/省份/城市聚合。
GET/api/stats/:siteId/events
获取自定义事件统计数据。
查询参数：
event_name：可选，按事件名称筛选
站点管理接口
GET/api/sites
获取当前账号下的所有站点列表。
响应示例：
json
{
"code": 0,
"data": [
{
"id": "tid_xxxxxxxxxx",
"name": "我的网站",
"domain": "example.com",
"type": "website",
"created_at": "2025-01-01T00:00:00Z"
}
]
}
POST/api/sites
创建新站点。
请求体：
json
{
"name": "我的新网站",
"domain": "new.example.com",
"type": "website",
"timezone": "Asia/Shanghai"
}
字段说明：
name：站点名称，必填domain：域名，必填type：类型，可选值：website, miniprogram，默认 websitetimezone：时区，默认 Asia/Shanghai
GET/api/sites/:siteId
获取单个站点的详细信息。
DELETE/api/sites/:siteId
删除站点（⚠️ 不可恢复，删除后所有数据将被清除）。仅限管理员。
数据采集接口
💡 注意：数据采集接口为公开接口，无需认证，由SDK自动调用。你通常不需要手动调用此接口。
GETPOST/api/collect
数据采集上报接口，支持GET和POST两种方式。
通用参数：
tid：Tracking ID，必填type：事件类型，pageview / event / performance / errorurl：当前页面URLref：来源URLuid：访客匿名IDscreen：屏幕分辨率，如 1920x1080lang：浏览器语言
自定义事件参数（type=event）：
event_name：事件名称event_props：事件属性，JSON字符串
性能参数（type=performance）：
lcp：LCP指标，毫秒fid：FID指标，毫秒cls：CLS指标fp：FP指标，毫秒fcp：FCP指标，毫秒
GET请求示例（像素追踪）：
http
GET /api/collect?tid=tid_xxx&type=pageview&url=https%3A%2F%2Fexample.com%2F&ref=https%3A%2F%2Fgoogle.com%2F&uid=v_xxx HTTP/1.1 Host: your-domain User-Agent: Mozilla/5.0 ...
POST请求示例：
bash
curl -X POST "https://your-domain/api/collect" \
-H "Content-Type: application/json" \
-d '{
"tid": "tid_xxx",
"type": "event",
"event_name": "purchase",
"event_props": {
"amount": 99,
"product_id": "P123"
},
"url": "https://example.com/product/123",
"uid": "v_xxx"
}'
响应：
text
HTTP/1.1 200 OK Content-Type: image/gif GIF89a... （返回1x1透明像素）
错误码说明
| 错误码 | 说明 |
|---|---|
0 | 成功 |
400 | 请求参数错误 |
401 | 未授权，Token无效或过期 |
403 | 权限不足 |
404 | 资源不存在 |
429 | 请求过于频繁，触发速率限制 |
500 | 服务器内部错误 |
📚 更多接口：
本文档列出了常用的核心接口。完整的API文档包含更多细分维度接口、事件属性查询、导出接口等，请登录后台在「API文档」菜单中查看完整的交互式文档（支持在线调试）。
💡 SDK封装：
建议优先使用官方SDK进行数据采集，SDK会自动处理参数编码、批量上报、重试、用户标识生成等逻辑，无需手动调用collect接口。