使用 statpx REST API 提取您的分析数据
statpx 控制台为您提供了网站流量的清晰可视化摘要。但是，仪表板只是使用分析数据的一种方式。对于开发人员、数据团队和注重自动化的网站所有者，REST API 打开了一组不同的可能性：将流量数字输入到您自己的工具中、构建自定义报告、根据真实数据触发工作流，以及将分析集成到标准 UI 从未设计过的地方。
statpx API 设计得很直接。使用 Bearer 令牌进行身份验证，调用端点，接收 JSON。本指南涵盖了为什么要使用它、身份验证的工作原理、哪些端点可用以及响应的样子。
为什么使用分析 API
与使用仪表板相比，选择 API 的最常见原因是您需要数据存在于 Web 浏览器之外的地方。一些实际例子：
自定义仪表板
您的团队可能已经在 Grafana、Notion、自定义内部工具或 Retool 应用程序中拥有一个仪表板。您可以将 statpx 数据拉入您的团队已经使用的同一个视图中，而不是维护一个单独的浏览器标签页用于分析。单个统一的仪表板减少了上下文切换，并使跨指标关联变得更容易——您可以将流量趋势放在收入数字、支持工单量或部署历史记录旁边。
Slack 或聊天机器人
一个向您团队的 Slack 频道发布每日流量摘要的机器人，或在页面浏览量超过某个数字时提醒一个频道，使用 API 和一个基本脚本很容易构建。机器人按时间表运行，调用 API，格式化结果，然后发布它。无需手动检查，无需提取报告——数据自动发送给团队。
电子表格自动化
Google Sheets 和 Excel 都支持通过脚本从外部 API 拉取数据。一个 Google Apps 脚本每天运行，调用 statpx API，并将今天的页面浏览次数追加到一张表中，这样您就可以获得一个日益增长的历史记录，您可以绘制图表、共享和分析，而无需打开分析仪表板。
CI/CD 管道检查
在部署您网站的新版本后，部署后检查可以查询页面浏览次数时间序列端点，并将部署后几分钟内的流量与前一天同一时间段的流量进行比较。部署直后的显著下降是出了问题的强烈信号。在管道中捕获这一点，在下一个上午的站会之前，比起在几小时后才发现要好得多。
第三方集成
如果您使用可以调用 webhook 或外部 API 的工具（Zapier、Make、n8n）——statpx API 是可连接的。将每周的页面浏览次数拉入 CRM 笔记，将每日会话总数记录到项目管理工具中，或在会话下降到您自己的警报未涵盖的阈值以下时触发 Slack 通知。
身份验证
所有 API 请求都需要身份验证。statpx 使用 API 密钥，您可以从帐户设置中的 API 密钥页面生成这些密钥。每个密钥都有一个您选择的名称，因此您可以为不同的集成创建单独的密钥，并确定如果需要撤销它，正在使用的是哪一个。
重要提示：完整的 API 密钥仅在生成后立即显示一次。复制它并将其安全地存储——密码管理器是正确的位置。如果您丢失了密钥，您必须生成一个新的；没有办法检索原始值。
使用 Bearer 令牌身份验证
在每个请求的 Authorization 标头中传递您的 API 密钥：
一个完整的 curl 示例如下所示：
使用查询参数
或者，您可以将密钥作为查询参数传递。这对于在浏览器中快速测试或在不容易支持自定义标头的工具中非常有用：
对于生产使用，首选标头方法。查询参数可能会出现在服务器日志和浏览器历史记录中，这使得它们不太适合长期密钥。
可用端点
statpx API 使用单一基础 URL https://statpx.com/api/index.php，通过 endpoint 查询参数选择端点。以下六个端点可满足大多数需求。
GET ?endpoint=sites
返回与您帐户关联的所有网站的列表。使用此功能发现您的网站 ID，这些 ID 是其他端点所必需的参数。
请求示例：
响应示例：
GET ?endpoint=stats
返回网站在过去 7、30 或 90 天内的指标。参数：
site_id— 必需，来自endpoint=sites的数字 IDmetric— 以下之一：pageviews（页面浏览量，默认）、sessions（会话）、unique_visitors（独立访客）、bounce_rate（跳出率）、top_pages（热门页面）、top_referrers（热门来源）、countries（国家）range—7、30（默认）或90天
请求示例：
响应示例：
时间序列指标（pageviews、sessions、unique_visitors）返回 total 以及 daily 数组。对于 unique_visitors，total 在整个时间范围内每位访客只计一次，因此通常低于每日数值之和。
GET ?endpoint=pageviews
返回网站页面浏览量和会话数的每日时间序列。对于绘制流量趋势随时间变化的图表非常有用。参数：
site_id— 必需range—7（默认）、30或90天
请求示例：
响应示例：
GET ?endpoint=events
返回您通过 _st('event', …) 跟踪的自定义事件。每个事件都包含其 value 以及您附加的自定义 props。需要网站的所有者或编辑者权限。参数：
site_id— 必需name— 按事件名称筛选（可选）from/to—YYYY-MM-DD（默认：最近 30 天）group—name或value，返回计数而不是原始记录（可选）limit（1–1000，默认 500）和offset用于分页
请求示例：
响应示例：
使用 group=value 时，每个事件名称和值返回一行，包含总次数和不同会话数：
GET ?endpoint=realtime
最近几分钟的实时快照（不含机器人流量），数据与控制台中的"实时"页面相同。任何有权访问该网站的团队成员都可以调用。也接受 endpoint=real_time 作为别名。参数：
site_id— 必填metric—active_visitors、page_views、countries、active_pages、referrers之一。省略则在一次响应中返回全部五项。minutes— 时间窗口，1–30（默认 5）
请求示例：
响应示例：
active_visitors 统计窗口内的不同会话数。列表返回前 10 个国家、前 20 个页面和前 10 个来源。建议每 15–30 秒轮询一次，这样远低于每分钟 120 次请求的限制。
GET ?endpoint=visitors
访客日志，每次页面浏览一行（不含机器人流量），最新的在前。需要网站的所有者或编辑者权限。参数：
site_id— 必填minutes— 滚动时间窗口，1–1440（可选；优先于from/to）from/to—YYYY-MM-DD（默认：今天）limit（1–1000，默认 100）和offset用于分页
请求示例：
响应示例（省略部分字段）：
每一行还包含 title、city、browser 和 os。为保护您的访客，IP 地址经过掩码处理：IPv4 地址的最后一段替换为 x（203.0.113.x），IPv6 地址仅保留前三组（2001:db8:abcd::）。API 永远不会返回完整地址。
立即获取您的 API 密钥
statpx API 密钥对每个帐户免费。生成一个命名密钥，复制一次，然后开始从任何语言或工具查询您的分析数据。随时从 API 密钥页面撤销它。
免费尝试 statpx →管理 API 密钥
statpx API 密钥页面（位于您的帐户设置中）是您创建、命名和撤销密钥的地方。一些实用指南：
为每个集成使用一个密钥
为每个用例创建一个单独的命名密钥：一个用于您的 Slack 机器人，一个用于您的 Google Sheet，一个用于您的 CI 管道。如果您曾经需要撤销其中任何一个的访问权限——因为项目结束、团队成员离开或密钥暴露——您可以仅撤销该密钥，而不会中断其他密钥。
以描述性方式命名密钥
名为"slack-weekly-digest"或"grafana-dashboard-prod"的密钥比"key1"或"api-key-june"更容易管理。名称是您在密钥值消失后唯一拥有的元数据。
定期轮换密钥
对于长期运行的集成，每几个月轮换一次您的 API 密钥是一个合理的安全习惯。生成新密钥，更新集成，验证它有效，然后撤销旧密钥。转换只需要几分钟，并减少了旧密钥在某处被捕获的暴露窗口。
一个简单的 Python 示例
为了说明 API 的使用有多么直接，这里是一个最小的 Python 脚本，可获取网站过去 7 天的页面浏览次数并打印总数：
相同的模式在 Node.js、Ruby、PHP、Go 或任何具有 HTTP 支持的语言中都能工作。该 API 遵循标准 REST 约定——GET 请求、查询参数、JSON 响应、HTTP 状态代码用于错误——因此它与任何工具链都能干净地集成。
接下来要构建什么
该 API 是一个起点，而不是终点。一旦您的数据流入自定义集成，您可以使用它做的有用事情就会复合增长。一个开始是每日页面浏览摘要的 Slack 机器人可以发展为包括热门页面、流量来源分析和周比较。一个开始是基本的下降检测器的 CI 检查可以发展成一个完整的流量健康门，当检测到异常时阻止部署。
约束不是数据——它是您对用数据做什么的想象。从一个简单的集成开始，让它工作，然后让它从那里发展。
底线
分析 REST API 将您的流量数据从仅限仪表板的视图转变为可编程资源——您可以将其输入到 Slack 机器人、电子表格、CI 管道或您的团队已经使用的任何内部工具。实际步骤是从小处开始：生成一个命名 API 密钥，编写一个五行脚本来获取上周的页面浏览次数，并在构建任何更雄心勃勃的东西之前让它工作。一旦数据流动，有用的集成就会快速复合增长。statpx 通过其 API 公开页面浏览量、会话、独立访客和跳出率，每日时间序列可用于在您首选的任何工具中绘制流量趋势。