Один URL на входе — чистые структурированные данные на выходе

Скрейпинг

Yozh Scraper рендерит любой URL в настоящем браузере Playwright и возвращает ровно то, что вы просите — извлечённые поля, сырой HTML или скриншот всей страницы. Каждый скрейп — это асинхронная задача: отправьте URL, опросите задачу, заберите результат. Прокси, stealth, пресеты и авторизованные сессии — всё это полноценные возможности.

• Рендер в настоящем браузере — Playwright рендерит страницы, построенные на JS; выключите render для статического HTML.
• Структурированное извлечение — правила полей на CSS или XPath возвращают чистый объект data, куда дешевле, чем самому качать и парсить сырой HTML.
• Встроенные прокси — CyberYozh residential / mobile LTE / datacenter, с GEO-таргетингом и без поиска pool-id.
• Stealth по умолчанию — патчи playwright-stealth (navigator.webdriver, отпечаток WebGL / Canvas, chrome runtime) снижают детект ботов.
• Пресеты — скрейпьте Amazon / Google / eBay / Walmart / YouTube / LinkedIn по имени, с опциональным LLM-самовосстановлением.
• Сессии — управляемые сервером авторизованные сессии для целей под логином, переиспользуемые между скрейпами.

Быстрый старт

Скрейпер поднимается из корневого docker-compose.yml (вместе с краулером):

cp .env.example .env          # set CYBERYOZH_API_KEY if using proxies
docker compose up --build
# scraper → http://localhost:8000
# crawler → http://localhost:8001

Проверьте, что он поднялся:

curl http://localhost:8000/api/v1/health
# {"status":"ok","workers":2}

Базовое использование

Каждый скрейп-эндпоинт создаёт фоновую задачу и возвращает job_id. Опросите задачу, затем заберите её результаты.

curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{ "url": "https://example.com", "proxy_type": "none" }'
# → { "job_id": "req_abc123" }

curl http://localhost:8000/api/v1/scrape/req_abc123          # status
curl http://localhost:8000/api/v1/scrape/req_abc123/results  # results

Готовый результат несёт метаданные плюс то, что вы запросили (data, raw_html, screenshot_base64):

{
  "job_id": "req_abc123",
  "status": "done",
  "total": 1, "done": 1,
  "results": [
    {
      "request_id": "req_abc123",
      "took_ms": 1234,
      "meta": { "url": "https://example.com", "final_url": "https://example.com/",
                "status_code": 200, "device": "desktop", "proxy_type": "none", "retries": 0 },
      "data": null, "raw_html": null, "screenshot_base64": null, "warnings": []
    }
  ]
}

Извлечение данных

Передайте правило extract — и ответ будет содержать объект data с ключами по именам ваших полей, куда дешевле, чем качать raw_html и парсить его самому. Правила бывают css или xpath.

curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{
    "url": "https://example.com",
    "extract": {
      "type": "css",
      "fields": {
        "title": { "selector": "h1", "attr": "text", "required": true }
      }
    }
  }'
# result → { "data": { "title": "Example Domain" } }

Каждое поле — это правило:

Используйте "type": "xpath" с XPath-селекторами (например, //h1) для той же структуры.

Скриншоты & сырой HTML

Задайте screenshot: true для PNG всей страницы (base64 в screenshot_base64) или raw_html: true, чтобы получить полный HTML после рендера в raw_html.

curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{ "url": "https://example.com", "screenshot": true, "raw_html": true }'

Прокси

Для надёжного скрейпинга прокси необходимы — большинство современных сайтов блокируют прямые запросы. Yozh интегрирован с CyberYozh Proxy Service; задайте proxy_type в любом запросе.

Нацельтесь на локацию через proxy_geo (country_code / region / city). Узнайте, что вы купили, без поиска pool id:

curl "http://localhost:8000/api/v1/proxies/available?proxy_type=res_rotating"
curl "http://localhost:8000/api/v1/proxies/countries"

Пресеты

Пресет объединяет профиль запроса + шаблон URL + рецепт парсинга, так что вы скрейпите сайт по имени, а не собираете запрос вручную. Встроенные идут для Amazon, Google, eBay, Walmart, YouTube и LinkedIn; можно создать и свой (детерминированный CSS/XPath или сгенерированный ИИ).

curl -X POST http://localhost:8000/api/v1/scrape/preset/page 
  -H "Content-Type: application/json" 
  -d '{
    "source": "amazon_product",
    "preset_params": { "asin": "B08N5WRWNW" },
    "locale": "us",
    "llm": { "model": "openai/gpt-5.4-mini" }
  }'
# → { "job_id": "..." }  then GET /api/v1/scrape/<job_id>/results

Управляйте пресетами через GET /api/v1/presets, GET /api/v1/presets/{name} и POST /api/v1/presets (имена пользовательских пресетов должны начинаться с user_).

Сессии

Управляемые сервером авторизованные сессии: создайте одну, войдите один раз, затем передавайте её session_id в любой скрейп — страницы будут загружаться с сохранёнными cookies + storage state. Обязательно для целей под логином, таких как пресет linkedin_profile.

1. POST /api/v1/sessions — создать. Фиксирует device / proxy_type / proxy_geo и TTL. Возвращает { session_id, expires_at }.
2. POST /api/v1/sessions/{id}/login — проиграть декларативный сценарий входа с creds в теле: { script, creds }.
3. POST /api/v1/scrape/page с заданным session_id — скрейпинг под авторизацией.
4. DELETE /api/v1/sessions/{id} — очистка.

# 1. create  →  {"session_id":"sess_...","expires_at":...}
curl -X POST http://localhost:8000/api/v1/sessions 
  -H "Content-Type: application/json" 
  -d '{ "device": "desktop", "proxy_type": "res_rotating" }'

# 2. log in (declarative DSL + creds)
curl -X POST http://localhost:8000/api/v1/sessions/sess_.../login 
  -H "Content-Type: application/json" 
  -d '{ "script": { "steps": [ {"op":"goto","url":"https://site/login"} ] },
        "creds": { "username": "...", "password": "..." } }'

# 3. scrape with the session
curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{ "url": "https://site/secure", "session_id": "sess_...", "raw_html": true }'

Пакетный скрейпинг

Отправьте много страниц одной задачей через POST /api/v1/scrape/pages — каждый элемент это полноценный скрейп-запрос. Опрашивайте статус и забирайте результаты через те же эндпоинты задач.

curl -X POST http://localhost:8000/api/v1/scrape/pages 
  -H "Content-Type: application/json" 
  -d '{
    "pages": [
      { "url": "https://example.com", "proxy_type": "none" },
      { "url": "https://example.org", "proxy_type": "none" }
    ]
  }'

MCP

Скрейпер монтирует эндпоинт Model Context Protocol по адресу /mcp (Streamable HTTP). Укажите на него Claude или Cursor — и инструменты появятся автоматически:

• run_scrape_page
• run_scrape_pages
• get_job_status
• get_job_result
• cancel_scrape_job
• health

"yozh-scraper": {
  "type": "http",
  "url": "http://localhost:8000/mcp"
}

Дальше просто попросите: «Скрейпни https://example.com и расскажи, что на странице.» Тот же эндпоинт работает из агента LangChain или ноды MCP Client Tool в n8n.

Справочник по конфигурации

Запрос — ScrapeRequest (выборочно)

Справочник API

Важные детали