> ## 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 — это **scraping API с единой конечной точкой** для сайтов с большим количеством JavaScript и защитой от парсинга.

Вы отправляете URL, получаете отрендеренный HTML/текст страницы и обрабатываете его в собственном конвейере извлечения данных.

## Зачем использовать его как Scraping API

* Одна конечная точка для любого целевого URL
* Авторизация по API-ключу, оркестрация браузеров не требуется
* Ответ в формате HTML, который легко подключается к существующим парсерам
* Подходит для ETL, мониторинга, загрузки данных для ИИ и конвейеров обработки данных

## Конечная точка

`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+` -> временная ошибка на стороне сервера

## Рекомендации по повторным запросам

Повторяйте запрос с экспоненциальной задержкой (exponential backoff) при:

* сетевых ошибках
* кодах `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 получает их из HTML, который вернул API:

* `scrapeText(url)` -> обычный текст
* `scrapeMarkdown(url)` -> markdown
* `scrapeJSON(url)` -> структурированные метаданные (`title`, `meta`, `links`, `headings`)
* `batchScrape(urls, { concurrency })` -> вспомогательный метод для нескольких запросов scrape

### Типизированные ошибки

* `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/ru/cli-tools/web-access.md).

## Связанные материалы

* [Что такое Web Unlocker](https://gologin.com/docs/ru/what-is-web-unlocker.md)
* [Быстрый старт с Web Unlocker](https://gologin.com/docs/ru/web-unlocker-quick-start.md)
* [Сценарии использования Web Unlocker](https://gologin.com/docs/ru/web-unlocker-use-cases.md)


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