scraperapi-crawler

ScraperAPI Crawler

Crawler 会从种子 URL 开始，自动发现并抓取关联页面，并跟进与正则表达式模式匹配的链接。如果你需要获取网站多个页面的数据，但尚未掌握这些页面的 URL，可以使用它。

何时不应使用 Crawler

• 你已有确定的 URL 列表 → 改用 Async API，费用更低，也更可预测。
• 你只需要单个页面 → 使用 Standard API（api.scraperapi.com）。
• 内容需要登录才能访问 → Crawler 只能访问公开页面。
• 使用免费套餐，且需要的深度 > 1 → 免费账户的上限为 max_depth: 1。

端点

操作	方法	URL
开始爬取	POST	https://crawler.scraperapi.com/job
查看状态	GET	https://crawler.scraperapi.com/job/<jobId>
取消爬取	DELETE	https://crawler.scraperapi.com/job/<jobId>

身份验证：在 JSON 请求体（POST）中加入 api_key，或将其作为查询参数（GET/DELETE）。

开始爬取

import os, requests

API_KEY = os.environ["SCRAPERAPI_API_KEY"]

job = requests.post(
    "https://crawler.scraperapi.com/job",
    json={
        "api_key":            API_KEY,
        "start_url":          "https://example.com/blog/",
        "url_regexp_include": "(?<full_url>https?://example\\.com/blog/.*)",
        "url_regexp_exclude": ".*\\.(pdf|png|jpg|zip)",
        "max_depth":          3,
        "crawl_budget":       500,
        "api_params": {
            "country_code": "us",
            "render":       False,
        },
        "callback": {
            "type": "webhook",
            "url":  "https://yourapp.com/crawler-results"
        },
    }
).json()

job_id = job["jobId"]
print(f"Started: {job_id}")

必需参数

参数	说明
api_key	你的 ScraperAPI 密钥（从环境变量中读取，切勿硬编码）
start_url	种子 URL，即爬取的起始位置
url_regexp_include	定义要爬取哪些 URL 的正则表达式（参见下方的模式）
max_depth 或 crawl_budget	至少提供其中一个；如果两者都提供，则以先达到的限制为准

URL 正则表达式模式

url_regexp_include 和 url_regexp_exclude 是标准正则表达式。包含模式必须使用命名捕获组：绝对 URL 使用 (?<full_url>...)，相对 URL 使用 (?<relative_url>...)。

# All pages on a domain
(?<full_url>https?://example\.com/.*)

# Only blog posts
(?<full_url>https?://example\.com/blog/.*)

# Only HTML pages — exclude files by requiring no extension
(?<full_url>https?://example\.com/[^.]*$)

# Relative paths (for sites that use relative links)
(?<relative_url>/products/.*)

排除模式（url_regexp_exclude — 普通正则表达式，无需捕获组）：

# Skip binary files
.*\.(pdf|png|jpg|jpeg|gif|svg|zip|mp4)

# Skip auth and admin pages
.*(login|logout|signup|admin|auth).*

先使用范围较窄的 url_regexp_include，并在扩大规模前进行小规模测试——像 .* 这样的模式会跟进外部链接，进而爬取整个互联网。

深度与预算

适合使用 max_depth 的情况	适合使用 crawl_budget 的情况
网站结构已知且范围明确	网站规模未知
你想抓取特定版块（例如，从着陆页出发，经过 3 跳）	你想限制额度消耗
小型网站	链接密度难以预测的大型网站

同时使用两者可安全探索：max_depth: 3, crawl_budget: 500 会在任一限制先达到时停止。

深度 0 = 仅起始 URL。深度 1 = 起始 URL 加上它链接到的所有页面。深度 2 = 再深入一层，以此类推。

单页抓取参数（api_params）

控制每个发现页面的获取方式。支持所有标准 ScraperAPI 参数：

{
  "render":       true,
  "premium":      false,
  "ultra_premium": false,
  "country_code": "us",
  "device_type":  "desktop",
  "output_format": "markdown"
}

只有在网站使用 JavaScript 加载内容时才添加 render: true——它会使每个爬取页面的额度成本增加。请先测试不启用该选项的情况。

查看状态

import time, requests

def wait_for_crawl(job_id, api_key, poll_interval=10):
    url = f"https://crawler.scraperapi.com/job/{job_id}"
    while True:
        data = requests.get(url, params={"api_key": api_key}).json()
        status = data.get("status")
        print(f"Status: {status}")
        if status in ("completed", "failed", "cancelled", "delivered"):
            return data
        time.sleep(poll_interval)

任务状态：delayed → running → completed / failed / cancelled → in delivery → delivered。

对于长时间运行的爬取，请使用 Webhook 代替轮询——Webhook 会在每个页面抓取完成后推送结果，无需轮询等待最终结果。

Webhook

设置 callback 后，ScraperAPI 会在每个页面抓取完成时向你的端点发送 POST 请求（而不是仅在最后发送）。每个负载都包含爬取的 URL、HTML/内容、该请求的额度成本以及当前深度。

爬取完成后，还会发送最终摘要负载，列出所有成功/失败的 URL 和总成本。

{
  "callback": {
    "type": "webhook",
    "url": "https://yourapp.com/crawler-results"
  }
}

Webhook URL 必须可公开访问。ScraperAPI 最多会重试发送 3 次；Webhook 发送失败不会导致爬取本身停止。如果需要重新获取结果，结果还会保留最多 30 天。

计划任务

一次性爬取时省略 schedule。添加该参数即可按固定间隔运行：

{
  "schedule": {
    "name": "weekly-blog-crawl",
    "interval": "daily"
  }
}

可用间隔：once、hourly、daily、weekly、monthly。计划任务需要付费套餐——免费账户只能以 max_depth: 1 运行一次性爬取。

积分费用

Crawler 积分费用 = 抓取中的所有单个页面请求费用之和。每个页面的费用与使用相同 api_params（render、premium 等）的 Standard API 调用相同。

设置 crawl_budget 以限制总积分费用。达到预算时，抓取会正常停止，不会超出预算。失败的请求不收费。

检查每个 webhook 载荷中的 sa-credit-cost 标头，查看每页费用；根据此信息为后续运行调整 crawl_budget。

错误处理

代码	含义	操作
200	已创建任务或已返回状态	继续
400	请求格式错误	检查必填字段和正则表达式语法
401	API 密钥无效	检查 SCRAPERAPI_API_KEY
403	积分已用尽或免费套餐深度限制	升级套餐或降低 max_depth/crawl_budget
429	并发任务过多	等待后重试
500	暂时性故障	延迟后重试

文档

• 爬虫概览
• API 参考
• 控制面板