# Primeros pasos

## Cómo usar el Analizador Personalizado <a href="#how-to-use-custom-parser" id="how-to-use-custom-parser"></a>

### Ejemplo de escenario

Supongamos que desea extraer **el número de resultados totales** que Bing Search arroja con un término de búsqueda `test`:

<figure><img src="https://338917265-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FPrxIqONdWJuGVRNOZnTk%2Fcustom_parser_bing.png?alt=media&#x26;token=0a9be806-d7f5-40ae-b80c-0f11871f9996" alt=""><figcaption></figcaption></figure>

Revisaremos los tres métodos principales para lograr este objetivo:

* [Generar analizadores con OxyCopilot](#generate-parsers-with-oxycopilot)
* [Generar analizadores mediante API](#generate-parsers-via-api)
* [Escribir instrucciones de análisis manualmente](#write-instructions-manually)

### Generar analizadores con OxyCopilot

OxyCopilot le permite describir sus necesidades en inglés sencillo para **crear automáticamente scrapers y analizadores** para un sitio web. Aprenda lo básico siguiendo los pasos a continuación y consulte [documentación de OxyCopilot](https://developers.oxylabs.io/documentation/es/soluciones-de-scraping/web-scraper-api-playground/oxycopilot#custom-parser-builder) para más información.

{% hint style="success" %}
Abra el [**Web Scraper API Playground**](https://dashboard.oxylabs.io/en/api-playground) en nuestro panel para acceder a OxyCopilot.
{% endhint %}

{% stepper %}
{% step %}

#### Ingrese la(s) URL(s)

Haga clic en el **botón OxyCopilot** en la parte superior izquierda e ingrese hasta 3 URLs del mismo tipo de página. Usemos esta URL de Bing Search: `https://www.bing.com/search?q=test`.

<figure><img src="https://338917265-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FmJqGOdCEMSZRc8qRwIfk%2FCS-OxyCopilot-1.png?alt=media&#x26;token=860755f5-84a7-4e7a-8354-160e94b192aa" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
También puede configurar el scraper manualmente completando los **Sitio web**, **campos Scraper**, y **URL** en la parte superior y ajustando **parámetros adicionales** como el renderizado de JavaScript en el menú lateral izquierdo.
{% endhint %}
{% endstep %}

{% step %}

#### Configurar parámetros del scraper

A continuación, especifique los parámetros del scraper, las instrucciones del navegador y habilite el renderizado de JavaScript si su sitio objetivo lo requiere.

Para Bing Search, **habilite el renderizado de JavaScript** y luego haga clic **Siguiente**.

<figure><img src="https://338917265-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FVi2jUZZp7kD3dAnGwwCR%2FCS-OxyCopilot-2.png?alt=media&#x26;token=4e793d18-f3ea-4ea5-b612-09596eee61c5" alt="" width="375"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Escribir el prompt

Explique los datos que desea extraer de una página. Asegúrese de ser descriptivo y proporcionar la información más importante. Puede encontrar ejemplos de prompts para sitios populares en nuestra [biblioteca de prompts de OxyCopilot](https://oxylabs.io/resources/prompts-code-samples).

Pegue el siguiente prompt para extraer el número total de resultados de las páginas de Bing Search:

```
Extraer el número total de resultados de búsqueda.
```

<figure><img src="https://338917265-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FLMI159k2LpJPzpfJ9LK3%2FCS-OxyCopilot-3.png?alt=media&#x26;token=795ae14c-e276-4362-9158-6660c965d44a" alt="" width="563"><figcaption></figcaption></figure>

Haga clic en el **Generar instrucciones** botón para enviar su prompt.
{% endstep %}

{% step %}

#### Revisar datos e instrucciones parseadas

Una vez que OxyCopilot termine, verá la siguiente ventana donde los datos parseados están en el lado derecho:

<figure><img src="https://338917265-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2Femo5HJUYdI6yNkecQiZP%2FCS-OxyCopilot-4.png?alt=media&#x26;token=e0e12895-5a88-4c91-a0bc-0e9d88b30270" alt=""><figcaption></figcaption></figure>

Si desea hacer ajustes, puede hacerlo aquí. Modifique la(s) URL(s), refine el prompt, habilite el renderizado de Javascript o [editar el esquema de análisis](https://developers.oxylabs.io/documentation/es/soluciones-de-scraping/web-scraper-api-playground/oxycopilot#step-2-optional-adjust-parsing-schema) para adaptarlo a sus necesidades. Cuando actualice cualquier campo en esta ventana, puede volver a ejecutar la solicitud seleccionando **Iniciar nueva solicitud**.

También puede **ver y editar directamente las instrucciones de análisis** aquí:

<figure><img src="https://338917265-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FylhQnnMEzPbCX0jqxLWA%2FCS-OxyCopilot-5.png?alt=media&#x26;token=3be22fad-112e-4835-b360-787c36362c5a" alt="" width="373"><figcaption></figcaption></figure>

Una vez que esté satisfecho con el resultado, **Cargar instrucciones** para continuar.
{% endstep %}

{% step %}

#### Guardar el analizador como un preset

Puede guardar fácilmente sus instrucciones de análisis como un [preset del parser](https://developers.oxylabs.io/documentation/es/soluciones-de-scraping/web-scraper-api/features/custom-parser/parser-presets). Esto le permite reutilizar el preset en OxyCopilot y con sus solicitudes API.&#x20;

En el Web Scraper API Playground, opcionalmente puede elegir el usuario para el cual guardar el preset. Una vez listo, simplemente haga clic en **Guardar**:

<figure><img src="https://338917265-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2F7OOEZBc2SMe4AeLv8uZQ%2FCS-OxyCopilot-6.png?alt=media&#x26;token=2a1bf65b-9660-415e-9bb2-01a60962b1cb" alt=""><figcaption></figcaption></figure>

Aparecerá un pop-up solicitándole que nombre el preset y agregue una descripción opcional:

<figure><img src="https://338917265-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FrvVBSfKFMvVkEaoub5Sv%2FCS-OxyCopilot-7.png?alt=media&#x26;token=246ff512-7e3d-4b06-bf0b-7cc41e7cb42c" alt="" width="375"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Usar el preset con solicitudes API

Para usar un preset con sus solicitudes Web Scraper API, establezca `parse` to `true` y especifique el nombre del preset con el `parser_preset` hará que Google cargue más aplicaciones. Este parámetro solo es útil si se usa junto con el

**Endpoint:** `POST https://data.oxylabs.io/v1/queries`

```json
{
    "source": "bing_search",
    "query": "test",
    "render": "html",
    "parse": true,
    "parser_preset": "Bing_total_results"
}
```

Ejecutar la solicitud proporcionará la siguiente salida JSON:

```json
{
    "results": [
        {
            salida estructurada
                "parse_status_code": 12000,
                "total_search_results": 12000000
            },
            "created_at": "2025-10-24 09:29:28",
            "updated_at": "2025-10-24 09:30:42",
            "content": {
            "url": "https://www.bing.com/search?q=test",
            "job_id": "7387419953164488705",
            "is_render_forced": false,
            "status_code": 200,
            "type": "parsed",
            "parser_type": "preset",
            "parser_preset": "Bing_total_results"
        }
    ]
}
```

{% endstep %}
{% endstepper %}

## Uso avanzado

### Generar analizadores mediante API

En lugar de usar OxyCopilot en el playground, puede enviar prompts directamente a Web Scraper API y generar analizadores. Vea la página de [Generación de instrucciones de análisis mediante API](https://developers.oxylabs.io/documentation/es/soluciones-de-scraping/web-scraper-api/features/custom-parser/generating-parsing-instructions-via-api) de documentación para obtener más información.

{% hint style="success" %}
Recomendamos **proporcionar 3-5 URLs del mismo tipo** (p. ej., páginas de producto). Esto ayuda al analizador a adaptarse a diferentes diseños y mejora la precisión del análisis.
{% endhint %}

**Endpoint:** `POST https://data.oxylabs.io/v1/parsers/generate-instructions/prompt`

```json
{
    "prompt_text": "Extraer el número total de resultados de búsqueda.",
    "urls": ["https://www.bing.com/search?q=test"],
    "render": true
}
```

<details>

<summary>Salida</summary>

```json
{
    "parsing_instructions": {
        "total_search_results": {
            "_fns": [
                {
                    "_args": [
                        "//span[contains(@class, 'count')]/text()"
                    ],
                    "_fn": "xpath_one"
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        }
    },
    "prompt_schema": {
        "properties": {
            "total_search_results": {
                "description": "El número total de resultados de búsqueda.",
                "title": "Resultados Totales de Búsqueda",
                "type": "number"
            }
        },
        "required": [
            "total_search_results"
        ],
        "title": "Campos",
        "type": "object"
    }
}
```

</details>

### Guardar presets de analizadores vía API

Web Scraper API le permite guardar instrucciones de análisis como presets de analizadores reutilizables. Consulte la [documentación de Parser Presets](https://developers.oxylabs.io/documentation/es/soluciones-de-scraping/web-scraper-api/features/custom-parser/parser-presets) para encontrar una lista de acciones disponibles y ejemplos de código completos.

**Endpoint:** `POST https://data.oxylabs.io/v1/parsers/presets`

```json
{
    "name": "Bing_total_results",
    "parsing_instructions": {
        "total_search_results": {
            "_fns": [
                {
                    "_fn": "xpath_one",
                    "_args": [
                        "//span[contains(@class, 'count')]/text()"
                    ]
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        }
    }
}
```

<details>

<summary>Salida</summary>

```json
{
    "id": 421938,
    "name": "Bing_total_results",
    "description": null,
    "prompt_text": null,
    "prompt_schema": null,
    "urls": [],
    "render": false,
    "parsing_instructions": {
        "total_search_results": {
            "_fns": [
                {
                    "_args": [
                        "//span[contains(@class, 'count')]/text()"
                    ],
                    "_fn": "xpath_one"
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        }
    },
    "self_heal": false,
    "heal_status": "disabled",
    "last_healed_at": null,
    "created_at": "2025-10-27 09:28:37",
    "updated_at": "2025-10-27 09:28:37"
}
```

</details>

### Escribir instrucciones manualmente

Para usar Custom Parser manualmente, incluya un conjunto de `parsing_instructions` al crear un job. Puede usar **selectores CSS y XPath** para apuntar a elementos en el DOM.

Siga el ejemplo paso a paso a continuación para aprender lo básico, luego explore nuestra guía detallada sobre [escribir instrucciones manualmente](https://developers.oxylabs.io/documentation/es/soluciones-de-scraping/web-scraper-api/features/custom-parser/writing-instructions-manually) para técnicas avanzadas y documentación detallada.

Tomemos el escenario de Bing Search como ejemplo. Los parámetros del job se verían de la siguiente manera:

```json
{
    "source": "bing_search",
    "query": "test",
    "render": "html",
    "parse": true,
    "parsing_instructions": {
        "number_of_results": {
            "_fns": [
                {
                    "_fn": "xpath_one",
                    "_args": [".//span[@class='sb_count']/text()"]
                }
            ]
        }
    }
}
```

**Paso 1.** Debe proporcionar el `"parse": true` hará que Google cargue más aplicaciones. Este parámetro solo es útil si se usa junto con el

**Paso 2.** Las instrucciones de análisis deben describirse en el `"parsing_instructions"` campo.

Las instrucciones de ejemplo anteriores especifican que el objetivo es extraer el número de resultados de búsqueda del documento scrapeado y colocar el resultado en el `number_of_results` campo. Las instrucciones sobre cómo analizar el campo definiendo una “pipeline” se dan como:

```json
"_fns": [
    {
        "_fn": "xpath_one",
        "_args": [".//span[@class='sb_count']/text()"]
    }
]
```

La pipeline describe una lista de funciones de procesamiento de datos que se ejecutarán. Las funciones se ejecutan en el orden en que aparecen en la lista y toman la salida de la función anterior como entrada.&#x20;

En la pipeline de ejemplo anterior, la `xpath_one` función ([**lista completa de funciones disponibles**](https://developers.oxylabs.io/documentation/es/soluciones-de-scraping/web-scraper-api/features/custom-parser/writing-instructions-manually/list-of-functions)) se utiliza. Le permite procesar un documento HTML usando expresiones XPath y funciones XSLT. Como argumento de la función, especifique la ruta exacta donde se puede encontrar el elemento objetivo: `.//span[@class='sb_count']`. También puede indicar al analizador que seleccione el `text()` encontrado en el elemento objetivo.

El resultado parseado del job de ejemplo anterior debería verse así:

```json
{
    "results": [
        {
            salida estructurada
                "number_of_results": "About 16,700,000 results",
                "parse_status_code": 12000
            },
            "created_at": "2025-10-27 09:48:04",
            "updated_at": "2025-10-27 09:48:38",
            "content": {
            "url": "https://www.bing.com/search?q=test",
            "job_id": "7388511797231226881",
            "is_render_forced": false,
            "status_code": 200,
            "type": "parsed",
            "parser_type": "custom",
            "parser_preset": null
        }
    ]
}
```

Custom Parser no solo ofrece extracción de texto desde un HTML scrapeado, sino que también puede ejecutar funciones básicas de procesamiento de datos.&#x20;

Por ejemplo, las instrucciones de análisis descritas previamente extraen `number_of_results` como un texto con palabras clave adicionales que puede que no necesite necesariamente. Si desea obtener el número de resultados para la `query=test` dado en el tipo de dato numérico, puede reutilizar las mismas instrucciones de análisis y agregar la `amount_from_string` función a la pipeline existente:

```json
{
    "source": "bing_search",
    "query": "test",
    "render": "html",
    "parse": true,
    "parsing_instructions": {
        "number_of_results": {
            "_fns": [
                {
                    "_fn": "xpath_one",
                    "_args": [".//span[@class='sb_count']/text()"]
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        }
    }
}
```

El resultado parseado del job de ejemplo anterior debería verse así:

```json
{
    "results": [
        {
            salida estructurada
                "number_of_results": 14200000,
                "parse_status_code": 12000
            },
            "created_at": "2025-10-27 10:00:36",
            "updated_at": "2025-10-27 10:01:05",
            "content": {
            "url": "https://www.bing.com/search?q=test",
            "job_id": "7388514950961963009",
            "is_render_forced": false,
            "status_code": 200,
            "type": "parsed",
            "parser_type": "custom",
            "parser_preset": null
        }
    ]
}
```

## Qué sucede si el análisis falla al usar Custom Parser <a href="#what-happens-if-parsing-fails-when-using-custom-parser" id="what-happens-if-parsing-fails-when-using-custom-parser"></a>

Si Custom Parser no puede procesar las instrucciones de análisis definidas por el cliente, devolveremos el `12005` código de estado (parseado con advertencias).

```json
{
    "source": "bing_search",
    "query": "test",
    "render": "html",
    "parse": true,
    "parsing_instructions": {
        "number_of_results": {
            "_fns": [
                {
                    "_fn": "xpath_one",
                    "_args": [".//span[@class='sb_count']/text()"]
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        },
        "number_of_organics": {
            "_fns": [
                {
                    "_fn": "xpath",
                    "_args": ["//this-will-not-match-anything"]
                },
                {
                    "_fn": "length"
                }
            ]
        }
    }
}
```

Se le cobrará por tales resultados:

```json
{
    "results": [
        {
            salida estructurada
                "_warnings": [
                    {
                        "_fn": "xpath",
                        "_msg": "Las expresiones XPath no coincidieron con ningún dato.",
                        "_path": ".number_of_organics",
                        "_fn_idx": 0
                    }
                ],
                "number_of_results": 14200000,
                "parse_status_code": 12005,
                "number_of_organics": null
            },
            "created_at": "2025-10-27 10:03:54",
            "updated_at": "2025-10-27 10:04:22",
            "content": {
            "url": "https://www.bing.com/search?q=test",
            "job_id": "7388515782126234625",
            "is_render_forced": false,
            "status_code": 200,
            "type": "parsed",
            "parser_type": "custom",
            "parser_preset": null
        }
    ]
}
```

Si Custom Parser encuentra una excepción y se detiene durante la operación de análisis, puede devolver estos códigos de estado: `12002`, `12006`, `12007`. No se le cobrará por estos errores inesperados.

## Códigos de estado <a href="#status-codes" id="status-codes"></a>

Consulte nuestros códigos de estado descritos [**aquí**](https://developers.oxylabs.io/documentation/es/soluciones-de-scraping/response-codes#parsers).