Введіть один URL-адресу — отримайте чисті структуровані дані

Скрейпінг

Yozh Scraper відображає будь-яку URL-адресу в реальному браузері Playwright і повертає саме те, що ви просите — витягнуті поля, необроблений HTML або знімок екрана всієї сторінки. Кожен скрейп — це асинхронне завдання: вкажіть URL-адресу, перевірте стан завдання, отримайте результат. Проксі, прихований режим, пресети та сесії з автентифікацією — все це працює на найвищому рівні.

• Реальне відтворення у браузері — Playwright відтворює сторінки, створені за допомогою JavaScript; переключіть render для статичного HTML.
• Структуроване вилучення — правила для полів на основі CSS або XPath повертають очищений data об’єкт, що набагато ефективніше, ніж самостійне завантаження та аналіз необробленого HTML-коду.
• Вбудовані проксі-сервери — CyberYozh (побутові / мобільні LTE / центри обробки даних) з геотаргетингом та без виявлення ідентифікаторів пулів.
• Режим «Stealth» за замовчуванням — патчі playwright-stealth (navigator.webdriver, відбитки WebGL / Canvas, середовище виконання Chrome) для зменшення ймовірності виявлення ботів.
• Пресети — збір даних з 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_type для будь-якого запиту.

Виберіть місце розташування за допомогою proxy_geo (country_code / region / city). Дізнайтеся, що ви придбали, не шукаючи ідентифікатори пулів:

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 для будь-якого скрейпу, щоб сторінки завантажувалися із збереженими файлами cookie та станом сховища. Необхідно для цілей, що вимагають входу, таких як linkedin_profile пресет.

1. POST /api/v1/sessions — create. Pins 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 set — скрейпінг з авторизацією.
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, так і з вузла n8n MCP Client Tool.

Довідник з налаштування

Запит — ScrapeRequest (вибрано)

Довідник API

Важливі деталі