@gscdump/ 分析
为Google搜索控制台数据提供SEO分析器和报告. 对已有的行使用纯函数,或对照源运行分析器.
安装
npm install @gscdump/analysis
节点(Node.js 22)或更新的节点消费者需要.
选择导出
| 子路径 | 目的 |
|---|---|
@gscdump/analysis | 纯分析器、浏览器发送和共享分析器合同 |
@gscdump/analysis/registry | 所有30个注册分析器,包括SQL执行 |
@gscdump/analysis/report | 报告登记册, runReport和格式化 |
@gscdump/analysis/source | 复合和内燃工厂 |
@gscdump/analysis/sitemap-health | 无进口品的Sitemp保健三角洲和站点地图倒塌检查 |
@gscdump/analysis/errors | 输入分析错误和渲染帮助 |
@gscdump/engine 拥有分析器、源和期合同.
分析根是共同合同的再出口.
默认的注册会导入每个分析器; 当您需要一个更小的浏览器捆绑时避免它 .
分析行
import { analyzeDecay, analyzeMovers } from '@gscdump/analysis'
const current = [{
query: 'example query',
page: 'https://example.com/docs',
clicks: 40,
impressions: 1000,
ctr: 0.04,
position: 8,
}]
const previous = [{
query: 'example query',
page: 'https://example.com/docs',
clicks: 100,
impressions: 1000,
ctr: 0.1,
position: 4,
}]
const movers = analyzeMovers({ current, previous })
const decay = analyzeDecay({ current, previous })
console.log(movers.declining, decay)
比较函数需要一个 { current, previous } 输入对象.
选项是单独的第二个参数.
见 SEO 指南 一个完全惊人的例子.
来源
使用 runAnalyzerFromSource 选择分析器的行或 SQL 计划:
import { defaultAnalyzerRegistry } from '@gscdump/analysis/registry'
import { createGscApiQuerySource } from '@gscdump/engine-gsc-api'
import { runAnalyzerFromSource } from '@gscdump/engine/analyzer'
import { googleSearchConsole } from 'gscdump'
const client = googleSearchConsole({ accessToken: process.env.GSC_ACCESS_TOKEN! })
const source = createGscApiQuerySource({ client, siteUrl: 'sc-domain:example.com' })
const result = await runAnalyzerFromSource(source, {
type: 'striking-distance',
startDate: '2026-08-01',
endDate: '2026-08-28',
minImpressions: 100,
}, defaultAnalyzerRegistry)
console.log(result.results)
安装 @gscdump/engine, (中文(简体) ), @gscdump/engine-gsc-api,以及 gscdump 以此为例.
十三岁 分析器有行图:
brand, (中文(简体) ),cannibalization, (中文(简体) ),clustering, (中文(简体) ),concentrationdata-detail, (中文(简体) ),data-query, (中文(简体) ),decay, (中文(简体) ),moversopportunity, (中文(简体) ),seasonality, (中文(简体) ),striking-distance, (中文(简体) ),trajectory, (中文(简体) ),zero-click
所有30个分析器都有SQL计划. SQL-只分析器需要一个支持其所需能力的源.
| 工厂 | 导入路径 | 投入 |
|---|---|---|
createGscApiQuerySource | @gscdump/engine-gsc-api | { client, siteUrl } |
createLiveGscSource | @gscdump/engine-gsc-api | { siteUrl, getAccessToken } |
createEngineQuerySource | @gscdump/engine/source | { engine, ctx } |
createSqliteQuerySource | @gscdump/engine-sqlite | { executor, siteId, regex? } |
createInMemoryQuerySource | @gscdump/analysis/source | { queryRows } |
createCompositeSource | @gscdump/analysis/source | { engine, live, site } |
综合资料来源, site 包含 oldestDateSynced, (中文(简体) ), newestDateSynced选择 coveredSpans。 。 。 .
它在存储覆盖缺失或存储维度无法回答查询时会向Google传送支持的查询.
SQL执行总是使用"引擎".
报告
报告将分析器合并为受约束的区段.
创建后 source 上,运行一个报告,由该来源支持:
import { defaultReportRegistry, runReport } from '@gscdump/analysis/report'
import { resolveWindow } from '@gscdump/engine/period'
import { getLatestGscDate } from 'gscdump/dates'
const report = defaultReportRegistry.getReport('movers')!
const window = resolveWindow({ preset: 'last-28d', anchor: getLatestGscDate(), comparison: 'prev-period' })
const result = await runReport(report, {
source,
analyzers: defaultAnalyzerRegistry,
ctx: {
site: 'sc-domain:example.com',
window,
params: {},
registryVersion: defaultReportRegistry.version,
},
})
console.log(result.sections, result.meta.degraded)
见 报告清单 输入和默认值.
如果可选步骤失败, meta.degraded 实值 true。 。 。 .
所需步骤失败拒绝报告.
使用 defineReport 从 @gscdump/engine/report 定义您自己的报告.
DuckDB 和浏览器使用
对于节点,创建引擎源 createEngineQuerySource({ engine, ctx }) 从 @gscdump/engine/source。 。 。 .
上下文供应 userId 财务报告和审定财务报表 siteId。 。 。 .
节点附件帮助者居住在 @gscdump/engine/node。 。 。 .
对于浏览器, 使用 @gscdump/engine-duckdb-wasm 附加 Parquet 表格.
analyzeInBrowser 使用 query(sql, params, signal?)、选项、分析参数和分析器登记册.
浏览器分析使用附件表格,如 ADR-0001 (韩语)。 。 。 .
用于 SQLite 和 D1, 使用 @gscdump/engine-sqlite。 。 。 .
分析器支持取决于源的SQL方言和能力.
日期窗口
import { resolveWindow } from '@gscdump/analysis'
const window = resolveWindow({ preset: 'last-30d', anchor: '2026-08-28', comparison: 'yoy' })
console.log(window.start, window.end, window.comparison)
每个预设 custom 需要一个 anchor: 窗口包括的最后日期.
传递您数据中最新的完整日期, 如 Store 最新的同步日或 getLatestGscDate() 从 gscdump/dates。 。 。 .
resolveWindow 从来没有读过钟.
预设 : last-7d, (中文(简体) ), last-28d, (中文(简体) ), last-30d, (中文(简体) ), last-90d, (中文(简体) ), last-180d, (中文(简体) ), last-365d, (中文(简体) ), mtd, (中文(简体) ), qtd, (中文(简体) ), ytd, (中文(简体) ), last-quarter,以及 custom。 。 。 .
比较: none, (中文(简体) ), prev-period,以及 yoy。 。 。 . yoy 将窗口往后移364天,因此每天与同一天的同一天相比.
获取预算和产出限制
limit 为行盖上一个分析器返回。 它从来不会封住它读的行.
最多读取行计划 fetchBudget 每个查询行:默认情况下为2.5万行(1个GSC页),最高可达10万行.
meta.total 计算每个分析器的每个匹配数, 不只是返回的行.
SQL 唯一的分析器是例外. 他们还在报到 meta.total 之后 limit数字 : bayesian-ctr, (中文(简体) ), bipartite-pagerank, (中文(简体) ), change-point, (中文(简体) ), ctr-anomaly, (中文(简体) ), intent-atlas, (中文(简体) ), long-tail, (中文(简体) ), query-migration, (中文(简体) ), stl-decompose,以及 trends。 。 。 .
meta.coverage 实值 { kind: 'complete' },或 { kind: 'truncated', fetched } 当查询到达其获取预算时.
短跑会错过行,因此将其总数和排名视为部分.
公共 API
使用上面列出的套件导出 .
下方的文件 src/ 属于私人性质,可能在没有公共移徙途径的情况下发生变化.