WebExtrator Guía de Integración de API de Extracción Inteligente

POST https://api.acedata.cloud/webextrator/extract La API de extracción inteligente WebExtrator convierte una URL en resultados estructurados tipificados — artículos, productos, recetas, videos, discusiones, reclutamiento, etc., junto con Markdown y texto plano limpios. Este es el interfaz que debes usar cuando deseas “datos estructurados limpios” en lugar de HTML crudo. En su base hay una tubería de tres capas:

Esquema de mapeo JSON-LD de schema.org — determinista, costo cero de LLM. Cubre Wikipedia / BestBuy / AllRecipes / YouTube / la mayoría de las noticias / la mayoría de las páginas de productos.
Extracción tipificada de LLM — se activa solo cuando schema.org no coincide. Selecciona el esquema según el tipo de página, verificación estricta de Zod.
Readability + Markdown como respaldo — siempre en funcionamiento, completa los campos de nivel superior que no fueron llenados por las dos primeras capas.

Las solicitudes repetidas de URL serán capturadas por la caché de resultados de Redis, <1 ms de retorno.

Proceso de Solicitud

Para usar la página de servicios de WebExtrator, primero ve a la consola de Ace Data Cloud para obtener tu Token de API, guárdalo para uso futuro.

Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invita a registrarte e iniciar sesión, y después volverás automáticamente a la página actual. Un Token de API es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno por cada servicio. La primera solicitud te otorgará un crédito gratuito para que lo pruebes; si el crédito es insuficiente, puedes recargar el saldo general en la consola.

📘 Documentación completa: Página de servicios de WebExtrator →

Autenticación

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

Parámetros de Solicitud

Extract acepta todos los parámetros de Render API (url, user_agent, timeout, wait_until, delay, wait_for_selector, block_resources, headers, cookies, callback_url, bypass_cache, cache_ttl_seconds, async), además de dos campos exclusivos de Extract:

Campo	Tipo	Requerido	Predeterminado	Descripción
`expected_type`	enum	❌	Auto-determinado	Sugerencia de tipo de página: `product` / `article` / `general`. Salta la heurística de URL / texto y va directamente a la rama correspondiente.
`enable_llm`	boolean	❌	`false`	Permite la llamada a la extracción LLM cuando schema.org no coincide. En páginas sin JSON-LD como Amazon / HN / Greenhouse, debe estar habilitado para obtener resultados tipificados.

Cuando la página tiene schema.org JSON-LD, enable_llm es ineficaz — el mapeador determinista devuelve resultados directamente, nunca desperdiciará una llamada LLM. Obtienes resultados tipificados sin costo.

Respuesta Sincrónica

{
  "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": "Empresa estadounidense de aprendizaje automático y gestión del conocimiento",
    "byline": "Contribuyentes a proyectos de 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 es un desarrollador de aprendizaje automático ...",
    "text": "Diffbot es un desarrollador de algoritmos de aprendizaje automático ...",
    "structured": {
      "schemaOrg": { "primary": { /* Entidad tipificada */ }, "breadcrumbs": [], "all": [] },
      "openGraph": { "title": "...", "description": "...", "image": "...", "type": "..." },
      "jsonLd": [ /* JSON-LD original */ ]
    },
    "rawSignals": {
      "hasJsonLd": true,
      "title": "Diffbot - Wikipedia",
      "metaDescription": null,
      "pageStatus": 200,
      "textLength": 11473
    },
    "elapsedMs": 2412
  }
}

Campos de Nivel Superior

Campo	Tipo	Descripción
`kind`	string	Fijo `"extract"`.
`url`	string	La URL que enviaste.
`finalUrl`	string	La URL final después de la redirección.
`contentType`	enum	`product` / `article` / `general`, determinado por `expected_type` → schema.org primary → heurística en orden.
`title`	string	`<title>` de Readability o `document.title` renderizado.
`description`	string?	Prioridad: `<meta name="description" />` → `og:description` → extracción de schema.org / LLM → truncamiento del primer párrafo del texto.
`byline`	string?	Autor / canal / empresa. Fuente `<meta name="author" />` → schema.org / LLM.
`language`	string?	`<html lang>`.
`siteName`	string?	`og:site_name`.
`publishedAt`	string?	ISO 8601. Prioridad: `article:published_time` → `<time datetime>` → schema.org / LLM.
`images`	string[]	Hasta 50 `<img src />`, resueltos a URL absolutas, deduplicados, eliminando `data:` URI.
`links`	string[]	Hasta 100 enlaces externos, filtrados de fragmentos / `javascript:` / `mailto:` / `tel:`.
`markdown`	string	Markdown convertido por Turndown.
`text`	string	`textContent` extraído por Mozilla Readability.
`structured`	object	Resultados estructurados completos, ver abajo.
`rawSignals`	object	Información de diagnóstico para depuración.
`cached`	boolean?	`true` cuando se encuentra en caché.
`cacheStoredAt`	number?	Marca de tiempo Unix en milisegundos cuando se escribió por primera vez la entrada en caché.

Subcampos de `data.structured`

Subcampo	Cuándo aparece	Descripción
`schemaOrg`	Siempre	`{ primary, breadcrumbs, all }`. `primary` es el tipo de entidad tipificada de mayor prioridad; si no se encuentra, es `null`.
`openGraph`	Siempre	`{ title, description, image, type }`, proveniente de `<meta property="og:*" />`.
`jsonLd`	Siempre	Todos los bloques `<script type="application/ld+json">` en un array JSON original.
`llm`	Cuando LLM se ejecuta y tiene éxito	`{ kind, data, model, promptCharCount }`, resultados tipificados validados por Zod.
`llmError`	Cuando LLM se ejecuta pero falla	`{ kind, error, model }`, la solicitud no fallará, los resultados heurísticos aún se devolverán.
`amazon`	Cuando la URL es `amazon.*`	Resultados de un antiguo extractor específico de amazon (se eliminará gradualmente).

Alcance del mapeador schema.org

Ordenado por prioridad (al coincidir se considera structured.schemaOrg.primary):

Tipo schema.org	Mapeo kind	Campos de salida
`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` (incluyendo `*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`	(anclado en sibling)	Siempre se emite a `structured.schemaOrg.breadcrumbs[]`, no se considera como primary.

Procesamiento del mapeador:

Contenedor @graph (despliegue recursivo);
Array @type (como ["Recipe", "NewsArticle"] — ambos son reconocidos, se toma el de mayor prioridad);
Variantes con prefijo http://schema.org/;
Offer anidado y AggregateOffer (este último lee lowPrice);
URL de imágenes relativas (se resuelven a absolutas según finalUrl).

Schema tipificado LLM

Cuando enable_llm: true y schema.org no tiene primary, el extractor utiliza heurísticas de URL (o sugerencias de expected_type) para seleccionar uno de los modelos de validación Zod a continuación:

Kind	Heurística de URL	Campos obligatorios	Campos opcionales
`article`	Texto ≥400 palabras y otros no coincidentes	`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[]`

Cuando LLM tiene éxito, también rellenará los campos de nivel superior como “último recurso”:

article → description / byline / publishedAt / language
product → description
discussion → description (primeros 280 caracteres del cuerpo) / byline (autor) / publishedAt (postedAt)
recipe → description / byline (autor)
video → description / byline (canal) / publishedAt (uploadDate)
job → description / byline (empresa) / publishedAt (datePosted)

El relleno solo se activa cuando la fuente de datos determinista no ha llenado los campos correspondientes — LLM siempre es el último recurso.

Caché

Las solicitudes idénticas se hash a la misma clave de Redis: webextrator:cache:extract:<sha256(canonical-json)>. La clave de caché ignora async, bypass_cache, cache_ttl_seconds (esto es un interruptor de operación, no afecta la respuesta). cookies / headers se agrupan en caché.

Campo	Efecto
`bypass_cache: true`	Salta la lectura; el resultado de esta vez aún se escribirá en caché, la próxima solicitud idéntica podrá coincidir.
`cache_ttl_seconds: 0`	Esta respuesta no se almacena en caché.
`cache_ttl_seconds: N`	Personaliza el TTL de esta entrada (por defecto 3600 segundos).

Las respuestas que coinciden con la caché incluirán data.cached: true y data.cacheStoredAt: <unix-ms>.

Modo asíncrono y callbacks

Configurar async: true para entrar en modo asíncrono (proporcionar callback_url también hará que se active automáticamente). La plataforma devuelve inmediatamente (HTTP 200):

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

Cuando la tarea se complete, se enviará el sobre completo POST a tu callback_url (si se configuró). También puedes consultar proactivamente a través de /webextrator/tasks.

Ejemplo

1. Artículo de Wikipedia (coincidencia schema.org, no necesita 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"
  }'

Campo clave data.structured.schemaOrg.primary:

{
  "kind": "article",
  "subtype": "Artículo",
  "headline": "Empresa estadounidense de aprendizaje automático y gestión del conocimiento",
  "datePublished": "2007-08-08T05:47:27Z",
  "dateModified": "2025-07-10T20:42:45Z",
  "author": { "name": "Contribuyentes a proyectos de Wikimedia", "type": "Organización" },
  "publisher": { "name": "Wikimedia Foundation, Inc." }
}

2. Página de producto de BestBuy (schema.org hit)

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 extracción:

{
  "kind": "product",
  "name": "Apple - Refurbished Excellent - AirPods Pro (2nd generation) - White",
  "sku": "10845412",
  "model": "MQD83AM/A",
  "color": "Blanco",
  "brand": "Apple",
  "offer": { "price": 159.99, "currency": "USD", "availability": "https://schema.org/InStock", "seller": "Best Buy" },
  "rating": { "value": 4.4, "count": 8 }
}

3. Página de recetas de AllRecipes (incluye nutrición y pasos)

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 extracción:

{
  "kind": "recipe",
  "name": "Easy Meatloaf",
  "cookTime": "PT60M",
  "totalTime": "PT75M",
  "recipeYield": "8 / 1 (9x5-inch) meatloaf",
  "ingredients": ["1 1/2 pounds ground beef", "..."],
  "instructions": [{ "text": "Precalentar el horno a 350°F ..." }, "..."],
  "rating": { "value": 4.7, "count": 9348 }
}

4. Página de discusión de HN (sin JSON-LD —— necesita habilitar 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": "Show HN: A new way to extract web pages",
  "author": "alice",
  "points": 173,
  "commentCount": 42,
  "body": "Hola HN, construimos una alternativa autohospedada a la API de análisis de Diffbot ..."
}

Los campos de nivel superior también se rellenaron: byline = "alice"、publishedAt = "..."。

5. Página de producto de Amazon (Amazon sin JSON-LD —— necesita habilitar 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 (tipificado product):

{
  "kind": "product",
  "name": "Apple 2023 MacBook Pro M2 Pro de 14 pulgadas",
  "brand": "Apple",
  "price": 1799,
  "currency": "USD",
  "bullets": ["Chip Apple M2 Pro con CPU de 10 núcleos", "..."],
  "specifications": [{ "name": "Tamaño de pantalla", "value": "14.2 pulgadas" }, "..."]
}

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, 'tipos de ingredientes');

Consejos y trampas

Si puedes pasar expected_type, hazlo. Consejo gratuito, salta la evaluación heurística, especialmente útil para páginas cuyo patrón de URL no está en la lista incorporada.
enable_llm: true en páginas con schema.org hit es gratuito. LLM solo se llama cuando schema.org no tiene primary, por lo que dejarlo activado también es seguro.
Al depurar, primero mira rawSignals.hasJsonLd. Si es true pero structured.schemaOrg.primary es null, significa que la página usó un tipo @type que nuestro mapeador aún no ha cubierto —— informa un problema, lo agregaremos.
structured.llmError es informativo. La solicitud sigue siendo exitosa, el resultado heurístico aún se devuelve. Mira llmError.error para localizar la causa (tiempo de espera, error de análisis JSON, error de validación Zod).
Los links[] de páginas que no son artículos no se ordenarán por relevancia. Solo se limpiarán según “un límite de 100 entradas + filtrado de protocolos no válidos”.
Los aciertos de caché también se facturan. La caché es para retrasos y protección de la piscina de navegadores, no para ahorrar dinero.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Proxy

Avanzado

WebExtrator Guía de Integración de API de Extracción Inteligente

Proceso de Solicitud

Autenticación

Parámetros de Solicitud

Respuesta Sincrónica

Campos de Nivel Superior

Subcampos de `data.structured`

Alcance del mapeador schema.org

Schema tipificado LLM

Caché

Modo asíncrono y callbacks

Ejemplo

1. Artículo de Wikipedia (coincidencia schema.org, no necesita LLM)

2. Página de producto de BestBuy (schema.org hit)

3. Página de recetas de AllRecipes (incluye nutrición y pasos)

4. Página de discusión de HN (sin JSON-LD —— necesita habilitar LLM)

5. Página de producto de Amazon (Amazon sin JSON-LD —— necesita habilitar LLM)

Python (requests)

Node.js (fetch)

Consejos y trampas

​Proceso de Solicitud

​Autenticación

​Parámetros de Solicitud

​Respuesta Sincrónica

​Campos de Nivel Superior

​Subcampos de data.structured

​Alcance del mapeador schema.org

​Schema tipificado LLM

​Caché

​Modo asíncrono y callbacks

​Ejemplo

​1. Artículo de Wikipedia (coincidencia schema.org, no necesita LLM)

​2. Página de producto de BestBuy (schema.org hit)

​3. Página de recetas de AllRecipes (incluye nutrición y pasos)

​4. Página de discusión de HN (sin JSON-LD —— necesita habilitar LLM)

​5. Página de producto de Amazon (Amazon sin JSON-LD —— necesita habilitar LLM)

​Python (requests)

​Node.js (fetch)

​Consejos y trampas

Proceso de Solicitud

Autenticación

Parámetros de Solicitud

Respuesta Sincrónica

Campos de Nivel Superior

Subcampos de `data.structured`

Alcance del mapeador schema.org

Schema tipificado LLM

Caché

Modo asíncrono y callbacks

Ejemplo

1. Artículo de Wikipedia (coincidencia schema.org, no necesita LLM)

2. Página de producto de BestBuy (schema.org hit)

3. Página de recetas de AllRecipes (incluye nutrición y pasos)

4. Página de discusión de HN (sin JSON-LD —— necesita habilitar LLM)

5. Página de producto de Amazon (Amazon sin JSON-LD —— necesita habilitar LLM)

Python (requests)

Node.js (fetch)

Consejos y trampas