> ## 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 i CLI

Gologin Web Unlocker to **scraping API z jednym endpointem** przeznaczone dla stron intensywnie wykorzystujących JavaScript oraz stron chronionych.

Wysyłasz adres URL, otrzymujesz wyrenderowany kod HTML lub tekst strony i przetwarzasz go we własnym potoku ekstrakcji danych.

## Dlaczego warto używać go jako Scraping API

* Jeden endpoint dla dowolnego docelowego adresu URL
* Uwierzytelnianie kluczem API, bez konieczności orkiestracji przeglądarek
* Odpowiedź w formacie HTML, którą łatwo podłączyć do istniejących parserów
* Dobre dopasowanie do procesów ETL, monitoringu, pozyskiwania danych dla AI i potoków danych

## Endpoint

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

## Uwierzytelnianie

Przekaż swój klucz API w nagłówkach:

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

## Model żądania

| Nazwa | Lokalizacja | Typ | Wymagany | Opis |
| - | - | - | - | - |
| `url` | parametr zapytania | ciąg znaków (bezwzględny adres URL) | tak | Docelowy adres URL do scrapingu |

## Szybki start

### 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));
```

## Zachowanie odpowiedzi

Aktualna treść odpowiedzi to **surowy, wyrenderowany kod HTML lub tekst**.

* `200` -> sukces, treść odpowiedzi zawiera kod HTML/tekst strony
* `401` / `403` -> nieprawidłowy lub brakujący klucz API
* `422` -> nieprawidłowy lub brakujący parametr `url`
* `429` -> przekroczony limit żądań
* `500+` -> tymczasowy błąd po stronie serwera

## Wskazówki dotyczące ponawiania żądań

Ponawiaj żądania z wykładniczym wydłużaniem odstępów (exponential backoff) w przypadku:

* błędów sieciowych
* kodów `408`, `429`, `500`, `502`, `503`, `504`

## Uwaga o zakresie

Obecny publiczny endpoint zwraca przede wszystkim HTML. Nie zakładaj istnienia dodatkowych endpointów backendu (na przykład do zrzutów ekranu, crawlowania, wyszukiwania czy sprawdzania zużycia), jeśli nie zostały one wyraźnie udokumentowane i włączone dla Twojego konta.

## Oficjalne SDK dla Node.js

Instalacja:

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

### Szybki start z 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));
```

### Opcje konstruktora

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

### Podstawowe metody SDK

* `scrape(url)` -> znormalizowany obiekt odpowiedzi
* `scrapeRaw(url)` -> natywny obiekt `Response`
* `buildScrapeUrl(url)` -> pełny adres URL żądania

### Metody pochodne po stronie SDK (na podstawie zwróconego HTML)

To **nie są osobne endpointy backendu**; są one tworzone w SDK na podstawie HTML zwróconego przez API:

* `scrapeText(url)` -> zwykły tekst
* `scrapeMarkdown(url)` -> markdown
* `scrapeJSON(url)` -> ustrukturyzowane metadane (`title`, `meta`, `links`, `headings`)
* `batchScrape(urls, { concurrency })` -> pomocnik do wykonywania wielu wywołań scrape

### Typowane błędy

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

Mapowanie:

* `401` / `403` -> `AuthenticationError`
* `429` -> `RateLimitError`
* `500+` -> `APIError`
* przekroczenie czasu/przerwanie żądania -> `TimeoutError`
* błąd fetch/sieci -> `NetworkError`

## CLI

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

Polecenia:

* `scrape` (surowy HTML/tekst)
* `text` (tekst pochodny)
* `markdown` (markdown pochodny)
* `json` (metadane pochodne)

Przykłady:

```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
```

## Typowe zastosowania scrapingu

* monitoring cen i katalogów produktów
* wzbogacanie baz leadów i katalogów firm
* potoki analizy rynku i wywiadu konkurencyjnego
* agregowanie i indeksowanie treści
* przepływy pracy związane z pozyskiwaniem i ekstrakcją danych dla LLM

## Gologin Web Access CLI (zunifikowane)

Jeśli potrzebujesz bardziej rozbudowanego CLI, które łączy Web Unlocker z Cloud Browser w jednym zestawie poleceń, użyj `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
```

Pełny opis znajdziesz w [Gologin Web Access CLI](https://gologin.com/docs/pl/cli-tools/web-access.md).

## Dokumentacja źródłowa

* [Czym jest Web Unlocker](https://gologin.com/docs/pl/what-is-web-unlocker.md)
* [Szybki start z Web Unlocker](https://gologin.com/docs/pl/web-unlocker-quick-start.md)
* [Zastosowania Web Unlocker](https://gologin.com/docs/pl/web-unlocker-use-cases.md)


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