Saltar al contenido
CrawlForge MCP
Herramienta de IA3 credits

extract_structured

Dele al extractor un JSON Schema y un prompt en lenguaje natural. El LLM lee la página y devuelve datos que coinciden con su esquema. Cuando no hay un proveedor de LLM configurado, recurre a la extracción con selectores CSS usando sus indicaciones.

Casos de uso

Extracción de productos basada en esquema

Defina los campos que desea una sola vez; el LLM asigna cualquier sitio de comercio electrónico a su esquema.

Análisis de currículos y documentos

Extraiga nombres de candidatos, habilidades e historial laboral directamente en un objeto tipado.

Carga inicial de grafos de conocimiento

Extraiga entidades y relaciones de los artículos en JSON estructurado para cargadores de grafos.

Endpoint

POST/api/v1/tools/extract_structured
Auth Required
1 req/s en el plan Free
3 credits

Parameters

NameTypeRequiredDefaultDescription
url
stringRequired-
URL de la que extraer datos
Example: https://example.com/product/123
schema
objectRequired-
JSON Schema que describe los datos a extraer
Example: {"type":"object","properties":{"title":{"type":"string"},"price":{"type":"number"}},"required":["title"]}
prompt
stringOptional-
Instrucciones en lenguaje natural que guían la extracción con LLM
Example: Extract the product name, current price, and whether it is in stock
llmConfig
objectOptional-
Configuración opcional del proveedor de LLM (provider, apiKey). Omítala para usar el respaldo de selectores CSS.
Example: {"provider": "openai", "apiKey": "sk-..."}
selectorHints
objectOptional-
Indicaciones de selectores CSS para guiar la extracción (también usadas por el respaldo de selectores)
Example: {"title": "h1.product-title", "price": ".price"}
fallbackToSelectors
booleanOptionaltrue
Recurrir a la extracción con selectores CSS cuando el LLM no esté disponible
Example: true
respect_robots
booleanOptionaltrue
Respeta el robots.txt del sitio de destino. Con el valor `true`, una ruta que robots.txt no permita a `CrawlForge` se rechaza con un 403 antes de descargar nada y no se cobran credits. Póngalo en `false` solo para destinos con los que tenga su propio acuerdo: la respuesta incluye entonces una entrada `warnings` y la anulación queda registrada en su API key.
Example: true

Ejemplos de solicitud

cURL — extracción con LLM

terminalBash
curl -X POST https://crawlforge.dev/api/v1/tools/extract_structured \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/123",
    "schema": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "price": { "type": "number" },
        "in_stock": { "type": "boolean" }
      },
      "required": ["title", "price"]
    },
    "prompt": "Extract the product name, price in USD, and availability",
    "llmConfig": { "provider": "openai", "apiKey": "sk-..." }
  }'

TypeScript — respaldo de selectores

extractStructured.tsTypescript
// npm install crawlforge-sdk
import { CrawlForge } from 'crawlforge-sdk';

const client = new CrawlForge({ apiKey: process.env.CRAWLFORGE_API_KEY });

const result = await client.extractStructured({
  url: 'https://example.com/product/123',
  schema: {
    type: 'object',
    properties: {
      title: { type: 'string' },
      price: { type: 'number' },
    },
    required: ['title'],
  },
  selectorHints: {
    title: 'h1.product-title',
    price: '.price-value',
  },
  fallbackToSelectors: true,
});

// result.data is untyped in crawlforge-sdk 0.1 — its shape is the Response Example below.
const { data: product } = result.data as { data: { title: string; price: number } };
console.log(product.title, product.price);

Python

extract_structured.pyPython
# pip install crawlforge
from crawlforge import CrawlForge

client = CrawlForge()  # reads CRAWLFORGE_API_KEY

result = client.extract_structured(
    url='https://example.com/article/42',
    schema={
        'type': 'object',
        'properties': {
            'headline': {'type': 'string'},
            'author': {'type': 'string'},
            'published_at': {'type': 'string'},
            'tags': {'type': 'array'},
        },
        'required': ['headline'],
    },
    prompt='Extract headline, author, publish date (ISO 8601), and tags',
)

# result.data is a plain dict — its shape is the Response Example below.
print(result.data['data'])

Ejemplo de respuesta

200 OK1.2s
{
  "success": true,
  "data": {
    "url": "https://example.com/product/123",
    "data": {
      "title": "Premium Wireless Headphones",
      "price": 299.99,
      "in_stock": true
    },
    "extraction": {
      "method_by_field": {
        "title": "selector",
        "price": "json-ld",
        "in_stock": "meta"
      },
      "llm_used": false,
      "note": "Selector/structured-data extraction; LLM-guided extraction is available via the CrawlForge MCP server"
    },
    "extracted_at": "2026-08-26T14:30:00.000Z"
  },
  "credits_used": 3,
  "credits_remaining": 997,
  "processing_time": 1240
}
Field Descriptions
data.dataUna clave por cada propiedad de tu esquema. Una propiedad `number` o `integer` toma el primer número del texto encontrado (`"4.5 out of 5"` es 4.5, `"$1,299.00"` es 1299; un `integer` solo si es entero); el texto sin ningún número se devuelve tal cual. Un campo que no se pudo encontrar es null.
data.extraction.method_by_fieldCómo se obtuvo cada campo: `selector` desde una entrada de selectorHints, `json-ld` desde datos estructurados, `meta` desde una metaetiqueta, o `none` cuando nada coincidió.
data.extraction.llm_usedSiempre false en la API REST alojada: la extracción se basa en selectores y datos estructurados, nunca es generativa.
data.extraction.noteRecuerda dónde está disponible la extracción guiada por LLM.
data.extracted_atMarca de tiempo ISO 8601 de la extracción.

Manejo de errores

Bloqueado por robots.txt (403 Forbidden)

El robots.txt del sitio de destino no permite esta ruta a CrawlForge. Establezca respect_robots: false para anularlo si tiene su propio acuerdo con el destino: la anulación queda registrada en su API key. La anulación no alcanza a un host incluido en la lista de exclusión permanente de CrawlForge, que se rechaza sea cual sea el valor de respect_robots.

Costo en credits

3 credits
3 credits por solicitud
3 credits fijos tanto si la llamada usa el LLM como el respaldo de selectores.

Consejo: Combínela con scrape_structured (2 credits, solo CSS) cuando ya tenga selectores estables y no necesite la flexibilidad de un LLM.

Herramientas relacionadas

scrape_structured
Extracción con selectores CSS (2 credits)
analyze_content
Análisis de sentimiento, entidades y temas (3 credits)