选SEO数据API,先写出要取得的数据:自己的历史搜索点击、展示和平均位置,用Search Console API;某个地点的一次搜索结果,用SERP数据接口;网站访问和关键事件,用GA4 Data API。
接口只是取数方式,不能把历史平均位置变成此刻排名。下面先分清三种数据来源,再给一份完整GSC请求与读表过程,最后处理分页、失败和自动报告。 API返回行数与指标后,先用Search Console报告读法解释口径,再把数字送进自动报表。
先写出你想取得的一行数据
“做一个SEO看板”还不够具体。可以先写:“每周按查询、页面、国家和设备保存点击、展示、CTR和平均位置。”这是一份自站历史搜索表现,适合GSC。
如果要“每天查美国手机下,我们和三家同行的实际结果URL”,则需要指定条件的SERP采样。GSC只提供有权限资源的数据,不给任意同行的实时搜索列表。
如果要“哪些自然搜索入口触发询盘”,则使用GA4与正确事件;接口不会额外取得每个人在Google输入的自然搜索词。
| 来源 | 主要数据 | 开始前准备 | 容易混淆的地方 |
|---|---|---|---|
| GSC API | 自站历史搜索聚合 | 资源权限、OAuth、日期和维度 | 平均位置当即时名次 |
| SERP API | 指定条件的结果采样 | 服务商账号、地点、语言、设备 | 数组序号当自然排名 |
| GA4 Data API | 站内访问和事件聚合 | GA4权限、资源、兼容字段 | 页面询盘当逐词成交 |
选择后再核费用、配额、覆盖和失败处理。非开发者也能先用界面完成一次分析,确认要保存哪些字段;重复工作足够多时,再自动取数。

GSC最小请求:资源、授权和美国手机过滤
先在Google项目启用API,再按授权文档取得对目标资源的OAuth授权。普通API Key不能读取私有搜索数据;令牌不要写进公开文章、仓库或共享表格。
资源标识也要匹配。网址前缀可能是https://example.com/,域资源则使用sc-domain:example.com。从 Search Console 的资源选择器复制完整前缀,包含协议、主机及路径。请求路径里再对这个值做 URL 编码。
下面是网址前缀资源的教学请求。将网址和日期换成实际值,配置真实授权后才能调用。
POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fexample.com%2F/searchAnalytics/query
Authorization: Bearer <OAUTH_ACCESS_TOKEN>
Content-Type: application/json
{
"startDate": "2026-09-01",
"endDate": "2026-09-07",
"type": "web",
"dimensions": ["query", "page", "country", "device"],
"dimensionFilterGroups": [
{
"groupType": "and",
"filters": [
{"dimension": "country", "operator": "equals", "expression": "usa"},
{"dimension": "device", "operator": "equals", "expression": "MOBILE"}
]
}
],
"rowLimit": 1000,
"startRow": 0
}
这里先按查询、页面、国家和设备分组,再把范围限定美国手机。只添加country和device维度,会分组但不会自动排除其他国家设备;过滤条件才限制本次范围。
日期使用GSC的太平洋时间口径,国家使用接口支持的三字母代码。rowLimit与startRow控制单批返回和偏移,具体字段按Search Analytics query文档核对。
成功响应的一行可能长这样,数值是自拟教学例:
{
"keys": ["industrial lamp", "https://example.com/lamps/", "usa", "MOBILE"],
"clicks": 8,
"impressions": 200,
"ctr": 0.04,
"position": 11.5
}
keys顺序与请求维度一致:查询、页面、国家、设备。后面是8次点击、200次展示、CTR4%、历史平均位置11.5。CTR0.04做一次百分比显示即可,不要在已经转换后再次乘100。
先读前几行,确认国家、设备、URL正确,再导CSV。列可以固定为query,page,country,device,clicks,impressions,ctr,position。这里一行是一组组合,不是一个用户,8次点击也不等于8个唯一客户。
分页与错误处理:别把失败写成0
本例每批1000行,首批满额就用startRow:1000继续,再满额用2000。单次rowLimit官方上限为25000;正常响应没有行,可以结束本次读取。
但HTTP错误不是空结果。建议把返回状态与数据分开记录:
| 当前结果 | 如何保存 | 下一步 |
|---|---|---|
| 成功,1000行 | 范围、偏移、行数、原响应 | 按偏移取下一批 |
| 成功,无行 | 已完成到该偏移 | 结束当前分页 |
| 授权或访问失败 | 状态码、错误正文、请求配置 | 核令牌、范围与资源权限 |
| 配额或临时服务错误 | 错误时间与未完成批次 | 按返回原因和官方限制处理 |
401通常先核凭据;403需要读具体错误,可能是权限、配额或配置问题,不能只重发;429或临时服务错误按规则控制请求与重试。不要把这些批次填成0展示,否则自动报告会制造一场并不存在的流量暴跌。

日志至少留资源、日期、维度、过滤、偏移、行数和状态,例如“偏移0成功1000行;偏移1000失败,尚未完成”。恢复时有明确断点,也能向使用者说明文件是否完整。
例如每次只取一个资源的一天 Web 数据,分页期间保持维度、筛选和日期不变,只增加 startRow。取完后再切到下一天。Search Analytics 对每个资源、每个日期和每种搜索类型最多提供 50,000 行。最后一页为空只能说明当前请求没有更多可返回行。查询隐私和内部取数限制仍会影响覆盖。API使用限制要和文件一起保留。持续大规模历史保存还可以研究BigQuery每日导出,根据任务选择,不能认为有API就替代全部方案。
查即时排名,SERP任务需要哪些条件
以DataForSEO Google Organic Live Advanced为例,提交前确认关键词、地点、语言、设备和深度。地点代码从服务商当前列表核实,不复制一个不知道位置的数字。
给开发者的任务可以写成:查询industrial lamp supplier;已确认美国目标地点;英语;mobile;观察指定深度;保存自然结果的实际URL及对应位置。
拿到结果后先核任务成功,再筛type: "organic"的项。这个接口中,rank_group表示该结果在同类型元素中的位置;rank_absolute表示它在所有结果元素中的位置,包含其他结果类型。广告、问答、图片等可能同时出现,数组第三个对象未必是自然第三名。
例如一条自拟教学项只摘出这些字段:
{
"type": "organic",
"rank_group": 2,
"rank_absolute": 5,
"url": "https://example.com/lamps/"
}
它是自然结果第2,所有元素中第5,并非两次排名冲突。做自然排名记录用rank_group,同时保留rank_absolute、URL和采样条件,才能知道当时的结果环境。DataForSEO字段定义
没有目标域名时,记“本次成功采样的深度内未检出”;任务失败则记“未取得”。这两种状态不填排名0或任意最大值。原响应、条件、时间与实际URL一起保存,之后才有可比记录。
GA4接口与自动报告,怎样接着做
先取自然搜索入口的会话,再取询盘事件
假设你要交接的是“哪些自然搜索入口带来访问,哪些入口相关会话记录了询盘提交”。先启用Analytics Data API,取得目标GA4资源的读取权限及OAuth授权。资源ID是GA4资源的数字编号,不是 G- 开头的衡量ID。下面是请求模板,日期、编号和令牌要换成实际值;示例不包含实际资源的返回数据。
POST https://analyticsdata.googleapis.com/v1beta/properties/123456789:runReport
Authorization: Bearer <OAUTH_ACCESS_TOKEN>
Content-Type: application/json
{
"dateRanges": [{"startDate": "2026-10-01", "endDate": "2026-10-07"}],
"dimensions": [
{"name": "landingPagePlusQueryString"},
{"name": "sessionDefaultChannelGroup"}
],
"metrics": [{"name": "sessions"}],
"dimensionFilter": {
"filter": {
"fieldName": "sessionDefaultChannelGroup",
"stringFilter": {"matchType": "EXACT", "value": "Organic Search"}
}
},
"limit": "1000"
}
landingPagePlusQueryString 是会话首次浏览的页面路径及查询参数,sessionDefaultChannelGroup 是会话默认渠道,sessions 是会话数。例如教学响应按所请求的列返回 /pumps/、Organic Search、200,表示这段范围内该入口有200次自然搜索会话,不是200名独立采购者。日期应按该GA4资源的时区解释,不要直接当成GSC的太平洋时间。字段定义
第二次请求保留相同日期和入口维度,把指标改为 eventCount,并用下面这两项替换第一次请求里的 metrics 和 dimensionFilter:
{
"metrics": [{"name": "eventCount"}],
"dimensionFilter": {
"andGroup": {
"expressions": [
{"filter": {"fieldName": "sessionDefaultChannelGroup", "stringFilter": {"matchType": "EXACT", "value": "Organic Search"}}},
{"filter": {"fieldName": "eventName", "stringFilter": {"matchType": "EXACT", "value": "generate_lead"}}}
]
}
}
}
这不是单独完整请求,而是前一请求的两项替换配置。generate_lead 必须已经在成功提交时正确记录;接口不会替网站创建事件。若同一入口教学结果为6,意思是该范围记录了6次这个事件。用户可能重复提交,6也可能包含无效线索,所以不能直接称为6名客户。
尤其不能把带 eventName 过滤的结果拿来充当全部自然搜索会话。分母取第一次请求的200,第二次只取6次目标事件;6÷200可标为“每次会话平均0.03次提交事件”,不是发生询盘的会话比例。要计算后者,需要发生该事件的会话口径,并另核字段兼容与事件配置。
正式接入前,用同一资源对每份完整请求调用checkCompatibility,并按runReport规范处理返回。保留实际表头、行数、错误和数据限制;模板语法正确不等于已经取得该资源数据。
最后对齐报告口径,不拼出不存在的逐词询盘
GSC查询与GA4询盘可以按页面和相近范围对照,不能因自动化就生成逐人自然搜索词。没有共同记录的连接键,代码也不能靠点击比例补事实。
第一版自动报告不用很大。先取一个资源、一周、少量组合,完成下面四项:字段读得懂;条件正确;状态没有被混成0;界面与API按相同范围能合理对照。界面明细与API截断不同,不要求所有行合计天然等于总计。GSC明细差额
报告应附上数据来源、时间、过滤条件、单位、是否取完数据及原始结果文件。AI生成分析也使用这些条件,先筛掉未完成数据,再写判断。核对这些条件后,再将结果整理进SEO月报,避免把取数错误带进分析。
常见问题
Google官方API能查任意同行即时排名吗?
GSC API提供有权限资源的历史搜索表现,不是任意关键词与同行的即时SERP接口。一次结果采样需要相应服务,并保存条件。
分页取很多次就有全部关键词吗?
不能保证。内部取数与隐私限制仍在,准确表述是取得指定条件下可返回的记录,保留缺失和完成状态。
不会代码,应该先学API再做SEO吗?
先用界面完成一次正确分析,写清字段、筛选和输出。重复取数值得自动化时,再把任务交给开发者;接口不替代内容和业务判断。



