> 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-de-ia.md).

# Análisis de IA

Extrae JSON estructurado de cualquier página en una sola solicitud de Web API, usando un prompt en lenguaje natural o una definición de JSON Schema.

{% hint style="danger" %}
**Cuesta extra:** Usar el análisis con IA en 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 recupera la página web de destino. Combina `output: ["json"]` con el parámetro de nivel raíz `json` para extraer campos personalizados usando indicaciones en lenguaje natural o definiciones estrictas de OpenAPI / JSON Schema.

<table><thead><tr><th width="143">Campo</th><th>Descripción</th><th width="85">Tipo</th></tr></thead><tbody><tr><td><code>json.prompt</code></td><td>Descripción en lenguaje natural de los campos a extraer.</td><td>cadena</td></tr><tr><td><code>json.schema</code></td><td>Un <a href="https://spec.openapis.org/oas/v3.1.0#schema-object">Objeto de esquema OpenAPI</a> a la que el resultado debe ajustarse.</td><td>objeto</td></tr></tbody></table>

{% hint style="success" %}
Use `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 devuelven datos bajo la `json` clave en el `results[]` array:

<table><thead><tr><th width="101">Tipo</th><th>Método</th><th>Destinos</th><th>Usar para</th></tr></thead><tbody><tr><td>Analizador integrado</td><td>Establezca <code>output: ["json"]</code> sin proporcionar una raíz <code>json</code> objeto.</td><td>Destinos dedicados con analizadores preconstruidos (p. ej., <code>/scrape/amazon/product</code>, <code>/scrape/google/search</code>) y selecciona destinos usando <code>/v1/scrape</code> (p. ej., páginas de producto de Bed Bad &#x26; Beyond) </td><td>Esquemas estandarizados de comercio electrónico y SERP mantenidos por Oxylabs.</td></tr><tr><td>Extracción personalizada con IA</td><td>Establezca <code>output: ["json"]</code> y pasa <code>json: { "prompt": ... }</code> o <code>json: { "schema": ... }</code> objeto.</td><td>Cada ruta, incluidas las genéricas <code>/v1/scrape</code> y destinos sin analizadores dedicados.</td><td>Esquemas personalizados, diseños de página únicos o campos no estándar.</td></tr></tbody></table>

{% 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 objeto de `json` extracción, la extracción personalizada con IA anulará 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 objeto raíz `json` acepta una `prompt` cadena o un `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 usarlo

* Prototipado rápido
* Extracción experimental de datos
* Extracciones simples y planas de clave-valor 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 usarlo:&#x20;

* Canalizaciones de producción
* Bases de datos de ingesta automatizada
* Aplicaciones con tipado estricto donde los tipos de datos faltantes o inesperados pueden 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 array:

```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. Enumeraciones estandarizadas y registros anidados

Mapea texto de distintos sitios web a vocabularios internos fijos usando `enumeración`:

```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, `enumeración` es lo que hace que el campo sea comparable entre sitios: "In stock", "Available now" y "Ships today" terminan todos en `in_stock`, así que el código posterior bifurca 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

`location` se aplica directamente a las extracciones de IA. Pasa códigos de país ISO 3166-1 alfa-2 para asegurar que los precios y divisas 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 `location`, el `currency` que obtienes de vuelta es el que la página decidió mostrar.
{% endhint %}

## Esquema de respuesta

El JSON extraído se devuelve dentro del envoltorio 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` 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-de-ia.md?ask=<question>&goal=<user_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.
