2026年11月16日,一次针对 Google Trends Explore 页面、关键词为 web scraping 的请求返回了 HTTP 200。Crawlbase 报告了 cb_status=200,而 Google 自己的回答被记录为 original_status=200。正文写着 "Oops! There was a problem displaying this page",并要求读者重试。其中没有任何关键词历史数据。
Explore Markdown 路径在全部二十次首次尝试中都是如此。十九个正文带有 Oops 消息,一个带有 reCAPTCHA 提示。只读取 HTTP 状态的检查会接受其中每一个。流水线必须先确认它请求的 Trends 数据确实到达,才能把这次请求算作有效工作。
本文跟随的实现见 配套代码仓库:请求构造、响应处理、解析器、内容检查、有界重试,以及测试框架记录下的证据。其中 Crawling API 提供获取能力和内置提取路径。应用程序决定哪些返回的正文满足其数据要求。这些数字来自一个地区、一个日历日,仅作为观察结果报告,而不是基准。
- HTTP 200 和
cb_status=200描述的是到达的文档。对于 Google Trends,这个文档可能是一份错误提示。接受响应之前先读正文。 - 内置抓取器通过最多:Trending Now 20/20,使用 JavaScript 令牌的 Explore 18/20。在 Normal 令牌上以 Markdown 形式获取 Explore 的通过率为 0/20。
- 依据判定重试,绝不依据状态码重试。只重试一次,两次尝试都保留,通过的 200 永不重试。
该图把收到文档与收到所需数据区分开来。它不指明 Google Trends 内部是哪个浏览器请求或哪个组件失败了,这次运行也没有确定这一点。
先选 Trends 页面类型,再选抓取路径
测试覆盖三个 URL。按子区域的兴趣是 Explore 响应的一部分,因此在本实现中,关键词历史和地区兴趣不需要单独的目标页面。
| 页面类型 | 测试中的 URL | 项目使用的数据 |
|---|---|---|
| Trending Now | https://trends.google.com/trending?geo=US |
热门查询、搜索量标签、增长率、开始时间、状态和细分词条 |
| Explore | https://trends.google.com/trends/explore?q=web scraping&geo=US&date=today 12-m |
随时间变化的兴趣、按子区域的兴趣和相关查询 |
| Trending RSS | https://trends.google.com/trending/rss?geo=US |
条目标题、近似流量和发布日期 |
Trending Now 回答的是所选地区中哪些搜索正在飙升;保存的抓取器样本反映了页面的 "Past 24 hours"(过去 24 小时)筛选条件。Explore 回答的是某个词条的兴趣在选定时段内如何变化。Google 的 Trending Now 文档 把 RSS 列为导出选项之一;当其较少的字段集足以覆盖任务时,该订阅源就够用了。
Google 的 官方 Trends API alpha 版 是一个独立的接口。运行时其访问权限仅限于选定的测试者,公开概览中也没有列出 Trending Now 数据。本项目没有调用它。项目同样避开了非官方的 pytrends 库,其仓库已于 2025年4月17日归档,最后一次推送记录为 2024年8月10日。新流水线挑选依赖时,这种维护状态很重要。
让请求路径显式化
五种请求形态由 抓取路径模块 定义。每条路径都经过 Crawling API 端点 https://api.crawlbase.com/,包括对 RSS 订阅源的请求。
| 路径 | 区分它的参数 | 矩阵中使用的令牌 |
|---|---|---|
| 渲染 HTML |
page_wait 和 ajax_wait=true
|
JavaScript 令牌 |
| 内置抓取器 |
scraper=google-trends 或 scraper=google-trends-explore
|
Trending Now 用 Normal;Explore 用 JavaScript |
| Markdown | format=md |
Normal 令牌 |
| 无等待 HTML | 不带等待参数的目标 URL | JavaScript 令牌 |
| RSS 抓取 | RSS 目标 URL | Normal 令牌 |
无等待对照组仍然渲染 JavaScript。它与渲染路径的唯一区别是缺少两个显式等待参数。同样,Markdown 结果描述的是实际测试过的 Normal 令牌 Markdown 路径。本文中的每一处比较都写明了其令牌和请求设置。
请求构建器把令牌值排除在参数准备之外。对于抓取器请求,它不返回首选令牌类型;调用方提供选择,来源是 probe-config.json。随后 客户端 读取对应的密钥,并把参数传给 requests.Session.get() 并设置 180 秒超时:
def prepare( path: str, url: str, *, page_wait: int | None = None, ajax_wait: bool | None = None, scraper: str | None = None, store: bool = False, ) -> tuple[str | None, dict]: """Return (token_kind, params) for a path. token_kind is "js", "normal", or None. None means the caller chooses the token (the built-in scrapers do not name one). """ params = {"url": url} if store: params["store"] = "true" if path == "rendered": params["page_wait"] = str(page_wait) params["ajax_wait"] = "true" if ajax_wait else "false" return "js", params if path == "scraper": params["scraper"] = scraper or "" return None, params if path == "markdown": params["format"] = "md" return "normal", params if path == "nowait": return "js", params if path == "rss": return "normal", params raise ValueError(f"unknown path {path}")
渲染的 Trending Now 使用 page_wait=5000 和 ajax_wait=true。渲染的 Explore 使用 page_wait=8000 和 ajax_wait=true. page_wait 是页面加载后的固定延迟,单位为毫秒;而 ajax_wait=true 等待网络活动平息后再捕获页面,自身不增加固定延迟。
让探测的令牌决策可供检查
探测共发出十三次目标调用。它对每个内置抓取器都尝试两种令牌类型,并覆盖 HTML 和 Markdown 路径、RSS、一个单独的对比查询,以及一次启用存储的 RSS 请求。它还在前后各记录一次账户摘要,两次账户调用之间至少间隔五分钟。
探测的原始正文没有签入仓库,因此发现结果保存在矩阵读取的配置里:Normal 令牌得到空的图表对象,JavaScript 令牌得到 53 个时间线数据点。因此矩阵对 Explore 使用 JavaScript 令牌:
{ "probed_on": "2026-11-16", "trending_scraper_token": "normal", "explore_scraper_token": "js", "trending_page_wait": 5000, "trending_ajax_wait": true, "explore_page_wait": 8000, "explore_ajax_wait": true, "store": false, "store_reason": "re-crawling the same URL with store=true replaces the stored copy, so it cannot keep 20 runs", "explore_scraper_token_reason": "On the 16 Nov 2026 probe the normal token returned empty chart objects. The JS token returned 53 timeline points."
探测日志中仍保留着在信封处理和内容检查被修正之前生成的判定,所以那些原始判定并不反映最终规则。该配置是可复现实验的一部分,新的探测可以替换它。启动矩阵之前请先检查令牌选择,因为矩阵在响应失败后绝不会切换令牌或改选另一条抓取路径。
解析数据之前先读取响应的各层
外层状态、Crawlbase 状态、目标状态、最终 URL、耗时、正文大小和域名复杂度都由 抓取执行器 记录。传输异常会变成一条没有 HTTP 响应、正文为空的结果,异常文本中的令牌值会被抹除。
| 信号 | 它在本项目中确定的内容 |
|---|---|
| 外层 HTTP 状态 | 是否收到来自 Crawlbase 的响应,以及其状态是什么 |
cb_status |
Crawlbase 的抓取结果;应用程序要求为 200 才接受内容 |
original_status |
Google 报告的 HTTP 状态,保留在 CSV 中 |
| 应用程序判定 | 正文是否满足所请求页面类型和路径的检查 |
抓取器响应还需要额外一步。在观察到的 JSON 信封中,外层是 cb_status, original_status, domain_complexity,以及 url 包围着内层的 body 对象。执行器会在验证之前解开这层信封。只看响应头会错过信封携带的元数据,这正是第一次探测出错的地方:
def unwrap_envelope(body: str): """Scrapers return a JSON envelope. The fields we check are under body.""" text = (body or "").lstrip("\ufeff").strip() if not text.startswith("{"): return body, None, None, None, None try: data = json.loads(text) except json.JSONDecodeError: return body, None, None, None, None if not isinstance(data, dict) or "body" not in data or "cb_status" not in data: return body, None, None, None, None inner = data.get("body") if isinstance(inner, (dict, list)): inner_text = json.dumps(inner) elif inner is None: inner_text = "" else: inner_text = str(inner) return ( inner_text, data.get("cb_status"), data.get("original_status"), data.get("domain_complexity"), data.get("url"), )
执行器测量 body_bytes 时使用的是编码为 UTF-8 的原始响应文本,而且是在解开信封之前,所以对抓取器 JSON 而言该数字包含信封。它不是压缩后的传输大小。耗时毫秒数覆盖传输调用;180 秒这个值遵循 Requests 的超时语义 而非严格的墙钟截止时间。
第一道接受关卡位于 assertions.py。它先剥离 script 和 style 块以及标签,然后在可见文本中搜索配置的标记:Oops 消息,还有 reCAPTCHA, unusual traffic, /sorry/,以及 g-recaptcha。先去掉脚本可以避免把正常页面对 reCAPTCHA 库的引用误读为挑战页,回归测试 test_recaptcha_script_on_a_data_page_is_not_a_challenge 固定了这一行为:
def _visible_text(body: str) -> str: """Drop scripts and tags so a library URL is not mistaken for a challenge.""" text = re.sub(r"(?is)<script\b[^>]*>.*?</script>", " ", body) text = re.sub(r"(?is)<style\b[^>]*>.*?</style>", " ", text) text = re.sub(r"(?is)<[^>]+>", " ", text) return text def challenge_reason(body: str) -> str | None: if not body: return None lowered = _visible_text(body).lower() for marker in CHALLENGE_MARKERS: if marker.lower() in lowered: return f"challenge marker: {marker}" return None def gate(body: str | None, cb_status: int | None) -> Verdict | None: """Return a failing verdict, or None when the body may be parsed.""" text = body or "" challenge = challenge_reason(text) if cb_status != 200: if challenge: return Verdict(False, f"cb_status {cb_status}, {challenge}") return Verdict(False, f"cb_status {cb_status}") if text.strip() == "": return Verdict(False, "empty body") if challenge: return Verdict(False, challenge) return None
标记类别归并了应用程序无法使用的各种提示。单独一条 Oops 消息并不能说明 Google 为何无法显示页面。而一旦关卡放行正文进入解析器,所需数据仍须通过它自己的检查。
只解析任务真正需要的字段
每种响应格式都由 解析器 转换成断言所期望的值;规则则由 检查分发器 为页面类型和路径挑选,并加入传输、语言和地理位置处理。
对于 Trending Now 抓取器 JSON,解析器读取结构化的 trends 数组。对于 HTML 和 Markdown,它先寻找可见的英文搜索量行,例如 20K+ searches 以及位于其前面的标题,同时还读取 HTML 表格行和 Markdown 表格。格式差异是显式的:结构化抓取器路径检查的字段多于标记语言路径。
Explore 解析先寻找结构化图表数据,包括嵌入文档中的 JSON 对象。当这些字段缺失时,它读取英文章节标题下的可见行。从可见文本提取时间线时,期望的是形如 Nov 16, 2026 的日期标签后跟一个整数,因此本地化的标题或日期即使在完整的本地化页面到达时也可能让解析器得不到时间线。
| 响应 | 应用程序实现的接受规则 |
|---|---|
| Trending Now 抓取器 JSON | 至少十条记录;每条记录都有 position, title, searchVolume, increasePercentage, started,以及 status; trendsCount 等于数组长度 |
| Trending Now HTML 或 Markdown | 至少提取出十行,每行都有标题和一个匹配预期模式的搜索量标签 |
| Explore | 至少 40 个时间线值;每个值都等价于整数且在 0 到 100 之间;最大值为 100;提取出的子区域列表非空 |
| Explore 抓取器地理位置 | 一个可识别的美国标签,或者字面量 geo=US 出现在返回的 URL 中 |
| RSS | 至少五个条目,每个条目都有标题、近似流量和发布日期 |
时间线断言接受整数、整数值的浮点数和整数字符串,拒绝布尔值。它不验证日期、时间连续性、所请求的词条或每一个地区分值:
def assert_timeline(values) -> Verdict: if not isinstance(values, list) or len(values) < TIMELINE_FLOOR: count = len(values) if isinstance(values, list) else 0 return Verdict( False, f"timeline length {count} below {TIMELINE_FLOOR}", timeline_passed=False, ) numbers = [] for value in values: number = _as_int(value) if number is None: return Verdict( False, f"timeline value {value!r} is not an integer", timeline_passed=False, ) if number < 0 or number > 100: return Verdict( False, f"timeline value {number} outside 0 to 100", timeline_passed=False, ) numbers.append(number) if max(numbers) != 100: return Verdict(False, "timeline max is not 100", timeline_passed=False) return Verdict(True, "ok", timeline_passed=True)
这些阈值属于本实验的美国查询,其时间范围为 today 12-m。四十个点是最低覆盖规则,不是完整一年的定义。峰值为 100 的要求适用于本测试框架所期望的单序列图表,不应变成“任何没有 100 的 Trends 响应都是解析错误”这样的断言。地理位置要求仅适用于 Explore 抓取器路径;HTML 和 Markdown 路径不强制执行它。
保留数字的含义
Explore 的时间线值是归一化的兴趣分数。Google 对 Trends 归一化的解释 描述了某一时间和地点的相对搜索兴趣,缩放到 0 到 100。值为 50 不代表五十次搜索。零可能表示搜索量低;它不自动等于缺失的观测值。在本项目中,空时间线是一次失败的提取,而包含零的时间线会作为一个数值序列接受检查。
Trending Now 的 searchVolume 是另一种测量。诸如 1M+ 这样的标签是分桶的搜索流量,而 increasePercentage 是相对于预测基线的增长。实现原样保留这些字符串。它不会把 1M+ 变成精确计数,不会把相对的 started 标签转换成时间戳,也不会从 Explore 分数推导出绝对搜索次数。
子区域解析器保留地区名称以供非空列表检查。通过该检查并不等于验证了每个地区的数值,也不等于抓取了所有地区分页。抓取器返回了受测页面显示的前五个子区域,连同总数和分页文本,项目没有翻看其余部分。
该图按目的对检查分组。上面链接的函数定义了实际顺序以及哪些检查适用于每种响应格式。
重试失败的判定,并保留两次尝试
fetch、check 和 sleep 这三个可调用对象由 测试框架 接收。它的重试决策跟随判定,已完成批次中的每一次尝试都成为独立的记录,带有状态、计时、正文大小、判定、原因和诊断信息:
def run_with_retry(fetch, check, sleep, *, surface, path, run, date=""): """Fetch and check. Sleep and try once more only if the check fails.""" attempts = [] for attempt in (1, 2): result = fetch() verdict = check(result) attempts.append( Attempt( surface=surface, path=path, run=run, attempt=attempt, date=date, latency_ms=result.latency_ms, body_bytes=result.body_bytes, credits=getattr(result, "credits", None), passed=verdict.passed, reason=verdict.reason, related_flagged=getattr(verdict, "related_flagged", None), related_share=getattr(verdict, "related_share", None), timeline_passed=getattr(verdict, "timeline_passed", None), http_status=getattr(result, "http_status", None), cb_status=getattr(result, "cb_status", None), original_status=getattr(result, "original_status", None), target_url=getattr(result, "target_url", ""), final_url=getattr(result, "final_url", None), my_location=getattr(verdict, "my_location", None), classic_banner=getattr(verdict, "classic_banner", None), selected_geo=getattr(verdict, "selected_geo", None), domain_complexity=getattr(result, "domain_complexity", None), ) ) if verdict.passed: break if attempt == 1: sleep(10) return attempts
首次尝试通过即结束循环。首次尝试失败则在十秒后获得一次对同一配置请求的重试。已完成的批次为首次尝试及其重试分别保留 CSV 行,即使重试通过也是如此。
每一轮中,由 矩阵运行器 依次访问九个适用单元,同一时间只有一个请求在途,并在每个单元的批次结束后等待三秒。当某个单元需要重试时,十秒等待发生在该批次内部,所以这些间隔并不意味着每两次调用之间恰好相隔三秒。
11月16日的矩阵共发出 221 次目标调用:180 次首次尝试和 41 次重试。重试遵循的是那次运行期间生效的规则。之后应用修正后的检查改变了已保存响应的评分方式;它没有改变哪些请求曾被重试。
摘要按页面类型和路径对记录分组,只把 attempt == 1 计入通过数、中位延迟和中位正文大小。这些中位数同时包含通过和失败的首次尝试,所以结果表不会把初始可靠性与恢复能力混在一起:
def summarise(attempts): """First-attempt pass rate, median latency, median body size, credit sum.""" keys = sorted({(item.surface, item.path) for item in attempts}) rows = [] for surface, path in keys: first = [ item for item in attempts if item.surface == surface and item.path == path and item.attempt == 1 ] runs = len(first) passes = sum(1 for item in first if item.passed) known = [item.credits for item in first if item.credits is not None] rows.append( { "surface": surface, "path": path, "runs": runs, "passes": passes, "pass_rate": (passes / runs) if runs else None, "median_latency_ms": median([item.latency_ms for item in first]), "median_body_bytes": median([item.body_bytes for item in first]), "credits": sum(known) if known else None, } ) return rows
返回了什么
下表报告 2026年11月16日的运行,并对其保存的响应应用了修正后的检查。每一行包含二十次首次尝试。Explore 使用固定查询 web scraping, geo=US,以及 date=today 12-m;Trending Now 和 RSS 使用 geo=US 且不带关键词。
| 页面类型 | 路径 | 通过,首次尝试 | 通过,英文页面 | 中位延迟(毫秒) | 中位正文(字节) |
|---|---|---|---|---|---|
| Trending Now | 内置抓取器 | 20/20 | 20/20 | 10,607 | 6,864 |
| Trending Now | Markdown | 20/20 | n/a,无语言标签 | 11,151 | 5,110 |
| Trending Now | 渲染 HTML | 18/20 | 18/18 | 26,077 | 2,351,950 |
| Trending Now | 无等待 HTML | 15/20 | 15/15 | 19,735 | 2,323,239 |
| Explore | 内置抓取器 | 18/20 | 14/16 | 26,029 | 4,075 |
| Explore | Markdown | 0/20 | n/a,无语言标签 | 44,669 | 475 |
| Explore | 渲染 HTML | 17/20 | 17/17 | 27,493 | 705,602 |
| Explore | 无等待 HTML | 15/20 | 15/16 | 34,444 | 686,376 |
| Trending RSS | RSS 抓取 | 20/20 | n/a,XML | 2,850 | 22,028 |
英文页面列对 HTML 响应使用 HTML 语言标签,对抓取器 JSON 使用地理位置标签的语言。它排除了已识别的非英文页面和那次传输失败。Markdown 和 RSS 没有记录语言分类,所以这些单元格显示 n/a。首次尝试列统计每条路径的全部二十次尝试,包括在本地化页面上的失败。
实时运行期间使用的判定保存在 原始 CSV 中。修正后的通过数以及计时和大小数字可以重新计算,来源是 重评分 CSV。中位数四舍五入到整毫秒和整字节。积分未做测量。
Trending Now:结构化记录,体积只有一小部分
内置的 Trending Now 抓取器在 20 次首次尝试中通过了 20 次,中位延迟 10,607 毫秒,中位响应 6,864 字节。下面是第一条记录,取自 精简后的双趋势样本:
{ "position": 1, "title": "steelers vs bengals", "searchVolume": "1M+", "searchVolumeText": "1M+ searches", "increasePercentage": "1,000%", "started": "19 hours ago", "status": "Active", "trendBreakdown": [ "bengals vs steelers", "joe burrow", "ja'marr chase" ], "trendBreakdownMoreCount": 78 },
该样本保留了原始的 trendsCount=25 和分页元数据,仅留下两条记录用于演示。它是缩短的实时样本,不是可提交给十条记录断言的完整正文。
渲染的 Trending Now HTML 在 20 次中通过 18 次,中位正文 2,351,950 字节。重评分 CSV 把两次失败都识别为英文解析器无法读取的葡萄牙语页面;无等待 Trending Now 的失败中出现了法语。仅英文的渲染子集通过率为 18/18。
Trending Now Markdown 同样在 20 次中通过 20 次,中位正文 5,110 字节,依靠匹配所需的英文标题加搜索量模式。通过这项检查并不意味着在抓取器 JSON 上验证的六个字段也在 Markdown 上得到了验证。
Explore:一个通不过任何内容检查的 200
Explore Markdown 在 20 次首次尝试中通过 0 次。全部二十次都记录了 HTTP 200 和 cb_status=200,以及 original_status=200。十九个包含 Oops 消息,一个包含 reCAPTCHA 提示。在首次尝试和重试合计四十个已保存的 Explore Markdown 正文中,Oops 消息出现了 36 次。下面是 保存的错误样本,已去掉 cookie 横幅那一行:
Oops! There was a problem displaying this page. Please try again Google apps Please upgrade to a [supported browser](https://support.google.com/recaptcha/?hl=en#6223828) to get a reCAPTCHA challenge. [Why is this happening to me?](https://support.google.com/recaptcha#6262736)
该路径返回了一个小而可解析的文档,中位正文 475 字节,却没有任何所需的关键词数据。
渲染的 Explore HTML 在 20 次中通过 17 次,中位延迟 27,493 毫秒,中位正文 705,602 字节。它的三次失败都是非英文页面;仅英文子集通过率为 17/17。无等待 Explore 对照组在 20 次中通过 15 次:三个非英文页面、一次没有响应正文的传输失败,以及一个提取出空时间线的英文页面。这一对比支持本案例中记录的等待配置。每条路径二十次尝试并不能证明等待可以修复每一个空图表。
Explore 抓取器:原始分数与修正分数
Explore 抓取器最初在 20 次首次尝试中通过 14 次。另有四个响应有时间线和子区域,却因为美国标签被本地化(西班牙语或葡萄牙语、俄语或荷兰语)而未能通过原始的地理位置规则。修正后的检查接受可识别的本地化标签,并对抓取器路径回退到检查 geo=US 是否出现在响应 URL 中。
对同一批正文重新评分后,首次尝试通过数提高到 20 次中的 18 次,一次波兰语标签的重试从失败变为通过。变化汇总在 重评分报告 中:总共 23 处判定变化,其中五处是通过/失败变化、十八处是原因变化,五处通过/失败变化中有四处发生在首次尝试上。
修正后的抓取器剩余的两次首次尝试失败是英文页面上的空时间线。在两个规则版本下,它的英文标签子集都是 16 次中通过 14 次。它的中位响应为 4,075 字节,而渲染的 Explore HTML 为 705,602 字节。抓取器把应用程序必须处理的响应缩小了两个数量级,同时保留了时间线和显示的子区域。
语言解释了原始通过率与过滤后通过率之间的大部分差距
十七次首次尝试被识别为本地化页面或本地化的抓取器标签。其中十三次未能通过英文解析器,涉及俄语、土耳其语、斯洛伐克语、希伯来语、乌克兰语、法语、葡萄牙语、中文和波斯语页面。另外四次是地理位置修正后被接受的 Explore 抓取器响应。分发器会给这些解析失败打上标签,以免把本地化的完整页面报告为空组件:
def check_result(surface: str, path: str, result, term: str = TERM): verdict = _check(surface, path, result, term) if verdict.passed: return verdict lang = page_lang(result.body or "") if ( lang and not lang.lower().startswith("en") and surface in ("trending", "explore") and verdict.reason.startswith(LOCALE_SENSITIVE) ): return dataclasses.replace( verdict, reason=f"non-English page ({lang}), localized labels not read: {verdict.reason}", ) return verdict
该标签是针对本地化内容观察到的解析器局限。它既不能证明 Google 的组件是空的,也不能让这些响应对当前应用程序可用,所以它们在原始通过数中仍算失败。
没有发送任何语言设置。页面语言随请求路由变化是一个合理的解释,但这次运行没有证明这一机制。添加 hl=en-US 是一个有用的后续实验,而不是这些结果中包含的对照。本文报告的是一个地区、一个日历日,没有第二天或固定语言的矩阵。
检查通过的时间线可能掩盖的诊断信息
结构验证捕获了本次运行中的错误页面和空时间线。它也留有余地去记录可疑字段,而不丢弃响应中可用的部分。
相关查询与所请求的词条不匹配
在记录了相关查询标志的 59 次首次尝试中,没有一次的相关词条含有共同词元,对比的词条是 web scraping,而这个计数包含了相关列表为空的响应。报告把词条转为小写,提取至少三个字符的字母数字词元,为符合条件的 -ing 词加上简单词干,然后在相关名称中把这些词元作为子串查找:
def term_tokens(term: str) -> list[str]: tokens = [] for word in re.findall(r"[a-z0-9]+", term.lower()): if len(word) < 3: continue tokens.append(word) if word.endswith("ing") and len(word) > 5: stem = word[:-3] if len(stem) >= 3: tokens.append(stem) return tokens def related_report(term: str, names) -> tuple[bool, float]: """Return (flagged, share). Flagged when no query shares a term token.""" queries = [name for name in (names or []) if name] if not queries: return True, 0.0 tokens = term_tokens(term) hits = 0 for name in queries: lowered = str(name).lower() if any(token in lowered for token in tokens): hits += 1 share = hits / len(queries) return hits == 0, share
空列表同样会被标记,所以单独一个 related_flagged=True 并不能证明收到了非空列表。这是一种诊断启发式,不是语义相关性模型,并且在相关列表被标记时应用程序有意保持时间线判定不变。观察到的无关词条说明,在相关查询进入下游之前有必要检查查询绑定;这次运行没有确定其原因。
"My location" 与所选搜索地区不一致
Trending Now HTML 在 33 行首次尝试中,通过其 "My location"(我的位置)标签暴露了十五个不同的国家。印度出现八次;越南、印度尼西亚和黎巴嫩各三次。所选趋势地区在全部 33 行中始终是美国。此处的 解析器 分开记录 my_location 与 selected_geo。请用所选的 Trends 地理位置来确定数据的范围。"My location" 跟随请求路由只是从这些观察得出的推断,不是 Google 文档中的保证。
Classic Explore 显示了一条到期横幅
横幅 "Classic Explore is expiring soon"(Classic Explore 即将到期)出现在二十个渲染 Explore 页面中的十七个以及二十个无等待页面中的十六个上。内置抓取器的 JSON 中没有它。字段 classic_banner 记录它的存在,但不把它用作通过条件。该横幅没有给出迁移日期,但当 Explore 界面变化时,它是重新运行代表性检查的一个运维理由,对绑定于可见标题和日期格式的解析器尤其如此。
让方法匹配任务
记录下的运行支持以下起点:
| 任务 | 应使用的路径 | 证据,2026年11月16日 |
|---|---|---|
| 每日趋势订阅 | Trending Now 内置抓取器;当标题、近似流量和发布日期足够时用 RSS | 抓取器 20/20,中位 10,607 毫秒;RSS 20/20,中位 2,850 毫秒 |
| 关键词历史 | 使用 JavaScript 令牌的 Explore 内置抓取器 | 修正后的地理位置规则下 18/20;两个空时间线 |
| 地区细分 | Explore 内置抓取器的子区域列表 | 在同一响应中返回;是显示的前五个子区域,不是完整列表 |
| 智能体工具调用 | 以 JSON 形式使用 Trending Now 内置抓取器 | 20/20;结构化字段可以在数据返回给调用方之前得到检查 |
Explore Markdown 的 0/20 结果适用于受测的 Normal 令牌路径。这些结果是选择配置并在你自己的目标查询上加以验证的依据,而不是这种验证的替代品。
运行实现并验证变化
三个步骤模块由 完整软件包 导入,导入入口是 load_steps.py,因此上面引用的请求形态、断言和重试函数就是 CLI 实际运行的代码。最终测试套件有三十个测试,覆盖断言、解析器行为、信封处理、令牌脱敏、重试、计费响应上限、统计和 CLI 执行。它的一致性测试运行共享的测试框架摘要;它不会重新验证实时的 Google 响应。
依赖文件 requirements 声明了 requests>=2.32 和 pytest>=8 而没有锁定精确版本。记录的运行使用 Python 3.13。把 环境模板 复制为 .env 并放到 final/ 目录中,然后设置 CRAWLBASE_TOKEN 和 CRAWLBASE_JS_TOKEN 的值,来源是你的 Crawlbase 账户。该文件已被 gitignore 忽略。客户端只在 HTTP 边界加入密钥,其日志记录令牌类型,保存的正文和异常消息都会按配置的密钥进行抹除。在仓库根目录执行:
cd final cp .env.example .env # add CRAWLBASE_TOKEN and CRAWLBASE_JS_TOKEN python -m pytest -q python -m trends_probe --offline --date 2026-11-16 python -m trends_probe --matrix --runs 20 --max-billable 400 --date 2026-11-16 --geo US
pytest 和 offline 命令不发出实时目标调用。matrix 命令发出实时调用并消耗积分。它的 --date 参数只用于标记输出;它不请求历史快照,而 today 12-m 在 Google 处理请求时才被解析。设置步骤见 README 一文,涵盖 Windows、Linux 和 macOS。
把测试夹具与实时证据分开
offline 命令使用 合成夹具:一条最小时间线、示例趋势、RSS 条目、一个 Oops 正文和一个空响应。它的摘要会标明自己是夹具运行。这些结果展示的是程序行为,绝不能计为额外的实时尝试。
实时运行时,由 CLI 把每次调用脱敏后的正文保存在 results/raw/matrix/ 下,并把已完成的批次检查点写入 CSV。公开仓库同时包含记录的 CSV 和精简的实时样本;完整的原始正文目录已被 gitignore 忽略。
--report 根据记录的判定重建摘要,而 --rescore 需要匹配的本地原始正文,重新应用当前检查,并在不发出新目标请求的情况下写出单独的 -rescored CSV 和 Markdown 报告。在再次运行矩阵之前,请把每次运行的原始目录连同其 CSV 一起保留:正文文件名的调用计数器会重新开始,而重评分在核对页面类型和路径后按调用顺序把行与文件配对。
矩阵使用 store=False 并且绝不把之前成功的正文作为回退重用。有一次探测请求使用 store=true 搭配 Crawlbase Cloud Storage。它的日志记录了一个 storage_url 头,没有单独的 rid;标识符只出现在该 URL 的查询字符串中。签入的配置注明,再次存储同一 URL 会替换已存储的副本。因此这次运行保留了各个本地正文用于比较。另一方面,官方的 Crawling API 参考 为已存储的请求记录了一个 rid 标识符;本实现不依赖它。
把请求次数与积分消耗分开
矩阵统计到 220 个计费响应,配置的上限为 400。该上限统计的是响应而非积分。这里的 本地分类器 主要查看 cb_status:
BILLABLE = {200, 207} class BudgetStop(Exception): """The billable cap was reached before the matrix finished.""" def is_billable(result) -> bool: if result.cb_status in BILLABLE: return True if result.cb_status is None and result.http_status == 200 and not result.error: return True return False
Crawlbase 的 计费规则文档 还会考虑 original_status。在这次记录的矩阵中,全部 220 个收到的响应都有 cb_status=200 和 original_status=200,余下的那次调用是传输失败,因此两条规则在这批数据上是一致的。正文可以通不过本应用程序的检查,却仍然满足计费状态。不可用的 Explore Markdown 响应就是如此。应用程序的通过数和它的计费响应数回答的是不同的问题。
积分未做测量。没有记录到积分头,探测的账户摘要返回的用量字段为 null。这是辅助函数的读取错误,不是空账户,原因是 Account API 把当月总量放在嵌套字段 currentMonth,而辅助函数在顶层读取 totalSuccess 和其他字段,所以它们始终为 null。这些摘要无法确定任何测得的用量差值:
def account(self): token = self._token("normal") try: response = self._session.get( "https://api.crawlbase.com/account", params={"token": token, "product": "crawling-api"}, timeout=60, ) except Exception as exc: return {"error": self._fetch.scrub(str(exc), self._secrets())} try: payload = response.json() except ValueError: return {"error": "account response was not JSON", "http_status": response.status_code} return { "http_status": response.status_code, "totalSuccess": payload.get("totalSuccess"), "totalFailed": payload.get("totalFailed"), "totalDue": payload.get("totalDue"), "remainingCredits": payload.get("remainingCredits"), }
全部 220 个收到的矩阵响应都记录为 complex 层级。根据 积分倍数文档,一次 Complex 请求消耗两个积分,JavaScript 渲染再翻一倍。矩阵包含 100 个收到的 Normal 令牌响应和 120 个收到的 JavaScript 令牌响应:
矩阵消耗估算:(100 × 2) + (120 × 4) = 680 积分。
这是根据记录的令牌组合得出的估算,不是账户读数,而且不包括探测。虽然 Google 抓取器产品页面 宣传最多 5,000 次免费请求,但在把额度解读为 Explore 调用次数之前,请核对实际积分余额和适用的倍数。
运行器是串行的,使用上面描述的等待时间,并在达到计费上限后停止发出下一个请求。如果较低的上限在失败的首次尝试与其重试之间中断了批次,当前的运行器可能会把这个不完整的批次漏出 CSV;记录的运行中没有发生这种情况。在上限之内,挑战页提示与其他任何失败判定一样只获得一次重试,应用程序不添加任何 CAPTCHA 破解逻辑。请查阅 Google 的条款 了解预期用途,并选择一个符合你任务新鲜度需求的调度计划。关于节奏和爬虫行为的更广泛背景,参见 网络开始给爬虫打分了 一文。
结论
11月16日的运行说明了为什么可用的 Google Trends 数据需要自己的接受检查。每个收到的矩阵响应都报告了成功的 HTTP 和抓取状态,然而 Explore Markdown 没有产出任何可用的时间线,一些英文 Explore 响应的图表为空,本地化页面则暴露了标记语言解析器的局限。
Crawlbase 的内置抓取器提供了紧凑的结构化响应:Trending Now 通过 20/20,JavaScript 令牌的 Explore 抓取器在地理位置修正后通过 18/20。应用程序通过保留状态、检查所需字段、把诊断与接受分离,以及把每次重试作为独立尝试保留,使这些结果可供检查。
起点可以是文档中的 Google Trends 抓取器 或 Google Trends Explore 抓取器,然后应用适合你所请求数据的检查,并在判定发生变化时保留有代表性的正文。这样流水线就有了一个超越“收到 200”的成功定义。
以渲染 HTML、Markdown 或内置 Trending Now 和 Explore 抓取器的结构化 JSON 形式获取 Google Trends,每个响应都带有 cb_status 和 original_status 字段,由你自己的检查决定什么算有效。最多 5,000 次免费请求起步,无需信用卡。
常见问题 (FAQ)
HTTP 200 和 cb_status=200 能证明 Google Trends 数据可用吗?
它们确定的是报告的获取状态。这次运行在这些状态下仍然返回了 Oops 页面、一条 reCAPTCHA 提示和空时间线。接受数据之前,请要求具备你的应用程序所需的字段和覆盖范围。应用程序判定失败也不会让已收到的响应变为不计费。
抓取 Google Trends 一定需要 JavaScript 令牌吗?
令牌选择取决于页面类型和路径。在本矩阵中,Trending Now 抓取器 JSON、Trending Now Markdown 和 RSS 都用 Normal 令牌通过了。Explore 抓取器在探测的 Normal 令牌响应返回空图表对象之后改用了 JavaScript 令牌。渲染和无等待 HTML 都使用 JavaScript 令牌。测试框架重试配置好的请求,不会自行更换令牌。
Explore 的值和 Trending Now 的搜索量标签是同一种测量吗?
不是。Explore 的值是所选时间和地理位置的归一化兴趣分数。Trending Now 的标签,例如 1M+ 这类,则是所选趋势时段内分桶的流量。保持每个字段各自的含义:无论是 100 的 Explore 分数还是 1M+ 标签,都不是本应用程序能够还原的精确搜索次数。
同样的检查可以用于另一个国家或更短的时间范围吗?
先做调整。CLI 的 --geo 选项会改变所请求的 URL,但 Explore 抓取器的接受规则仍然期望美国。40 个点的最低要求和峰值 100 的检查是为固定的单词条、十二个月实验选择的,本地化的标记可能需要修改解析器。在把通过率与本次运行比较之前,请用匹配的断言测试目标地理位置、语言和时间窗口。
大规模爬取任何站点,无需与基础设施对抗。
Crawlbase 负责处理代理、指纹和验证码,让您的团队专注于构建数据管道,而不是维护爬取基础设施。免费提供最多 5,000 次请求,无需绑定信用卡。

