WebExtrator Инструкция по интеграции API для интеллектуального извлечения

POST https://api.acedata.cloud/webextrator/extract WebExtrator Интеллектуальный API извлечения преобразует URL в типизированные структурированные результаты — статьи, товары, рецепты, видео, обсуждения, вакансии и т.д., одновременно предоставляя очищенные Markdown и чистый текст. Когда вам нужны “чистые структурированные данные”, а не исходный HTML, это интерфейс, который следует использовать. В основе лежит трехуровневая система:

schema.org JSON-LD маппер — детерминированный, нулевые затраты LLM. Охватывает Wikipedia / BestBuy / AllRecipes / YouTube / большинство новостей / большинство страниц товаров.
Типизированное LLM извлечение — срабатывает только в случае, если schema.org не сработал. Выбор схемы в зависимости от типа страницы, строгая проверка Zod.
Readability + Markdown подстраховка — всегда работает, заполняя верхние поля, которые не были заполнены первыми двумя уровнями.

Повторные запросы URL будут перехвачены кэшем результатов Redis, <1 мс возврат.

Процесс подачи заявки

Чтобы использовать страницу сервиса WebExtrator, сначала перейдите в консоль Ace Data Cloud и получите ваш API Token для резервного копирования.

Если вы еще не вошли в систему или не зарегистрированы, вы будете автоматически перенаправлены на страницу входа, приглашающую вас зарегистрироваться и войти в систему, после чего вы будете автоматически возвращены на текущую страницу. Один API Token позволяет вызывать все сервисы платформы, не нужно подавать отдельные заявки на каждый сервис. При первой подаче заявки предоставляется бесплатный лимит, чтобы вы могли бесплатно протестировать; при недостатке лимита вы можете пополнить общий баланс в консоли.

📘 Полная документация: Страница сервиса WebExtrator →

Аутентификация

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

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

Extract принимает все параметры Render API (url, user_agent, timeout, wait_until, delay, wait_for_selector, block_resources, headers, cookies, callback_url, bypass_cache, cache_ttl_seconds, async), плюс два эксклюзивных поля Extract:

Поле	Тип	Обязательное	По умолчанию	Описание
`expected_type`	enum	❌	Автоопределение	Подсказка о типе страницы: `product` / `article` / `general`. Пропускает URL / текстовые эвристики, сразу идет по соответствующей ветке.
`enable_llm`	boolean	❌	`false`	Позволяет вызывать LLM извлечение, если schema.org не сработал. На страницах без JSON-LD, таких как Amazon / HN / Greenhouse, необходимо включить, чтобы получить типизированные результаты.

Когда страница содержит schema.org JSON-LD, enable_llm не имеет эффекта — детерминированный маппер сразу выдает результат, никогда не тратя вызов LLM. Вы бесплатно получаете типизированный результат.

Синхронный ответ

{
  "success": true,
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "trace_id": "550e8400-e29b-41d4-a716-446655440001",
  "started_at": 1777717800.123,
  "finished_at": 1777717802.535,
  "elapsed": 2.412,
  "data": {
    "kind": "extract",
    "url": "https://en.wikipedia.org/wiki/Diffbot",
    "finalUrl": "https://en.wikipedia.org/wiki/Diffbot",
    "contentType": "article",
    "title": "Diffbot",
    "description": "Американская компания по машинному обучению и управлению знаниями",
    "byline": "Участники проектов Wikimedia",
    "language": "en",
    "siteName": "Wikipedia",
    "publishedAt": "2007-08-08T05:47:27Z",
    "images": ["https://en.wikipedia.org/static/images/icons/enwiki-25.svg"],
    "links": ["https://en.wikipedia.org/wiki/Machine_learning"],
    "markdown": "# Diffbot\n\nDiffbot — разработчик алгоритмов машинного обучения ...",
    "text": "Diffbot — разработчик алгоритмов машинного обучения ...",
    "structured": {
      "schemaOrg": { "primary": { /* типизированная сущность */ }, "breadcrumbs": [], "all": [] },
      "openGraph": { "title": "...", "description": "...", "image": "...", "type": "..." },
      "jsonLd": [ /* исходный JSON-LD */ ]
    },
    "rawSignals": {
      "hasJsonLd": true,
      "title": "Diffbot - Wikipedia",
      "metaDescription": null,
      "pageStatus": 200,
      "textLength": 11473
    },
    "elapsedMs": 2412
  }
}

Верхние поля

Поле	Тип	Описание
`kind`	string	Фиксированное `"extract"`.
`url`	string	URL, который вы отправили.
`finalUrl`	string	Окончательный URL после перенаправления.
`contentType`	enum	`product` / `article` / `general`, определяется по `expected_type` → schema.org primary → эвристика последовательно.
`title`	string	Readability `<title>` или отрендеренный `document.title`.
`description`	string?	Приоритет: `<meta name="description" />` → `og:description` → schema.org / LLM извлечение → обрезка первого абзаца текста.
`byline`	string?	Автор / канал / компания. Источник `<meta name="author" />` → schema.org / LLM.
`language`	string?	`<html lang>`.
`siteName`	string?	`og:site_name`.
`publishedAt`	string?	ISO 8601. Приоритет: `article:published_time` → `<time datetime>` → schema.org / LLM.
`images`	string[]	Максимум 50 `<img src />`, преобразованные в абсолютные URL, дублирование удалено, `data:` URI отброшены.
`links`	string[]	Максимум 100 внешних ссылок, отфильтрованные фрагменты / `javascript:` / `mailto:` / `tel:`.
`markdown`	string	Markdown, преобразованный с помощью Turndown.
`text`	string	`textContent`, извлеченный с помощью Mozilla Readability.
`structured`	object	Полный структурированный результат, см. ниже.
`rawSignals`	object	Диагностическая информация для отладки.
`cached`	boolean?	При попадании в кэш будет `true`.
`cacheStoredAt`	number?	Unix временная метка в миллисекундах, когда запись кэша была впервые создана.

Подполя `data.structured`

Подполе	Когда появляется	Описание
`schemaOrg`	Всегда	`{ primary, breadcrumbs, all }`. `primary` — это типизированный объект с наивысшим приоритетом; если не найден, то `null`.
`openGraph`	Всегда	`{ title, description, image, type }`, полученные из `<meta property="og:*" />`.
`jsonLd`	Всегда	Исходный массив JSON всех блоков `<script type="application/ld+json">`.
`llm`	Когда LLM успешно выполнен	`{ kind, data, model, promptCharCount }`, типизированный результат, проверенный Zod.
`llmError`	Когда LLM выполнен, но неудачно	`{ kind, error, model }`, запрос не приведет к сбою, эвристический результат все равно будет возвращен.
`amazon`	Когда URL — `amazon.*`	Результаты старого специализированного парсера amazon (будут постепенно устаревать).

Область охвата маппера schema.org

Сортировка по приоритету (при попадании используется как structured.schemaOrg.primary):

Тип schema.org	Тип маппинга	Выходные поля
`Product`	product	`name, sku, gtin, model, color, brand, url, images, offer.{price,currency,availability,condition,seller}, rating.{value,count}, reviews[], properties[]`
`Recipe`	recipe	`name, description, image, datePublished, author, cookTime, prepTime, totalTime, recipeYield, ingredients[], instructions[], nutrition, rating, keywords, recipeCategory, recipeCuisine`
`VideoObject`	video	`name, description, thumbnailUrl, uploadDate, duration, embedUrl, contentUrl, channel, interactionCount`
`JobPosting`	job	`title, description, datePosted, validThrough, hiringOrganization, jobLocation, baseSalary, employmentType`
`Event` (включая `*Event`)	event	`name, description, startDate, endDate, location.{name,address}, organizer, offer.{url,price,currency}`
`Article` / `NewsArticle` / `BlogPosting` / `ScholarlyArticle` / `TechArticle` / `Report` / `*NewsArticle`	article	`subtype, headline, description, datePublished, dateModified, author, publisher, image[], url, sameAs[]`
`FAQPage`	faq	`questions[{question, answer}]`
`BreadcrumbList`	(привязка к sibling)	Всегда выводится в `structured.schemaOrg.breadcrumbs[]`, не будет использоваться как primary.

Обработка маппера:

Контейнер @graph (рекурсивное развертывание);
Массив @type (например, ["Recipe", "NewsArticle"] — оба распознаются, приоритет отдается первому);
Варианты с префиксом http://schema.org/;
Вложенные Offer и AggregateOffer (последний читает lowPrice);
Относительные URL изображений (разрешаются в абсолютные по finalUrl).

Типизированная схема LLM

Когда enable_llm: true и schema.org не имеет primary, парсер по URL использует эвристический (или подсказку expected_type) для выбора одной из моделей вывода Zod Schema:

Тип	Эвристика URL	Обязательные поля	Необязательные поля
`article`	Текст ≥400 слов и другие не попали	`headline`	`description, byline, publishedAt, language, topics[], sections[{heading,summary}]`
`product`	`amazon.* / ebay.* / aliexpress.* / temu.* / walmart.* / bestbuy.*`	`name`	`description, brand, sku, price, currency, availability, rating.{value,count}, bullets[], specifications[{name,value}]`
`discussion`	`news.ycombinator.com / reddit.com / lobste.rs`	`title`	`author, postedAt, points, commentCount, body, url`
`recipe`	`allrecipes / foodnetwork / seriouseats / epicurious / bonappetit / simplyrecipes`	`name`	`description, author, cookTime, prepTime, totalTime, recipeYield, ingredients[], instructions[], nutrition, rating, keywords[]`
`video`	`youtube.com/watch / youtu.be / vimeo.com/<id> / tiktok.com/@/video`	`name`	`description, channel, uploadDate, duration, viewCount, likeCount, thumbnailUrl, transcript`
`job`	`greenhouse.io / lever.co / jobs.* / careers.* / workable.com / bamboohr`	`title`	`description, company, location, remote, employmentType, datePosted, validThrough, salaryMin, salaryMax, salaryCurrency, salaryPeriod, responsibilities[], qualifications[]`

При успешном выполнении LLM также будет производить “последнюю попытку” заполнения верхних полей:

article → description / byline / publishedAt / language
product → description
discussion → description (первые 280 символов тела) / byline (автор) / publishedAt (postedAt)
recipe → description / byline (автор)
video → description / byline (канал) / publishedAt (uploadDate)
job → description / byline (компания) / publishedAt (datePosted)

Заполнение происходит только тогда, когда определенные источники данных не заполнили соответствующие поля — LLM всегда является последней инстанцией.

Кэширование

Одинаковые запросы будут хэшироваться в один и тот же ключ Redis: webextrator:cache:extract:<sha256(canonical-json)>. Ключ кэша игнорирует async, bypass_cache, cache_ttl_seconds (это переключатель, не влияющий на ответ). cookies / headers будут кэшироваться по отдельным корзинам.

Поле	Эффект
`bypass_cache: true`	Пропустить чтение; результат этого запроса все равно будет записан в кэш, чтобы следующий такой же запрос мог сработать.
`cache_ttl_seconds: 0`	Этот ответ не кэшируется.
`cache_ttl_seconds: N`	Настроить TTL для этой записи (по умолчанию 3600 секунд).

Ответы, попадающие в кэш, будут содержать data.cached: true и data.cacheStoredAt: <unix-ms>.

Асинхронный режим и обратные вызовы

Установите async: true, чтобы перейти в асинхронный режим (предоставление callback_url также автоматически приведет к этому). Платформа немедленно возвращает (HTTP 200):

{
  "success": true,
  "task_id": "550e8400-...",
  "trace_id": "6ba7b810-...",
  "started_at": 1777717800.123
}

Когда задача завершится, полный envelope будет POST на ваш callback_url (если он настроен). Также можно позже запросить через /webextrator/tasks.

Пример

1. Статья Wikipedia (попадание schema.org, LLM не требуется)

curl -X POST https://api.acedata.cloud/webextrator/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://en.wikipedia.org/wiki/Diffbot",
    "expected_type": "article"
  }'

Ключевые поля data.structured.schemaOrg.primary:

{
  "kind": "article",
  "subtype": "Статья",
  "headline": "Американская компания по машинному обучению и управлению знаниями",
  "datePublished": "2007-08-08T05:47:27Z",
  "dateModified": "2025-07-10T20:42:45Z",
  "author": { "name": "Участники проектов Wikimedia", "type": "Организация" },
  "publisher": { "name": "Фонд Wikimedia, Inc." }
}

2. Страница товара BestBuy (schema.org совпадение)

curl -X POST https://api.acedata.cloud/webextrator/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.bestbuy.com/product/apple-airpods-pro-2nd-generation-white/JJ8ZH6TPSW",
    "expected_type": "product"
  }'

schema.org извлечение：

{
  "kind": "product",
  "name": "Apple - Восстановленные Отличные - AirPods Pro (2-е поколение) - Белый",
  "sku": "10845412",
  "model": "MQD83AM/A",
  "color": "Белый",
  "brand": "Apple",
  "offer": { "price": 159.99, "currency": "USD", "availability": "https://schema.org/InStock", "seller": "Best Buy" },
  "rating": { "value": 4.4, "count": 8 }
}

3. Страница рецепта AllRecipes (с питательной ценностью и шагами)

curl -X POST https://api.acedata.cloud/webextrator/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.allrecipes.com/recipe/16354/easy-meatloaf/"
  }'

schema.org извлечение：

{
  "kind": "recipe",
  "name": "Легкий мясной хлеб",
  "cookTime": "PT60M",
  "totalTime": "PT75M",
  "recipeYield": "8 / 1 (9x5-дюймовый) мясной хлеб",
  "ingredients": ["1 1/2 фунта говяжьего фарша", "..."],
  "instructions": [{ "text": "Разогрейте духовку до 350°F ..." }, "..."],
  "rating": { "value": 4.7, "count": 9348 }
}

4. Страница обсуждения HN (без JSON-LD —— необходимо включить LLM)

curl -X POST https://api.acedata.cloud/webextrator/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.ycombinator.com/item?id=37000000",
    "enable_llm": true
  }'

data.structured.llm.data：

{
  "kind": "discussion",
  "title": "Показать HN: Новый способ извлечения веб-страниц",
  "author": "alice",
  "points": 173,
  "commentCount": 42,
  "body": "Привет HN, мы создали саморазмещенную альтернативу API анализа Diffbot ..."
}

Верхние поля также были заполнены: byline = "alice"、publishedAt = "..."。

5. Страница товара Amazon (Amazon без JSON-LD —— необходимо включить LLM)

curl -X POST https://api.acedata.cloud/webextrator/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.amazon.com/dp/B0BSHF7WHW",
    "expected_type": "product",
    "enable_llm": true
  }'

data.structured.llm.data（тип product）：

{
  "kind": "product",
  "name": "Apple 2023 MacBook Pro M2 Pro 14-дюймовый",
  "brand": "Apple",
  "price": 1799,
  "currency": "USD",
  "bullets": ["Чип Apple M2 Pro с 10-ядерным ЦП", "..."],
  "specifications": [{ "name": "Размер дисплея", "value": "14.2 дюйма" }, "..."]
}

Python (requests)

import os, requests

API_KEY = os.environ["ACEDATA_API_KEY"]

resp = requests.post(
    "https://api.acedata.cloud/webextrator/extract",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://en.wikipedia.org/wiki/Diffbot",
        "expected_type": "article",
    },
    timeout=120,
)
resp.raise_for_status()
data = resp.json()["data"]

primary = (data.get("structured") or {}).get("schemaOrg", {}).get("primary")
print("contentType:", data["contentType"])
print("title:      ", data["title"])
print("byline:     ", data.get("byline"))
print("publishedAt:", data.get("publishedAt"))
if primary and primary["kind"] == "article":
    print("headline:    ", primary["headline"])
    print("dateModified:", primary.get("dateModified"))

Node.js (fetch)

const apiKey = process.env.ACEDATA_API_KEY;

const res = await fetch('https://api.acedata.cloud/webextrator/extract', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://www.allrecipes.com/recipe/16354/easy-meatloaf/',
  }),
});
const { data } = await res.json();
const recipe = data?.structured?.schemaOrg?.primary;
console.log(recipe.name, recipe.cookTime, recipe.ingredients.length, 'ингредиентов');

Подсказки и ловушки

Если можно передать expected_type, передавайте. Бесплатная подсказка, пропустите эвристическое определение, особенно полезно для страниц, URL-адреса которых не находятся в встроенном списке.
enable_llm: true на страницах с совпадением schema.org бесплатно. LLM вызывается только тогда, когда schema.org не имеет primary, поэтому по умолчанию это также безопасно.
При отладке сначала смотрите rawSignals.hasJsonLd. Если это true, но structured.schemaOrg.primary равно null, это означает, что страница использует тип @type, который еще не охвачен нашим маппером — создайте issue, мы добавим.
structured.llmError является информационным. Запрос все равно успешен, эвристические результаты все равно возвращаются. Смотрите llmError.error, чтобы определить причину (тайм-аут, ошибка разбора JSON, ошибка проверки Zod).
Ссылки на не-статьи links[] не будут сортироваться по релевантности. Только по “максимум 100 записей + фильтрация недействительных протоколов” стараемся очистить.
Кэширование также учитывается в расчетах. Кэш предназначен для уменьшения задержек и защиты пула браузеров, а не для экономии.

Начало работы

AI Чат

AI Изображение

AI Видео

AI Аудио

Веб и данные

CAPTCHA

Идентичность

Прокси

Продвинутый

Coding

WebExtrator Инструкция по интеграции API для интеллектуального извлечения

Процесс подачи заявки

Аутентификация

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

Синхронный ответ

Верхние поля

Подполя `data.structured`

Область охвата маппера schema.org

Типизированная схема LLM

Кэширование

Асинхронный режим и обратные вызовы

Пример

1. Статья Wikipedia (попадание schema.org, LLM не требуется)

2. Страница товара BestBuy (schema.org совпадение)

3. Страница рецепта AllRecipes (с питательной ценностью и шагами)

4. Страница обсуждения HN (без JSON-LD —— необходимо включить LLM)

5. Страница товара Amazon (Amazon без JSON-LD —— необходимо включить LLM)

Python (requests)

Node.js (fetch)

Подсказки и ловушки

​Процесс подачи заявки

​Аутентификация

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

​Синхронный ответ

​Верхние поля

​Подполя data.structured

​Область охвата маппера schema.org

​Типизированная схема LLM

​Кэширование

​Асинхронный режим и обратные вызовы

​Пример

​1. Статья Wikipedia (попадание schema.org, LLM не требуется)

​2. Страница товара BestBuy (schema.org совпадение)

​3. Страница рецепта AllRecipes (с питательной ценностью и шагами)

​4. Страница обсуждения HN (без JSON-LD —— необходимо включить LLM)

​5. Страница товара Amazon (Amazon без JSON-LD —— необходимо включить LLM)

​Python (requests)

​Node.js (fetch)

​Подсказки и ловушки

Процесс подачи заявки

Аутентификация

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

Синхронный ответ

Верхние поля

Подполя `data.structured`

Область охвата маппера schema.org

Типизированная схема LLM

Кэширование

Асинхронный режим и обратные вызовы

Пример

1. Статья Wikipedia (попадание schema.org, LLM не требуется)

2. Страница товара BestBuy (schema.org совпадение)

3. Страница рецепта AllRecipes (с питательной ценностью и шагами)

4. Страница обсуждения HN (без JSON-LD —— необходимо включить LLM)

5. Страница товара Amazon (Amazon без JSON-LD —— необходимо включить LLM)

Python (requests)

Node.js (fetch)

Подсказки и ловушки