> ## Documentation Index
> Fetch the complete documentation index at: https://gologin.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Scraping API SDK 和 CLI

Gologin Web Unlocker 是一个**单端点抓取 API**，适用于大量依赖 JS 渲染以及有防护机制的网站。

你只需发送一个 URL，即可获得渲染后的页面 HTML/文本，然后在自己的数据提取流程中进行处理。

## 为什么将它用作 Scraping API

* 任意目标 URL 只需一个端点
* 使用 API 密钥认证，无需编排浏览器
* 以 HTML 为主的响应，可直接接入现有解析器
* 适合 ETL、监控、AI 数据摄取和数据管道

## 端点

`GET https://parsing.webunlocker.gologin.com/v1/scrape?url={encoded_url}`

## 身份验证

在请求头中发送你的 API 密钥：

```http theme={null}
apikey: <API_KEY>
```

## 请求模型

| 名称 | 位置 | 类型 | 是否必填 | 说明 |
| - | - | - | - | - |
| `url` | query | string（绝对 URL） | 是 | 要抓取的目标 URL |

## 快速开始

### cURL

```bash theme={null}
curl "https://parsing.webunlocker.gologin.com/v1/scrape?url=https%3A%2F%2Fexample.com" \
  -H "apikey: YOUR_API_KEY"
```

### Python

```python theme={null}
import requests

response = requests.get(
    "https://parsing.webunlocker.gologin.com/v1/scrape",
    params={"url": "https://example.com"},
    headers={"apikey": "YOUR_API_KEY"}
)

print(response.status_code)
print(response.text[:500])
```

### JavaScript (fetch)

```js theme={null}
const response = await fetch(
  "https://parsing.webunlocker.gologin.com/v1/scrape?url=" +
    encodeURIComponent("https://example.com"),
  { headers: { apikey: "YOUR_API_KEY" } }
);

const html = await response.text();
console.log(response.status, html.slice(0, 500));
```

## 响应行为

当前响应体为**原始的渲染后 HTML/文本**。

* `200` -> 成功，响应体包含页面 HTML/文本
* `401` / `403` -> API 密钥无效或缺失
* `422` -> `url` 无效或缺失
* `429` -> 触发速率限制
* `500+` -> 服务端临时错误

## 重试建议

对以下情况，请使用指数退避策略进行重试：

* 网络错误
* `408`、`429`、`500`、`502`、`503`、`504`

## 范围说明

当前公开的端点以 HTML 为主。除非文档明确说明且已为你的账户启用，否则请不要假定存在其他后端端点（例如截图/爬取/搜索/用量）。

## 官方 Node.js SDK

安装：

```bash theme={null}
npm i gologin-webunlocker
```

### SDK 快速开始

```ts theme={null}
import { WebUnlocker } from "gologin-webunlocker";

const client = new WebUnlocker({
  apiKey: process.env.GOLOGIN_WEBUNLOCKER_API_KEY!
});

const result = await client.scrape("https://example.com");
console.log(result.status);
console.log(result.content.slice(0, 500));
```

### 构造函数选项

```ts theme={null}
new WebUnlocker({
  apiKey: "wu_live_xxx",
  baseUrl: "https://parsing.webunlocker.gologin.com",
  timeoutMs: 15000,
  maxRetries: 2
});
```

### SDK 核心方法

* `scrape(url)` -> 标准化的响应对象
* `scrapeRaw(url)` -> 原生 `Response`
* `buildScrapeUrl(url)` -> 完整的请求 URL

### SDK 端派生方法（基于返回的 HTML）

这些**不是独立的后端端点**，而是 SDK 基于 API 返回的 HTML 派生出来的：

* `scrapeText(url)` -> 纯文本
* `scrapeMarkdown(url)` -> Markdown
* `scrapeJSON(url)` -> 结构化元数据（`title`、`meta`、`links`、`headings`）
* `batchScrape(urls, { concurrency })` -> 用于多次抓取调用的辅助方法

### 类型化错误

* `WebUnlockerError`
* `AuthenticationError`
* `RateLimitError`
* `APIError`
* `TimeoutError`
* `NetworkError`

映射关系：

* `401` / `403` -> `AuthenticationError`
* `429` -> `RateLimitError`
* `500+` -> `APIError`
* 超时/中止 -> `TimeoutError`
* fetch/网络故障 -> `NetworkError`

## CLI

```bash theme={null}
gologin-webunlocker <command> <url> [options]
```

命令：

* `scrape`（原始 HTML/文本）
* `text`（派生的文本）
* `markdown`（派生的 Markdown）
* `json`（派生的元数据）

示例：

```bash theme={null}
gologin-webunlocker scrape https://example.com --api-key wu_live_xxx
GOLOGIN_WEBUNLOCKER_API_KEY=wu_live_xxx gologin-webunlocker text https://example.com
GOLOGIN_WEBUNLOCKER_API_KEY=wu_live_xxx gologin-webunlocker json https://example.com
```

## 典型抓取使用场景

* 价格和商品目录监控
* 线索和名录信息补全
* 市场情报数据管道
* 内容聚合与索引
* LLM 数据摄取和提取工作流

## Gologin Web Access CLI（统一版）

如果你需要功能更强大的 CLI，在同一套命令中结合使用 Web Unlocker 和 Cloud Browser，请使用 `gologin-web-access`：

```bash theme={null}
npm install -g gologin-web-access

export GOLOGIN_WEB_UNLOCKER_API_KEY="wu_..."

# all scraping commands from gologin-webunlocker, plus:
gologin-web-access batch-scrape url1 url2 url3 --format text --summary
gologin-web-access search "query" --limit 10
gologin-web-access map https://example.com --limit 50
gologin-web-access crawl https://docs.example.com --format markdown --limit 20
gologin-web-access extract https://example.com --schema ./schema.json
gologin-web-access change-track https://example.com --format markdown

# plus cloud browser interaction (requires GOLOGIN_TOKEN)
gologin-web-access open https://example.com
gologin-web-access snapshot
gologin-web-access click e3
```

完整参考请参阅 [Gologin Web Access CLI](https://gologin.com/docs/zh/cli-tools/web-access.md)。

## 相关文档

* [什么是 Web Unlocker](https://gologin.com/docs/zh/what-is-web-unlocker.md)
* [Web Unlocker 快速开始](https://gologin.com/docs/zh/web-unlocker-quick-start.md)
* [Web Unlocker 使用场景](https://gologin.com/docs/zh/web-unlocker-use-cases.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.