> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/es/api-web/scrape/analisis-con-ia.md). # Análisis con IA Extrae JSON estructurado de cualquier página en una sola solicitud de la Web API, usando un prompt en lenguaje natural o una definición de JSON Schema. {% hint style="danger" %} **Cuesta extra:** Usar análisis con IA con tus `/scrape` solicitudes consume significativamente más crédito de la cuenta. {% endhint %} La Web API proporciona extracción estructurada de JSON en la misma llamada HTTP que obtiene la página web objetivo. Combina `output: ["json"]` con el `json` parámetro de nivel raíz para extraer campos personalizados usando instrucciones en lenguaje natural o definiciones estrictas de OpenAPI / JSON Schema.
CampoDescripciónTipo
json.promptDescripción en lenguaje natural de los campos a extraer.cadena
json.schemaUn Objeto de esquema OpenAPI al que debe ajustarse el resultado.objeto
{% hint style="success" %} Usa `prompt` cuando exploras una página y aún no conoces su estructura. Usa `schema` cuando la salida alimenta código, donde una clave renombrada o ausente lo rompería. {% endhint %} ## Analizadores dedicados vs. extracción personalizada con IA La Web API admite dos mecanismos de análisis, ambos devolviendo datos bajo la `json` clave en el `results[]` arreglo:
TipoMétodoDestinosUsar para
Analizador integradoEstablece output: ["json"] sin proporcionar un json objeto raíz.Destinos dedicados con analizadores preconstruidos (p. ej., /scrape/amazon/product, /scrape/google/search).Esquemas estandarizados de comercio electrónico y SERP mantenidos por Oxylabs.
Extracción personalizada con IAEstablece output: ["json"] y pasa json: { "prompt": ... } o json: { "schema": ... } objeto raíz.Toda ruta, incluyendo las genéricas /v1/scrape y los destinos sin analizadores dedicados.Esquemas personalizados, diseños de página únicos o campos no estándar.
{% hint style="warning" %} Tanto los analizadores preconstruidos como las extracciones personalizadas con IA rellenan la `results[].json` clave en el payload de respuesta. Si llamas a un scraper dedicado (p. ej., `/v1/scrape/amazon/product`) con `output: ["json"]` y usas un `json` objeto de extracción personalizado, la extracción personalizada con IA sobrescribirá la salida del analizador integrado. Elige una opción por solicitud. {% endhint %} ## Modos de extracción: `prompt` vs. `schema` Al usar extracción personalizada con IA, el `json` objeto acepta una `prompt` cadena o una `schema` objeto. No pases ambos parámetros en la misma solicitud. ### Lenguaje natural (`prompt`) Pasa una instrucción en lenguaje natural que describa los campos deseados. El modelo de IA inspecciona el DOM de la página y construye un objeto JSON correspondiente. ```json { "url": "https://example.com/product/10928", "output": ["json"], "json": { "prompt": "Extract the main product title, current sale price as a number, currency code, and a list of image URLs." } } ``` #### Cuándo usar * Prototipado rápido * Extracción experimental de datos * Extracciones simples de pares clave-valor planos donde luego no se aplican estrictamente los tipos de datos exactos ### Definido por esquema (`schema`) Pasa un objeto JSON Schema que cumpla con la especificación de esquema OpenAPI 3.1 / OAS 3.0. La canalización de extracción garantiza que la respuesta coincida con los tipos definidos, las estructuras anidadas y los campos requeridos. ```json { "url": "https://example.com/product/10928", "output": ["json"], "json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "price": { "type": "number", "description": "The final discounted price shown to the user, excluding tax." }, "currency": { "type": "string" }, "in_stock": { "type": "boolean" }, "categories": { "type": "array", "items": { "type": "string" } } }, "required": ["title", "price", "currency", "in_stock"] } } } ``` #### Cuándo usar: * Canalizaciones de producción * Bases de datos de ingesta automatizada * Aplicaciones fuertemente tipadas en las que la ausencia de datos o tipos de datos inesperados puede causar errores ## Patrones comunes de esquema ### 1. Filas y listas repetidas Extrae resultados de búsqueda, tablas o listados de productos envolviendo un objeto de fila en un arreglo: ```json { "url": "https://example.com/search?q=laptop", "output": ["json"], "json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price": { "type": "number" }, "rating": { "type": "number", "nullable": true }, "url": { "type": "string", "description": "Absolute URL to the product detail page" } }, "required": ["name", "price", "url"] } } }, "required": ["products"] } } } ``` ### 2. Enum estandarizado y registros anidados Mapea textos distintos de sitios web diferentes a vocabularios internos fijos usando `enum`: ```json { "url": "https://example.com/product/123", "output": ["json"], "json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "availability": { "type": "string", "enum": ["in_stock", "out_of_stock", "preorder", "discontinued"], "description": "Map the page wording to one of these standardized state strings" }, "seller": { "type": "object", "properties": { "name": { "type": "string" }, "rating": { "type": "number", "nullable": true } }, "required": ["name"] } }, "required": ["title", "availability"] } } } ``` Por ejemplo, `enum` es lo que hace que el campo sea comparable entre sitios: "In stock", "Available now" y "Ships today" todos terminan en `in_stock`, así que el código posterior se ramifica sobre un solo valor en lugar de una gran cantidad de coincidencias de cadenas. ### 3. Metadatos de artículos y blogs Extrae metadatos de publicación para almacenamiento estructurado en bases de datos: ```json { "url": "https://example.com/blog/article", "output": ["json"], "json": { "schema": { "type": "object", "properties": { "headline": { "type": "string" }, "author": { "type": "string", "nullable": true }, "published_at": { "type": "string", "description": "Publication date formatted as an ISO 8601 string (YYYY-MM-DD)" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": ["headline", "published_at"] } } } ``` ## Extracción localizada `ubicación` se aplica directamente a las extracciones con IA. Pasa códigos de país ISO 3166-1 alpha-2 para asegurar que los precios y monedas localizados se extraigan correctamente: ```bash curl https://webapi.oxylabs.io/v1/scrape \ -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "url": "https://sandbox.oxylabs.io/products/1", "output": ["json"], "location": "DE", "json": { "schema": { "type": "object", "properties": { "price": { "type": "number" }, "currency": { "type": "string" } }, "required": ["price", "currency"] } } }' ``` {% hint style="info" %} Sin `ubicación`, la `moneda` que recibes es la que la página decidió mostrar. {% endhint %} ## Esquema de respuesta El JSON extraído se devuelve dentro de la envoltura estándar bajo `results[].json`: {% code expandable="true" %} ```json { "state": "done", "results": [ { "json": { "currency": "€", "price": 91.99 }, "metadata": { "page": 1, "run_js": false, "url": "https://sandbox.oxylabs.io/products/1", "statuses": { "http_request": { "code": 200, "tag": "HTTP_OK" }, "json_parse": { "code": 12000, "tag": "PARSE_SUCCESS" } } } } ], "params": { "url": "https://sandbox.oxylabs.io/products/1", "output": [ "json" ], "json": { "schema": { "properties": { "currency": { "type": "string" }, "price": { "type": "number" } }, "required": [ "price", "currency" ], "type": "object" }, "prompt": null }, "location": "DE", "device": "desktop", "run_js": null }, "metadata": { "timestamp": 1790854381, "request_id": "7511387695155825665" } } ``` {% endcode %} {% hint style="info" %} Solicitud `output` el parámetro es una lista. Puedes solicitar `output: ["json", "markdown"]` en una sola solicitud para recibir tanto los campos extraídos como el texto completo. Las claves de formato no solicitadas devuelven `null`. {% endhint %} ### Ejemplos de código {% tabs %} {% tab title="Python (basado en esquema)" %} ```python import os import json import requests API_URL = "https://webapi.oxylabs.io/v1/scrape" HEADERS = { "Authorization": f"Bearer {os.environ['OXYLABS_WEB_API_KEY']}", "Content-Type": "application/json" } extraction_schema = { "type": "object", "properties": { "headline": {"type": "string"}, "author": {"type": "string", "nullable": True}, "publish_date": { "type": "string", "description": "ISO 8601 formatted publication date string (YYYY-MM-DD)." }, "word_count": {"type": "integer"} }, "required": ["headline", "publish_date"] } payload = { "url": "https://example.com/blog/article-1", "output": ["json"], "json": { "schema": extraction_schema } } response = requests.post(API_URL, headers=HEADERS, json=payload, timeout=120) response.raise_for_status() parsed_data = response.json()["results"][0]["json"] print(json.dumps(parsed_data, indent=2)) ``` {% endtab %} {% tab title="Node.js (basado en prompt)" %} ```javascript const API_URL = "https://webapi.oxylabs.io/v1/scrape"; const HEADERS = { "Authorization": `Bearer ${process.env.OXYLABS_WEB_API_KEY}`, "Content-Type": "application/json" }; const payload = { url: "https://example.com/product/10928", output: ["json"], json: { prompt: "Extract product title, rating out of 5 stars, review count, and primary features." } }; async function executeAiExtraction() { const response = await fetch(API_URL, { method: "POST", headers: HEADERS, body: JSON.stringify(payload) }); if (!response.ok) { throw new Error(`HTTP Error ${response.status}: ${await response.text()}`); } const data = await response.json(); const extractedJson = data.results[0].json; console.log("Extracted Data:", JSON.stringify(extractedJson, null, 2)); } executeAiExtraction(); ``` {% endtab %} {% endtabs %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developers.oxylabs.io/products/es/api-web/scrape/analisis-con-ia.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.