网站流量 API 使用指南：正确处理估计、日期和缺失值

流量看板最容易出错的地方，往往发生在请求成功之后：旧快照被标成今天的数据，缺失值被填成零。从第一次调用开始，就应把数字与它的含义一起保存。下面给出请求示例、需要保留的字段，以及不完整批次的处理方式。

先取一条响应，再安排批量任务

在 Vaneform 账号中创建 API key，在自己的终端或服务器设置 VANEFORM_API_KEY 环境变量。安装 curl 后，下面的命令读取 google.com 的缓存 scale 指标族，并按正常账号积分规则处理。环境变量缺失时命令会停止；密钥只留在受控终端或服务器。

使用 scale.visits 前，检查外层资源 status 和 scale.status。自己记录的读取时间与 scale.month、scale.as_of 分开保存。成功请求也可能返回 partial 或 missing 快照，进入图表前要查看实际字段。

curl --silent --show-error --fail-with-body --max-time 30 \
  --header "Authorization: Bearer ${VANEFORM_API_KEY:?Set VANEFORM_API_KEY}" \
  "https://vaneform.com/api/v1/domains/google.com/scale"

参考资料

Vaneform：认证与域名读取

哪些字段能保护比较结果的含义

Vaneform 公开 scale 资源使用下列字段。本文按 2026 年 10 月 8 日的契约核对，当前接口与访问规则以 API 文档为准。公开响应通过产品的估计类型表达口径，客户端应读取该字段，避免依赖内部数据供应商标识。

scale.estimate：site 或 search，标明估计类型。
scale.visits：可用时提供的访问估计。
scale.month 与 scale.as_of：接口提供的统计月份和观察日期。
scale.confidence：接口提供的定性可信度标签。
scale.status：流量指标族状态，需要和资源整体状态一起查看。
scale.monthly_visits：可用的月份与访问序列，保留每个点对应的月份。

参考资料

Vaneform：当前公开 OpenAPI 契约

保留完整含义的模拟 scale 片段

以下 JSON 是虚构的 scale 对象片段，用来展示比较记录需要保留的字段，完整响应还包含外层资源信息。通过已认证 API 请求 GET /api/v1/domains/example.com/scale 可以读取 scale 指标族；密钥设置和完整响应形状见下方 API 文档。

示例中的 42,000 对应 9 月，即使任务在 10 月读取，也应保留该月份。medium 是定性标签；若把它转成自行设定的 70% 概率，就会引入响应没有提供的含义。

{
  "status": "ready",
  "estimate": "site",
  "visits": 42000,
  "month": "2026-09",
  "as_of": "2026-09-30",
  "confidence": "medium"
}

缺失观察会改变汇总分母

假设一个三域名教学批次返回 42,000 次、18,000 次和一个缺失值，可用观察合计 60,000 次，两个可观察域名的平均值为 30,000 次，覆盖情况应写成三者中有两者可用。若用零填补缺失，平均值会变成 20,000 次，并隐藏覆盖缺口。

趋势图遇到缺失月份时保留断点；展示最后可用观察时，明确保留原月份。看板可以在覆盖不完整的情况下继续提供价值，后续观察补齐数据时，也能保留此前复查时所掌握的信息。

比例单位与访问限制需要单独确认

Vaneform 的 scale.sources 渠道值是比例，0.25 显示为 25%；它应与 visits_mom_change_pct 这类百分比变化字段区分。把已是百分比的变化值再次乘以 100，会让原本正确访问数字对应的变化被放大。

截至本文核对日期，Free 账号每个 UTC 月有 100 点普通 API 域名读取额度；关键词查询、关键词排名和 include=search 需要 Pro。读取缓存仍应按账号使用规则处理，结合文档中的账号和错误信息规划有边界的任务，并保留请求标识用于排查失败。

参考资料

Vaneform：API 用量、字段与错误说明

重试前先看错误码

401 的 unauthorized 或 invalid_api_key 需要修正凭据；403 的 search_requires_pro 或 pro_required 需要对应套餐，或改为当前可用能力的请求。原样重复请求无法解决这两类问题。

429 需要继续看 error.code：credits_exhausted 和 lookup_limit_exceeded 对应额度问题，应等待相应额度重置或处理账号额度；lookup_rate_exceeded 对应请求速度，需要降低频率，并在返回 Retry-After 时遵守它。临时错误也应限制重试次数，并保留 error.request_id 排查。

批次中断后，记录哪些域名已经取得可用观察，哪些因适合重试的原因失败，并保留成功快照的原统计期与状态。恢复前先检查未完成行和剩余额度，只继续处理还需要的工作。这样能减少重复操作，并清楚区分已保存观察与未取得可用指标的尝试。

参考资料

Vaneform：已定义错误码