Cómo empezar

Aprende a usar el Custom Parser de Oxylabs. En esta página encontrarás ejemplos completos, consejos y detalles sobre qué ocurre si el análisis falla.

Cómo usar Custom Parser

Ejemplo de escenario

Supongamos que quieres extraer el número de resultados totales que Bing Search devuelve con un término de búsqueda test:

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

• Generar parsers con OxyCopilot

• Generar parsers vía API

• Escribir instrucciones de parsing manualmente

Generar parsers con OxyCopilot

OxyCopilot te permite describir tus necesidades en inglés sencillo para crear automáticamente scrapers y parsers para un sitio web. Aprende lo básico siguiendo los pasos descritos a continuación y consulta documentación de OxyCopilot para más información.

Abre el Web Scraper API Playground en nuestro panel para acceder a OxyCopilot.

1

Introduce la(s) URL(s)

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

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 el renderizado de JavaScript en el menú lateral izquierdo.

2

Configurar parámetros del scraper

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

Para Bing Search, habilita el renderizado de JavaScript y luego haz clic Siguiente.

3

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 populares en nuestra biblioteca de prompts de OxyCopilot.

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

Analiza el número de resultados de búsqueda totales.

Haz clic en Generar instrucciones botón para enviar tu prompt.

4

Revisar datos e instrucciones parseadas

Una vez que OxyCopilot termine, verás la siguiente ventana donde los datos parseados aparecen a la derecha:

Si quieres hacer ajustes, puedes hacerlo aquí. Modifica la(s) URL, refina el prompt, habilita el renderizado de Javascript, o edita el esquema de parsing 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 parsing aquí:

Una vez que estés satisfecho con el resultado, Cargar instrucciones para continuar.

5

Guardar el parser como un preset

Puedes guardar fácilmente tus instrucciones de parsing como un parser preset. 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 listo, simplemente haz clic en Save:

Aparecerá un pop-up solicitándote nombrar el preset y agregar una descripción opcional:

6

Usar el preset con solicitudes API

Para usar un preset con tus solicitudes a Web Scraper API, establece parse a true y especifica el nombre del preset con el parser_preset parámetro.

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

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

Ejecutar la solicitud proporcionará la siguiente salida 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"
        }
    ]
}

Uso avanzado

Generar parsers vía API

En lugar de usar OxyCopilot en el playground, puedes enviar prompts directamente a Web Scraper API y generar parsers. Consulta la Generación de instrucciones de parsing vía API página de documentación para aprender más.

Recomendamos proporcionar 3-5 URL del mismo tipo (p. ej., páginas de producto). Esto ayuda al parser a adaptarse a diferentes diseños y mejora la precisión del parsing.

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

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

Salida

{
    "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 de resultados de búsqueda totales.",
                "title": "Resultados de búsqueda totales",
                "type": "number"
            }
        },
        "required": [
            "total_search_results"
        ],
        "title": "Fields",
        "type": "object"
    }
}

Guardar presets de parser vía API

Web Scraper API te permite guardar instrucciones de parsing como presets de parser reutilizables. Consulta la Parser Presets documentación para encontrar una lista de acciones disponibles y ejemplos de código detallados.

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

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

Salida

{
    "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 job. Puedes usar selectores CSS y XPath para dirigirte a elementos en el DOM.

Sigue el ejemplo paso a paso a continuación para aprender lo básico, luego explora nuestra guía detallada sobre escribir instrucciones manualmente 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:

{
    "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 parsing deben describirse en el "parsing_instructions" campo.

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

"_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, la xpath_one función (lista completa de funciones disponibles) se usa. Te 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 instruir al parser para que seleccione el text() encontrado en el elemento objetivo.

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

{
    "results": [
        {
            "content": {
                "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",
            "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 desde un HTML raspado, sino que también puede ejecutar funciones básicas de procesamiento de datos.

Por ejemplo, las instrucciones de parsing descritas anteriormente extraen number_of_results como un texto con palabras clave adicionales que puede que no necesites. 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 parsing y agregar la amount_from_string función a la pipeline existente:

{
    "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í:

{
    "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 el parsing falla al usar Custom Parser

Si Custom Parser no logra procesar las instrucciones de parsing definidas por el cliente, devolveremos el 12005 código de estado (parseado con advertencias).

{
    "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:

{
    "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 se detiene durante la operación de parsing, 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í.