# Primeros pasos ## Cómo usar Custom Parser ### Ejemplo de escenario Supongamos que quieres analizar el **número total de resultados** que devuelve Bing Search con un término de búsqueda `test`:
Veremos de forma general 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 te permite describir tus necesidades en inglés sencillo para **crear automáticamente scrapers y analizadores** para un sitio web. Aprende lo básico siguiendo los pasos que se indican a continuación y consulta [la documentación de OxyCopilot](/products/es/web-scraper-api/web-scraper-api-playground/oxycopilot.md#custom-parser-builder) para más información. {% hint style="success" %} Abra la ventana de [**Web Scraper API Playground**](https://dashboard.oxylabs.io/en/api-playground) en nuestro panel para acceder a OxyCopilot. {% endhint %} {% stepper %} {% step %} #### Introduce la(s) URL(s) Haz clic en el **botón de OxyCopilot** en la parte superior izquierda e introduce hasta 3 URL del mismo tipo de página. Usemos esta URL de Bing Search: `https://www.bing.com/search?q=test`.
{% hint style="info" %} También puedes configurar el scraper manualmente rellenando los **Sitio web**, **campos de Scraper**, y **URL** en la parte superior, y ajustando **parámetros adicionales** como la renderización de JavaScript en el menú de la izquierda. {% endhint %} {% endstep %} {% step %} #### Configurar los parámetros del scraper A continuación, especifica los parámetros del scraper, las instrucciones del navegador y activa la renderización de JavaScript si tu sitio objetivo lo requiere. Para Bing Search, **activa la renderización de JavaScript** y luego haz clic en **Siguiente**.
{% endstep %} {% step %} #### Escribe el prompt Explica los datos que quieres extraer de una página. Asegúrate de ser descriptivo y proporcionar la información más importante. Puedes encontrar ejemplos de prompts para sitios web populares en nuestra [biblioteca de prompts de OxyCopilot](https://oxylabs.io/resources/prompts-code-samples). Pega el siguiente prompt para extraer el número total de resultados de las páginas de Bing Search: ``` Analiza el número total de resultados de búsqueda. ```
Haz clic en el **Generar instrucciones** botón para enviar tu prompt. {% endstep %} {% step %} #### Revisar los datos analizados y las instrucciones Una vez que OxyCopilot termine, verás la siguiente ventana donde los datos analizados están en el lado derecho:
Si quieres hacer algún ajuste, puedes hacerlo aquí. Modifica la(s) URL, refina el prompt, activa la renderización de JavaScript o [edita el esquema de análisis](/products/es/web-scraper-api/web-scraper-api-playground/oxycopilot.md#step-2-optional-adjust-parsing-schema) para adaptarlo a tus necesidades. Cuando actualices cualquier campo en esta ventana, puedes volver a ejecutar la solicitud seleccionando **Iniciar nueva solicitud**. También puedes **ver y editar directamente las instrucciones de análisis** aquí:
Una vez que estés conforme con el resultado, **Cargar instrucciones** para continuar. {% endstep %} {% step %} #### Guardar el analizador como un preset Puedes guardar fácilmente tus instrucciones de análisis como un [preseteo del analizador](/products/es/web-scraper-api/features/custom-parser/parser-presets.md). Esto te permite reutilizar el preset en OxyCopilot y con tus solicitudes de API. En el Web Scraper API Playground, opcionalmente puedes elegir el usuario para el que guardar el preset. Una vez que esté todo listo, simplemente haz clic en **Guardar**:
Aparecerá una ventana emergente pidiéndote que nombres el preset y añadas una descripción opcional:
{% endstep %} {% step %} #### Usar el preset con solicitudes de API Para usar un preset con tus solicitudes de Web Scraper API, configura `parse` a `true` y especifica el nombre del preset con el `parser_preset` parámetro. **Endpoint:** `POST https://data.oxylabs.io/v1/queries` ```json { "source": "bing_search", "query": "test", "render": "html", "parse": true, "parser_preset": "Bing_total_results" } ``` Al ejecutar la solicitud se obtendrá la siguiente salida JSON: ```json { "results": [ { "content": { "parse_status_code": 12000, "total_search_results": 12000000 }, "created_at": "2025-10-24 09:29:28", "updated_at": "2025-10-24 09:30:42", "page": 1, "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, puedes enviar prompts directamente a Web Scraper API y generar analizadores. Consulta la [documentación sobre generación de instrucciones de análisis mediante API](/products/es/web-scraper-api/features/custom-parser/generating-parsing-instructions-via-api.md) para aprender más. {% hint style="success" %} Recomendamos **proporcionar 3-5 URL del mismo tipo** (por ejemplo, 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": "Analiza el número total de resultados de búsqueda.", "urls": ["https://www.bing.com/search?q=test"], "render": true } ```
Salida ```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" } } ```
### Guardar presets del analizador mediante API Web Scraper API te permite guardar instrucciones de análisis como presets reutilizables. Consulta la [Presets de analizador](/products/es/web-scraper-api/features/custom-parser/parser-presets.md) documentación 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" } ] } } } ```
Salida ```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" } ```
### Escribir instrucciones manualmente Para usar Custom Parser manualmente, incluye un conjunto de `parsing_instructions` al crear un trabajo. Puedes usar **selectores CSS y XPath** para apuntar a elementos en el DOM. Sigue el ejemplo paso a paso a continuación para aprender lo básico, y luego explora nuestra guía detallada sobre [escribir instrucciones manualmente](/products/es/web-scraper-api/features/custom-parser/writing-instructions-manually.md) para técnicas avanzadas y documentación detallada. Tomemos el escenario de Bing Search como ejemplo. Los parámetros del trabajo se verían así: ```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.** Debes proporcionar el `"parse": true` parámetro. **Paso 2.** Las instrucciones de análisis deben describirse en `"parsing_instructions"` . Las instrucciones de análisis de ejemplo anteriores especifican que el objetivo es analizar el número de resultados de búsqueda del documento extraído y poner el resultado en el campo `number_of_results` . 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. En la pipeline de ejemplo anterior, se usa la función `xpath_one` ([lista completa de funciones disponibles](/products/es/web-scraper-api/features/custom-parser/writing-instructions-manually/list-of-functions.md)). Permite procesar un documento HTML usando expresiones XPath y funciones XSLT. Como argumento de la función, especifica la ruta exacta donde se puede encontrar el elemento objetivo: `.//span[@class='sb_count']`. También puedes indicar al analizador que seleccione el `text()` encontrado en el elemento objetivo. El resultado analizado del trabajo de ejemplo anterior debería verse así: ```json { "results": [ { "content": { "number_of_results": "Aproximadamente 16,700,000 resultados", "parse_status_code": 12000 }, "created_at": "2025-10-27 09:48:04", "updated_at": "2025-10-27 09:48:38", "page": 1, "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 de un HTML extraído, sino que también puede ejecutar funciones básicas de procesamiento de datos. Por ejemplo, las instrucciones de análisis descritas anteriormente extraen `number_of_results` como texto con palabras clave adicionales que quizá no necesites necesariamente. Si quieres obtener el número de resultados para la `query=test` en el tipo de dato numérico, puedes reutilizar las mismas instrucciones de análisis y añadir la `amount_from_string` función al 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 analizado del trabajo de ejemplo anterior debería verse así: ```json { "results": [ { "content": { "number_of_results": 14200000, "parse_status_code": 12000 }, "created_at": "2025-10-27 10:00:36", "updated_at": "2025-10-27 10:01:05", "page": 1, "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é ocurre si falla el análisis al usar Custom Parser Si Custom Parser no puede procesar las instrucciones de análisis definidas por el cliente, devolveremos el `12005` código de estado (analizado 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 te cobrará por tales resultados: ```json { "results": [ { "content": { "_warnings": [ { "_fn": "xpath", "_msg": "XPath expressions did not match any data.", "_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", "page": 1, "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 falla durante la operación de análisis, puede devolver estos códigos de estado: `12002`, `12006`, `12007`. No se te cobrará por estos errores inesperados. ## Códigos de estado Consulta nuestros códigos de estado descritos [**aquí**](/products/es/web-scraper-api/response-codes.md#parsers). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.oxylabs.io/products/es/web-scraper-api/features/custom-parser/getting-started.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.