Cheerio (быстрое извлечение)

Быстрое извлечение структурированных данных из веб-страниц через CSS-селекторы без headless-браузера. Использует HTTP-запрос + cheerio для парсинга HTML. Идеально для серверных страниц (SSR, статические сайты), где JavaScript-рендеринг не требуется.

Заметка

Полная спецификация параметров: API Reference

Совет

Для статических и серверных страниц Cheerio в 10–50 раз быстрее /v1/browser/scrape — нет расходов на запуск браузера. Если страница требует выполнения JavaScript (SPA, React, Vue), используйте /v1/browser/scrape.

Эндпоинты

Метод	Эндпоинт	Описание
POST	/v1/browser/cheerio	Извлечение данных без браузера

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

API принимает URL и массив CSS-селекторов, загружает HTML через HTTP-запрос и парсит его с помощью cheerio. Возвращает структурированный JSON с текстом, HTML и атрибутами каждого найденного элемента.

cURL

# Извлечение заголовков и параграфов
curl -X POST "https://proxy.unoapi.ru/v1/browser/cheerio" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "elements": [
      {"selector": "h1"},
      {"selector": "p"}
    ]
  }'

# С кастомными заголовками и таймаутом
curl -X POST "https://proxy.unoapi.ru/v1/browser/cheerio" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "elements": [{"selector": ".product-card"}],
    "headers": {"Accept-Language": "ru-RU"},
    "timeout": 10000
  }'

TypeScript

const response = await fetch('https://proxy.unoapi.ru/v1/browser/cheerio', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    elements: [
      { selector: 'h1' },
      { selector: '.product-card' }
    ]
  })
});

const { data } = await response.json();

for (const element of data) {
  console.log(`Селектор: ${element.selector}`);
  for (const result of element.results) {
    console.log(`  Текст: ${result.text}`);
    console.log(`  HTML: ${result.html}`);
  }
}

Python

import requests

response = requests.post(
    'https://proxy.unoapi.ru/v1/browser/cheerio',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'url': 'https://example.com',
        'elements': [
            {'selector': 'h1'},
            {'selector': '.product-card'}
        ]
    }
)

data = response.json()['data']
for element in data:
    print(f"Селектор: {element['selector']}")
    for result in element['results']:
        print(f"  Текст: {result['text']}")

Go

body, _ := json.Marshal(map[string]interface{}{
  "url": "https://example.com",
  "elements": []map[string]string{
    {"selector": "h1"},
    {"selector": ".product-card"},
  },
})

req, _ := http.NewRequest("POST", "https://proxy.unoapi.ru/v1/browser/cheerio", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := client.Do(req)
var result struct {
  Data []struct {
    Selector string `json:"selector"`
    Results  []struct {
      Text string `json:"text"`
      HTML string `json:"html"`
    } `json:"results"`
  } `json:"data"`
}
json.NewDecoder(resp.Body).Decode(&result)

Формат ответа

API возвращает JSON с массивом data, где каждый элемент соответствует одному селектору из запроса:

{
  "data": [
    {
      "selector": "h1",
      "results": [
        {
          "html": "Добро пожаловать",
          "text": "Добро пожаловать",
          "attributes": [
            { "name": "class", "value": "title" }
          ]
        }
      ]
    },
    {
      "selector": ".product-card",
      "results": [
        {
          "html": "<img src=\"...\"><h3>Товар 1</h3><span>1 500 ₽</span>",
          "text": "Товар 1 1 500 ₽",
          "attributes": [
            { "name": "class", "value": "product-card" }
          ]
        }
      ]
    }
  ]
}

Поля каждого результата:

Поле	Тип	Описание
html	string	Внутренний HTML элемента (innerHTML)
text	string	Текстовое содержимое (textContent)
attributes	array	Массив атрибутов: {name, value}

Осторожно

В отличие от /v1/browser/scrape, Cheerio не возвращает поля width, height, top, left — без браузера нет рендеринга и координат элементов.

Параметры запроса

Параметр	Тип	Обязательный	Описание
url	string	url или html	URL страницы для извлечения данных
html	string	url или html	HTML-контент для парсинга (вместо URL)
elements	array	Да	Массив {selector: string}, минимум 1
headers	object	Нет	Кастомные HTTP-заголовки для запроса
timeout	number	Нет	Таймаут в мс (1000–60000, по умолчанию 30000)

Заметка

Нельзя передавать url и html одновременно — только одно из двух.

Заголовки ответа

API возвращает информацию о целевой странице через заголовки:

• X-Response-Code — HTTP-код ответа целевой страницы
• X-Response-URL — финальный URL после редиректов

Рендеринг HTML

Вместо URL можно передать HTML-контент напрямую для парсинга:

curl -X POST "https://proxy.unoapi.ru/v1/browser/cheerio" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<div><h1>Тест</h1><p class=\"info\">Текст</p></div>",
    "elements": [{"selector": "h1"}, {"selector": ".info"}]
  }'

При использовании html запрос выполняется мгновенно — без сетевого обращения.

Cheerio vs Scrape

	/v1/browser/cheerio	/v1/browser/scrape
Скорость	~50–100 мс	~2–10 сек
JavaScript	Не выполняется	Полный рендеринг
Координаты	Нет	width, height, top, left
Параметры	headers, timeout	Viewport, cookies, waitFor, и т.д.
Идеально для	SSR, статика, API	SPA, динамический контент

Сценарии использования

• Парсинг статических сайтов — блоги, документация, новостные сайты
• SEO-аудит — извлечение <title>, <meta>, заголовков и ссылок
• Мониторинг цен — серверные каталоги и маркетплейсы
• Агрегация контента — сбор данных с SSR-страниц
• Парсинг HTML-фрагментов — обработка HTML из других API

SSRF-защита

API блокирует небезопасные URL: localhost, приватные IP, .local домены.