Saltar al contenido
Empezar gratis
Volver al blog

Guía rápida de selectores CSS para el web scraping: sintaxis y código

Ștefan RăcilăÚltima actualización el 28 min read
Guía rápida de selectores CSS para el web scraping: sintaxis y código

Los selectores CSS son patrones que seleccionan elementos de un documento HTML, y los rastreadores los utilizan para señalar el texto o atributo exacto que desean extraer. Cinco selectores se encargan de la mayor parte del trabajo: .class, [attribute], los combinadores de descendientes e hijos (un espacio y >), :nth-child(), y :has(). Esta hoja de referencia de selectores CSS los abarca todos ellos y el resto de la sintaxis estándar, cada uno acompañado de un ejemplo de scraping. También encontrarás una matriz que indica qué selectores funcionan en los navegadores, BeautifulSoup, Scrapy, Cheerio, Playwright y selectolax; la misma extracción escrita en cuatro pilas; recetas para patrones de página comunes; y una tabla de soluciones para los selectores que devuelven resultados vacíos.

Puntos clave

  • La mayoría de las tareas de scraping solo necesitan clases, atributos, el espacio y > combinadores, :nth-child(), y :has().
  • :has() selecciona a los padres. Los navegadores modernos y los principales analizadores de scraping lo admiten.
  • El CSS estándar no permite seleccionar texto ni valores de atributos. ::text, ::attr(), y :-soup-contains() son extensiones de la biblioteca, no CSS.
  • Anclaje en data-* atributos y clases semánticas, no en clases generadas mediante hash ni en largas cadenas copiadas.
  • Si un selector funciona en DevTools pero no en tu rastreador, es probable que el contenido se genere mediante JavaScript.

¿Qué son los selectores CSS en el scraping web?

Los selectores CSS identifican elementos por etiqueta, clase, ID, atributo, posición o relación con otros elementos. Los navegadores los utilizan para aplicar estilos. Los rastreadores utilizan la misma sintaxis para encontrar los elementos que contienen datos y, a continuación, leen el texto o los atributos de cada elemento en campos como nombre, precio y URL.

Una página HTML se analiza en forma de árbol: cada etiqueta es un nodo con un padre, hermanos e hijos. Un selector describe una ruta o una condición en ese árbol, y el analizador devuelve todos los nodos que se ajustan a ella.

Casi todos los rastreadores siguen estos cuatro pasos:

  1. Recuperar la página con un cliente HTTP o un navegador.
  2. Analizar el HTML para convertirlo en un árbol.
  3. Seleccionar los nodos de interés mediante selectores CSS.
  4. Extraer el texto o los valores de los atributos y guardarlos como registros.

La diferencia clave está en el primer paso. Un cliente HTTP como requests, el fetcho el descargador de Scrapy, recibe el HTML sin procesar que envía el servidor, y analizadores como BeautifulSoup, Parsel y Cheerio trabajan con él. Un navegador ejecuta primero el JavaScript de la página, por lo que los selectores ven el DOM renderizado, que puede incluir contenido que nunca aparece en la respuesta sin procesar. Eso es lo que ocurre cuando una página se renderiza en un navegador sin interfaz gráfica, como Playwright, o mediante una API de renderizado. La sintaxis de tu selector sigue siendo la misma a ambos lados de la bifurcación. Sin embargo, el árbol sobre el que se ejecuta puede ser muy diferente, y esa diferencia provoca la mayoría de los errores del tipo «mi selector no devuelve nada».

Todos los ejemplos de esta página se ejecutan sobre un pequeño listado de productos, para que puedas comparar los códigos línea por línea:

<main id="catalog">
  <div class="product card" data-sku="A1" data-testid="product">
    <h2 class="title">Blue Mug</h2>
    <span class="price">$12.00</span>
    <span class="badge sale">Sale</span>
    <a class="link" href="/p/blue-mug">View</a>
    <img src="/img/a1.jpg" alt="Blue Mug">
  </div>
  <div class="product card" data-sku="b2" data-testid="product">
    <h2 class="title">Red Mug</h2>
    <span class="price">$14.00</span>
    <a class="link" href="/p/red-mug">View</a>
    <a class="spec" href="/files/red-mug.pdf">Spec sheet</a>
    <img src="/img/blank.gif" data-src="/img/b2.jpg" alt="Red Mug">
  </div>
  <div class="product card out-of-stock" data-sku="C3" data-testid="product">
    <h2 class="title">Green Mug</h2>
    <span class="price">$9.00</span>
    <p class="note">Out of stock</p>
    <a class="link" href="/p/green-mug">View</a>
  </div>
  <table class="specs">
    <tr><th>Name</th><th>Value</th></tr>
    <tr><td>Weight</td><td>300 g</td></tr>
    <tr><td>Color</td><td>Blue</td></tr>
  </table>
  <dl class="details">
    <dt>Material</dt><dd>Stoneware</dd>
    <dt>Capacity</dt><dd>350 ml</dd>
  </dl>
  <ul class="pager">
    <li><a href="?page=1">1</a></li>
    <li class="active"><a href="?page=2">2</a></li>
    <li><a href="?page=3">3</a></li>
  </ul>
  <a rel="next" href="?page=3">Next</a>
</main>

Hoja de referencia de selectores CSS

Las tablas siguientes enumeran todos los selectores estándar relevantes para el scraping, agrupados por tipo, con lo que cada uno coincide y un ejemplo basado en el listado de productos anterior. Las extensiones exclusivas de bibliotecas, como ::text tienen su propia tabla, ya que dejan de funcionar en cuanto se cambia de biblioteca. Para consultar el estándar completo, véase la referencia de selectores CSS de MDN.

Selectores básicos

Selector

Coincide con

Ejemplo de extracción de datos

*

Cada elemento

.product > * enumera todos los hijos directos de una tarjeta cuando estás mapeando un diseño desconocido

tag

Elementos con ese nombre de etiqueta

h2 devuelve los tres títulos de productos

.class

Los elementos que tienen esa clase

.price devuelve los tres precios

.a.b

Elementos que tienen ambas clases

.product.card devuelve las tres fichas

#id

El elemento con ese ID

#catalog limita todo al listado

tag.class

Esa etiqueta con esa clase

div.product omite cualquier elemento que no seadiv que reutilice la clase

Un espacio cambia completamente el significado. .product.card (sin espacio) significa un elemento con ambas clases. .product .card (con un espacio) significa un .card en algún lugar dentro de un .product, y en esta página no coincide con nada. Ese único espacio es el primer error más habitual en un nuevo rastreador.

Utiliza identificadores (ID) para valores únicos, como el encabezado de una página o un contenedor. Los elementos repetidos, como las fichas de productos o las filas de resultados, casi nunca tienen identificadores, así que selecciónalos por clase o por atributo.

Selectores de atributos

Selector

Coincide con

Ejemplo de scraping

[attr]

El atributo está presente

[data-sku] devuelve todas las tarjetas que tienen un SKU

[attr="v"]

El valor es exactamente v

[data-sku="A1"] devuelve una ficha

[attr~="v"]

v es una palabra en una lista separada por espacios

[class~="sale"] coincide class="badge sale" pero no presale

[attr|="v"]

El valor es v o empieza por v-

[lang|="en"] coincide en y en-US

[attr^="v"]

El valor empieza por v

a[href^="/p/"] solo muestra enlaces a productos

[attr$="v"]

El valor termina en v

a[href$=".pdf"] muestra la ficha técnica

[attr*="v"]

El valor contiene v en cualquier parte

a[href*="mug"] muestra todos los enlaces a tazas

[attr="v" i]

Coincidencia exacta, sin tener en cuenta las mayúsculas y minúsculas en ASCII

[data-sku="a1" i] coincide data-sku="A1"

Pon entre comillas cualquier valor que contenga espacios, barras, puntos u otros caracteres especiales. a[href$=".pdf"] es seguro, pero a[href$=.pdf] supone un error de sintaxis en la mayoría de los analizadores sintácticos.

Los selectores de atributos suelen ser los ganchos más estables de una página. data-* atributos, itemprop, aria-labely rel existen porque el propio código del sitio o las herramientas de accesibilidad dependen de ellos. Por eso suelen sobrevivir a los rediseños en los que se renombran las clases visuales.

Combinadores

Selector

Coincidencias

Ejemplo de extracción

A B

B en cualquier lugar dentro de A

#catalog .price devuelve todos los precios del anuncio

A > B

B que sea un elemento secundario directo de A

.product > .title omite los títulos anidados a mayor profundidad

A + B

B inmediatamente después de A, mismo padre

.title + .price devuelve el precio que sigue a cada título

A ~ B

Cualquier B después de A, el mismo elemento principal

.title ~ a devuelve todos los enlaces que aparecen después del título en cada ficha

A, B

Elementos que coincidan con cualquiera de los selectores

.title, .price devuelve los títulos y los precios juntos

Los resultados agrupados se muestran en el orden del documento, no en el orden en que has enumerado los selectores. .title, .price Te muestra nombre, precio, nombre, precio, y así sucesivamente, tanto en navegadores como en BeautifulSoup y Cheerio.

CSS no tiene combinador de padre ni combinador de hermano anterior. No necesitas ninguno de los dos, porque :has() cubre ambos casos, tal y como muestra la sección de lógica que aparece a continuación.

Pseudoclases de posición

Selector

Coincide con

Ejemplo de extracción

:first-child

El primer elemento hijo de su elemento padre

div.product:first-child devuelve la primera tarjeta

:last-child

El último elemento secundario de su elemento principal

.pager li:last-child a devuelve el enlace a la última página

:nth-child(n)

El enésimo elemento secundario (contando a partir de 1)

div.product:nth-child(2) .title devuelve «Taza roja»

:nth-child(odd) / (even)

Cada dos hijos

tr:nth-child(even) para las tablas a rayas

:nth-child(n+2)

Cada elemento secundario a partir del segundo

tr:nth-child(n+2) se salta una fila de encabezado

:nth-last-child(n)

El enésimo elemento, contando desde el final

li:nth-last-child(1) devuelve el último elemento del paginador

:only-child

Un elemento sin hermanos

td:only-child busca filas con una sola celda

:first-of-type

El primer elemento hermano con su etiqueta

span:first-of-type devuelve el precio de cada tarjeta

:last-of-type

El último elemento hermano con su etiqueta

div.product:last-of-type devuelve la última ficha

:nth-of-type(n)

El enésimo elemento del mismo nivel con su etiqueta

span:nth-of-type(2) devuelve la insignia de rebajas

:only-of-type

El único elemento del mismo nivel con su etiqueta

h2:only-of-type devuelve un título por cada tarjeta

La An+B fórmula que hay dentro :nth-child() cuenta a partir de 1, n tomando los valores 0, 1, 2, y así sucesivamente. n+2 por lo tanto, significa las posiciones 2, 3, 4 y siguientes, que es la forma de omitir la fila de encabezado de una tabla. -n+3 significa las posiciones 3, 2 y 1, por lo que selecciona los tres primeros elementos. 2n es lo mismo que even, y 2n+1 es lo mismo que odd. Se ignora cualquier coincidencia que se salga del número real de elementos hijos.

:nth-child() y :nth-of-type() parecen iguales, pero se cuentan de forma diferente. En la primera tarjeta, los hijos son h2, span.price, span.badge, a, y img. span:nth-child(2) devuelve el precio, ya que el precio es el segundo hijo en total. span:nth-of-type(2) devuelve la insignia de rebajas, porque la insignia es el segundo span.

En Scrapy y Parsel, las *-of-type pseudoclases necesitan un nombre de elemento. div.product:nth-of-type(2) funciona, pero .product:nth-of-type(2) genera un ExpressionError. Los navegadores, BeautifulSoup y Cheerio aceptan ambas formas.

Pseudoclases lógicas: :not(), :is(), :where() y :has()

Selector

Coincide con

Ejemplo de extracción de datos

:not(x)

Elementos que no coinciden x

div.product:not(.out-of-stock) devuelve las dos cartas disponibles

:is(x, y)

Elementos que coinciden con cualquier selector de la lista

:is(h2, h3).title gestiona plantillas que mezclan niveles de encabezado

:where(x, y)

Igual que :is(), con especificidad cero

Intercambiable con :is() para el scraping

:has(x)

Los elementos que contengan una coincidencia con x

div.product:has(.badge) devuelve la tarjeta en oferta

:has(> x)

Elementos con un elemento secundario directo que coincida con x

div.product:has(> .note) devuelve la ficha «agotado»

:has(+ x)

Elementos seguidos inmediatamente por x

dt:has(+ dd) devuelven cada etiqueta que tenga un valor

:has() es el selector de elementos padres del que carecía el CSS durante años. Busca un elemento en función de lo que hay dentro de él o de lo que viene justo después, lo que cubre ambas direcciones que suele necesitar un rastreador. .product:has(.badge) devuelve las tarjetas que contienen una insignia de rebajas, no las insignias en sí mismas. tr:has(td.out-of-stock) devuelve filas completas de la tabla que contengan una celda «agotado». dt:has(+ dd) devuelve una etiqueta solo cuando va seguida de un valor, que es la forma de acceder a un elemento hermano anterior. Combínalo con :not() para invertir la condición: .product:not(:has(.badge)) devuelve tarjetas sin insignia. La especificación «Selectors Level 4» lo define, y :has() en MDN lo clasifica como «Baseline» (ampliamente disponible) en todos los navegadores desde diciembre de 2023. BeautifulSoup, Scrapy, Cheerio, Playwright y selectolax también lo admiten. Se aplica una limitación: no se puede anidar :has() dentro de otro :has().

:is() y :where() solo se diferencian en la especificidad, que determina qué estilo prevalece en una hoja de estilo. La especificidad no afecta a lo que selecciona un rastreador, así que utiliza el que te resulte más claro.

Extensiones exclusivas de las bibliotecas

El CSS estándar selecciona elementos, nunca su texto ni los valores de sus atributos. Cada biblioteca de scraping cubre esa laguna a su manera, y las extensiones que se indican a continuación son las que hacen que tu código deje de ser portátil.

Extensión

Biblioteca

Qué hace

::text

Scrapy, Parsel

Selecciona los nodos de texto del elemento coincidente

::attr(name)

Scrapy, Parsel

Selecciona el valor de un atributo

:-soup-contains("x")

BeautifulSoup (a través de Soup Sieve)

Busca elementos cuyo texto, incluidos los descendientes, contenga x

:-soup-contains-own("x")

BeautifulSoup (a través de Soup Sieve)

Busca elementos cuyo propio texto, no el de los descendientes, contenga x

:contains("x")

Cheerio, Parsel (a través de cssselect)

Busca elementos cuyo texto contenga x

:has-text("x")

Solo localizadores de Playwright

Coincide con elementos que contengan x en cualquier parte de su contenido, sin distinguir entre mayúsculas y minúsculas

:text("x")

Solo localizadores de Playwright

Coincide con el elemento más pequeño que contenga x

:visible

Solo localizadores de Playwright

Coincide únicamente con elementos que sean visibles en la página

Ninguna de estas opciones forma parte del CSS estándar. El método document.querySelectorAll() lanza un SyntaxError excepción :contains(), y BeautifulSoup genera un error si se le pasa ::text. En BeautifulSoup, :contains() sigue funcionando como alias, pero está obsoleto y se recomienda utilizar :-soup-contains(). Soup Sieve, el motor de selección de BeautifulSoup, documenta su conjunto completo de extensiones.

Lo que los selectores CSS no pueden hacer

El CSS es un lenguaje de coincidencia, por lo que hay algunas tareas que quedan fuera de su ámbito:

  • Seleccionar un nodo de texto o el valor de un atributo por sí solo. Primero se selecciona el elemento y, a continuación, se lee su texto o atributo en el código.
  • Realizar coincidencias por contenido de texto en CSS estándar. Solo las extensiones de la biblioteca mencionadas anteriormente permiten hacerlo.
  • Subir un número fijo de antepasados, como «el abuelo de este span». :has() Selecciona por contención, no por distancia.
  • Comparar valores o realizar operaciones matemáticas, como «precio mayor que 10».
  • Acceder a un iframe, que es un documento independiente.

Cuando te encuentres con uno de estos límites, consulta la hoja de referencia de XPath para el scraping web o realiza el paso en el código tras la selección.

¿Qué selectores CSS funcionan en cada biblioteca de extracción de datos?

Los selectores estándar, incluidos los operadores de atributos, :nth-child(), :not(), :is(), y :has(), se comportan de la misma manera en los navegadores modernos, BeautifulSoup, Scrapy, Cheerio, Playwright y selectolax. Las diferencias radican en las extensiones y los casos extremos: Scrapy y Parsel necesitan un nombre de etiqueta para *-of-type, BeautifulSoup rechaza ::text, y cada biblioteca realiza la coincidencia de texto a su manera.

Característica

Navegador (querySelectorAll)

BeautifulSoup

Scrapy / Parsel

Cheerio

Playwright

selectolax

Los operadores de atributos y la i indicador

Sí

Sí

Sí

Sí

Sí

Sí

Combinadores (espacio, >, +, ~, ,)

Sí

Sí

Sí

Sí

Sí

Sí

An+B (:nth-child(n+2))

Sí

Sí

Sí

Sí

Sí

Sí

*-of-type sin etiqueta (.product:nth-of-type(2))

Sí

Sí

Error

Sí

Sí

Sí

*-of-type con una etiqueta (div.product:nth-of-type(2))

Sí

Sí

Sí

Sí

Sí

Sí

:not()

Sí

Sí

Sí

Sí

Sí

Sí

:is() y :where()

Sí

Sí

Sí

Sí

Sí

Sí

:has() y :has(> x)

Sí

Sí

Sí

Sí

Sí

Sí

:scope

Sí

Sí

Sí

Sí

Sí

Error

::text y ::attr()

Error

Error

Extensión

Error

Error

Error

Coincidencia de texto

No (:contains() lanza)

Extensión (:-soup-contains())

Extensión (:contains())

Extensión (:contains())

Extensión (:has-text(), :text())

Extensión (:lexbor-contains())

DOM de sombra abierto

No

No

No

No

Sí (CSS atraviesa las raíces de Shadow abiertas)

No

Actualizado a noviembre de 2026.

Las dos filas son la causa de la mayoría de los errores de migración. Cuando trasladas un selector desde la consola del navegador a Scrapy y este incluye .something:nth-of-type(), añade el nombre de la etiqueta. Cuando traslades un selector de Scrapy a BeautifulSoup, elimina ::text y ::attr() y lee el texto o el atributo en Python en su lugar.

La fila sobre el DOM de sombra requiere una aclaración. Los analizadores de HTML sin procesar nunca detectan las raíces de sombra añadidas por JavaScript, ya que estas no existen en la respuesta del servidor. Solo un navegador puede acceder a ellas, y solo el motor CSS de Playwright atraviesa las raíces de sombra de forma predeterminada.

Los rastreadores de PHP siguen las mismas reglas a través del componente CssSelector de Symfony. Este convierte los selectores CSS a XPath antes de ejecutarlos, por lo que también se aplican las limitaciones de esa conversión.

¿Cómo se encuentra y se prueba un selector CSS?

Inspecciona el elemento, toma nota de su etiqueta, sus clases y sus atributos de datos, busca un contenedor estable uno o dos niveles más arriba y escribe un selector breve que sea único dentro de ese contenedor. A continuación, pruébalo con Ctrl+F en el panel «Elementos» o document.querySelectorAll() en la Consola, y comprueba que el número de coincidencias sea el esperado.

  1. Inspeccionar. Haz clic con el botón derecho del ratón en el valor que desees y selecciona «Inspeccionar». El panel «Elementos» resaltará su nodo.
  2. Lee los enlaces. Busca data-* atributos, id, nombres de clases semánticas como price o title, itemprop, y aria-* atributos. Estos son los elementos que menos probabilidades tienen de cambiar.
  3. Busca el contenedor que se repite. En el caso de las listas, recorre la lista hacia arriba hasta llegar al elemento que se repite una vez por elemento, como div.product.
  4. Escribe el selector más corto que sea único dentro del contenedor. div.product .price Es mejor que recorrer todos los contenedores envolventes.
  5. Pruébalo. Pulsa Ctrl+F (Cmd+F en macOS) en el panel «Elementos» y pega el selector. DevTools muestra el número de coincidencias. También puedes ejecutarlo en la consola:

``js $$("div.product .price").length // 3 ``

  1. Compáralo con «Ver código fuente». Abre «Ver código fuente» (Ctrl+U) y busca el valor. Si no está ahí, el contenido se genera mediante JavaScript y un cliente HTTP no lo verá.

Todos los navegadores principales permiten copiar un selector generado desde el panel «Elementos». Haz clic con el botón derecho del ratón en el nodo y abre el submenú «Copiar»:

Navegador

Elemento del menú

Chrome y Edge

Copiar > Copiar selector

Firefox

Copiar > Selector CSS

Safari

Copiar > Ruta del selector

La guía del DOM de Chrome DevTools trata el panel «Elementos» con mayor detalle.

Cómo simplificar un selector copiado

Un selector copiado describe exactamente esta página y nada más. Una copia típica del precio de la segunda tarjeta tiene este aspecto:

/* Copied from DevTools */
#catalog > div:nth-child(2) > span

/* Rewrite 1: one card, by a stable attribute */
[data-sku="b2"] .price

/* Rewrite 2: every card */
div.product .price

La versión copiada depende de la posición de la tarjeta y de que el precio sea el único span en esa tarjeta. Si añades una tarjeta patrocinada en la parte superior, devuelve el precio del producto equivocado. Si pones una insignia de oferta en esta tarjeta, devuelve dos valores en lugar de uno. La reescritura 1 sustituye la posición por el propio SKU del producto y sustituye el span por su clase semántica. La reescritura 2 elimina por completo la condición de «una sola tarjeta», ya que un rastreador suele querer todos los precios, no solo el segundo. Cada capa que eliminas es una cosa menos que tiene que permanecer igual.

Selectores robustos frente a frágiles

Frágiles

Robustos

¿Por qué?

.css-1x9k2ab

[data-testid="product"]

Las herramientas de compilación regeneran los nombres de clase con hash en cada implementación, mientras que los ID de prueba se mantienen porque las propias pruebas del sitio dependen de ellos

main > div:nth-child(3) > div:nth-child(2) > span

.product .price

Una ruta de posición completa deja de funcionar cuando se añade o se elimina cualquier envoltorio

.text-red.font-bold

.price

Las clases de presentación cambian con un rediseño, mientras que las clases semánticas describen el contenido

div.product:nth-child(2)

[data-sku="b2"]

Las posiciones cambian cuando se ordenan o se insertan elementos, mientras que el identificador de un elemento no cambia

div > div > span

.price

Las cadenas de etiquetas genéricas coinciden en exceso y dependen de un anidamiento exacto

Los selectores robustos se basan en elementos de los que dependen los desarrolladores del sitio: identificadores de prueba, atributos de datos, clases semánticas y marcado de datos estructurados como itemprop.

Cómo extraer datos con selectores CSS en Python y JavaScript

Todas las bibliotecas aceptan la misma cadena de selector, pero cada una devuelve resultados de forma diferente: select() y select_one() en BeautifulSoup, response.css() con ::text y ::attr() en Scrapy, $() en Cheerio, y page.locator() en Playwright. El patrón es el mismo en todos los casos: primero se selecciona cada elemento repetido y, a continuación, se leen los campos que contiene.

Cada uno de los ejemplos que aparecen a continuación extrae el nombre, el precio y la URL absoluta de las tres fichas del listado.

BeautifulSoup

from urllib.parse import urljoin
import requests
from bs4 import BeautifulSoup

URL = "https://shop.example.com/mugs?page=2"
soup = BeautifulSoup(requests.get(URL, timeout=10).text, "lxml")

for card in soup.select("div.product"):
    title = card.select_one(".title")
    price = card.select_one(".price")
    link = card.select_one("a.link")
    print({
        "name": title.get_text(strip=True) if title else None,
        "price": price.get_text(strip=True) if price else None,
        "url": urljoin(URL, link.get("href")) if link else None,
    })
# {'name': 'Blue Mug', 'price': '$12.00', 'url': 'https://shop.example.com/p/blue-mug'}
# {'name': 'Red Mug', 'price': '$14.00', 'url': 'https://shop.example.com/p/red-mug'}
# {'name': 'Green Mug', 'price': '$9.00', 'url': 'https://shop.example.com/p/green-mug'}
  • select() devuelve una lista, y select_one() devuelve la primera coincidencia o None. Protege cada select_one() antes de llamar a un método sobre ella.
  • tag["href"] lanza un KeyError cuando falta el atributo, mientras que tag.get("href") devuelve None.
  • ::text lanza un error. Utiliza get_text(strip=True) en su lugar, y :-soup-contains("Out of stock") cuando necesites realizar una coincidencia por texto.
  • El analizador es importante en casos de HTML defectuoso. lxml y html.parser puede generar árboles diferentes a partir del mismo código malformado, así que elige uno y quédate con él.

Para ir más allá, crea un rastreador con BeautifulSoup desde cero o lee la documentación de BeautifulSoup para conocer la select() API.

Scrapy y Parsel

import scrapy

class MugSpider(scrapy.Spider):
    name = "mugs"
    start_urls = ["https://shop.example.com/mugs?page=2"]

    def parse(self, response):
        for card in response.css("div.product"):
            yield {
                "name": card.css(".title::text").get(default="").strip(),
                "price": card.css(".price::text").get(default="").strip(),
                "url": response.urljoin(card.css("a.link::attr(href)").get()),
            }
        # {'name': 'Blue Mug', 'price': '$12.00', 'url': 'https://shop.example.com/p/blue-mug'}
        # {'name': 'Red Mug', 'price': '$14.00', 'url': 'https://shop.example.com/p/red-mug'}
        # {'name': 'Green Mug', 'price': '$9.00', 'url': 'https://shop.example.com/p/green-mug'}
        next_page = response.css('a[rel="next"]::attr(href)').get()
        if next_page:
            yield response.follow(next_page, callback=self.parse)

Esta hoja de referencia de selectores CSS de Scrapy recoge las llamadas que más utilizarás:

Sintaxis

Devuelve

Ejemplo en el listado

::text

Los nodos de texto propios del elemento

.title::text devuelve «Blue Mug»

::text (espacio inicial)

Los nodos de texto del elemento y de todos sus descendientes

.product ::text devuelve todos los nodos de texto de la ficha

::attr(name)

El valor de un atributo

a.link::attr(href) devuelve «/p/blue-mug»

.get()

El primer resultado, o None

card.css(".price::text").get()

.getall()

Todos los resultados en forma de lista

response.css(".title::text").getall()

.get(default="")

El primer resultado, o el valor por defecto

Evita None las comprobaciones antes de .strip()

.attrib["href"]

Un atributo del primer elemento coincidente

card.css("a.link").attrib["href"]

  • *-of-type necesita un nombre de etiqueta. Escribe div.product:nth-of-type(2), no .product:nth-of-type(2).
  • a::text y a ::text son diferentes. El primero devuelve solo los nodos de texto propios del enlace. El segundo también devuelve el texto que hay dentro de etiquetas anidadas como <a><span>View</span></a>.
  • El texto se devuelve sin formato, incluyendo saltos de línea y sangrías, así que elimínalos.

Los selectores de Scrapy provienen de Parsel, por lo que las mismas .css() funcionan parsel.Selector(text=html) fuera de una araña. Consulta la documentación sobre selectores de Scrapy para conocer las reglas de extensión, o sigue la guía completa de scraping de Scrapy para el rastreo, los flujos de trabajo y la configuración.

Cheerio

import * as cheerio from "cheerio";

const URL = "https://shop.example.com/mugs?page=2";
const $ = cheerio.load(await (await fetch(URL)).text());

const products = $("div.product").map((i, el) => {
  const card = $(el);
  return {
    name: card.find(".title").text().trim(),
    price: card.find(".price").text().trim(),
    url: new URL(card.find("a.link").attr("href"), URL).href,
  };
}).get();
console.log(products);
// [ { name: 'Blue Mug', price: '$12.00', url: 'https://shop.example.com/p/blue-mug' },
//   { name: 'Red Mug', price: '$14.00', url: 'https://shop.example.com/p/red-mug' },
//   { name: 'Green Mug', price: '$9.00', url: 'https://shop.example.com/p/green-mug' } ]
  • Cheerio solo analiza HTML sin formato. No ejecuta JavaScript, por lo que cualquier elemento que un script añada tras la carga no aparecerá.
  • .text() En una selección con varios elementos, se une todo su texto, así que limita la selección a una sola tarjeta .find() antes de leerla.
  • .attr("href") devuelve undefined cuando falta el atributo.
  • :contains() funciona en Cheerio, pero genera un error en los navegadores, por lo que es posible que un selector que prototipes aquí no se pueda pegar de nuevo en la consola.

Para ver un proyecto completo, consulta «Extracción de datos web con Cheerio en Node.js».

Playwright

import { chromium } from "playwright";

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto("https://shop.example.com/mugs?page=2");
await page.locator("div.product").first().waitFor();

const names = await page.locator("div.product .title").allInnerTexts();
// [ 'Blue Mug', 'Red Mug', 'Green Mug' ]
const products = await page.$$eval("div.product", cards =>
  cards.map(card => ({
    name: card.querySelector(".title")?.innerText.trim() ?? null,
    price: card.querySelector(".price")?.innerText.trim() ?? null,
    url: card.querySelector("a.link")?.href ?? null,
  }))
);
// [ { name: 'Blue Mug', price: '$12.00', url: 'https://shop.example.com/p/blue-mug' }, ... ]
await browser.close();
  • Métodos de localización como allInnerTexts() y count() no esperan a que aparezcan los elementos, y $$eval() se ejecutan una sola vez sobre el DOM actual. Espera primero a que aparezca el contenedor, como se ha indicado anteriormente.
  • Dentro de $$eval(), la href propiedad devuelve una URL absoluta, mientras que getAttribute("href") devuelve el valor sin procesar.
  • Playwright añade sus propias pseudoclases CSS: div.product:has-text("Out of stock"), :text(), y :visible. Su CSS también traspasa las raíces de sombra abiertas. Nada de esto funciona fuera de Playwright.

La propia documentación de Playwright recomienda localizadores visibles para el usuario, como getByRole() y getByTestId() en lugar de CSS para clics y entradas en formularios, ya que CSS vincula una prueba a la implementación de la página. Para leer contenedores de datos repetidos, el CSS sigue siendo la opción más práctica, ya que una cuadrícula de productos no tiene un rol accesible que separe el precio del título. La documentación sobre localizadores CSS de Playwright enumera todas las extensiones, y la guía de extracción de datos web de Playwright abarca la navegación, la espera y el escalado.

Selenium

Selenium toma el CSS estándar a través de By.CSS_SELECTOR y lo ejecuta en un navegador real, de modo que ve el DOM renderizado y sigue la columna del navegador de la matriz. find_elements() devuelve una lista, que está vacía cuando no hay coincidencias, mientras que find_element() lanza NoSuchElementException. get_attribute("href") devuelve la URL absoluta resuelta.

from selenium.webdriver.common.by import By

titles = driver.find_elements(By.CSS_SELECTOR, "div.product .title")
links = driver.find_elements(By.CSS_SELECTOR, "div.product a.link")
print([t.text for t in titles])                     # ['Blue Mug', 'Red Mug', 'Green Mug']
print([a.get_attribute("href") for a in links])     # ['https://shop.example.com/p/blue-mug', ...]

Recetas de selectores CSS para tareas habituales de scraping

La mayoría de los trabajos de scraping repiten unos cuantos patrones: fichas de productos, enlaces y paginación, imágenes, tablas y pares de etiquetas y valores. Cada receta que aparece a continuación ofrece un selector y una o dos líneas de código de extracción, utilizando primero CSS estándar para que el selector funcione en cualquier biblioteca.

Fichas de productos y listados

Selecciona primero la ficha y, a continuación, lee los campos que contiene. De esta forma, si falta el precio en una ficha, los precios posteriores no se desplazarán a un registro incorrecto. Filtra a nivel de selector siempre que sea posible: div.product:not(.out-of-stock) devuelve solo los artículos en stock, y div.product:has(.badge) marca los artículos en oferta sin necesidad de una segunda pasada.

in_stock = [c.select_one(".title").get_text(strip=True)
            for c in soup.select("div.product:not(.out-of-stock)")]
# ['Blue Mug', 'Red Mug']
on_sale = [t.get_text(strip=True) for t in soup.select("div.product:has(.badge) .title")]
# ['Blue Mug']

Este patrón de «primero la ficha, luego el campo» es la clave para realizar un seguimiento a gran escala de los precios de la competencia, donde una página de listados se convierte en docenas de filas bien estructuradas.

Enlaces y paginación

Busca a[rel="next"] primero. rel="next" es un tipo de enlace HTML estándar que utilizan muchos sitios web y suele ser el punto de referencia de paginación más estable de la página. Cuando un sitio no lo marca, sal de la página activa con el combinador «next-sibling»: .pager li.active + li a. Los enlaces «href» suelen ser relativos, así que resuélvelos en función de la URL de la página antes de solicitarlos.

next_href = response.css('a[rel="next"]::attr(href)').get()
# '?page=3'
next_url = response.urljoin(response.css(".pager li.active + li a::attr(href)").get())
# 'https://shop.example.com/mugs?page=3'

Imágenes y fuentes con carga diferida

Las páginas con carga diferida suelen colocar un marcador de posición en src y la imagen real en data-src, que un script sustituye al desplazarse por la página. Un analizador de HTML sin procesar solo ve el marcador de posición, así que lee data-src primero y recurre a src. Las imágenes adaptativas también pueden enumerar varios tamaños en srcset, o envolverlos en picture source , así que comprueba ambos cuando necesites el archivo más grande.

const images = $("div.product img").map((i, el) => $(el).attr("data-src") ?? $(el).attr("src")).get();
// [ '/img/a1.jpg', '/img/b2.jpg' ]

Utiliza img[data-src] para encontrar solo las imágenes diferidas, y img:not([data-src]) para el resto.

Las tablas HTML

:nth-child() se encarga de la mayor parte del trabajo con tablas. tr:nth-child(n+2) omite la fila de encabezado, y td:nth-child(2) selecciona la segunda columna. Sin embargo, las posiciones de las columnas cambian con más frecuencia que las etiquetas de los encabezados. Para cualquier tarea que vaya más allá de un trabajo rápido, lee la fila de encabezado una vez y asigna cada celda a su nombre de encabezado.

values = [td.get_text(strip=True)
          for td in soup.select("table.specs tr:nth-child(n+2) td:nth-child(2)")]
# ['300 g', 'Blue']
headers = [th.get_text(strip=True) for th in soup.select("table.specs tr:first-child th")]
rows = [dict(zip(headers, [td.get_text(strip=True) for td in tr.select("td")]))
        for tr in soup.select("table.specs tr:has(td)")]
# [{'Name': 'Weight', 'Value': '300 g'}, {'Name': 'Color', 'Value': 'Blue'}]

Pares de etiqueta y valor

Las listas de definiciones y los bloques de especificaciones emparejan una etiqueta con el valor que le sigue. dt + dd devuelve cada valor, y dt:has(+ dd) devuelve cada etiqueta que realmente tenga un valor. Léelas en paralelo e incorpóralas a un diccionario. Las tablas con una th etiqueta y un elemento adyacente td funcionan de la misma manera con th + td.

labels = response.css("dl.details dt:has(+ dd)::text").getall()   # ['Material', 'Capacity']
values = response.css("dl.details dt + dd::text").getall()        # ['Stoneware', '350 ml']
specs = dict(zip(labels, values))

Cuando necesites «el valor cuya etiqueta diga Capacidad», eso es una coincidencia de texto. El CSS estándar no puede hacerlo, así que utiliza dt:-soup-contains("Capacity") + dd en BeautifulSoup, o una expresión XPath que funcione en cualquier sitio.

¿Por qué mi selector CSS no devuelve nada?

Normalmente, porque el HTML que ha recibido tu rastreador no es la página que has inspeccionado. DevTools muestra el DOM tras la ejecución de JavaScript, mientras que un cliente HTTP obtiene la respuesta sin procesar del servidor. Otras causas habituales son los iframes, el shadow DOM, los nombres de clase con hash de compilación, los caracteres especiales sin escapar y un espacio entre dos clases que deberían estar unidas.

Síntoma

Causa probable

Solución

Funciona en DevTools, pero queda vacío en el rastreador

El contenido se representa mediante JavaScript

Comprueba «Ver código fuente». Busca la solicitud JSON o XHR que realiza la página, o visualiza la página en un navegador.

Vacío solo en algunas páginas o en algunos países

Una variante diferente de la página, una pantalla de consentimiento o una página de verificación

Registra el código de estado y guarda el cuerpo de la respuesta para ver qué has recibido realmente

.product .card No devuelve nada

Un espacio convirtió «ambas clases» en «descendiente»

Une las clases: .product.card

Un ID con dos puntos o un dígito inicial da error

Caracteres especiales sin escapar

Escápalos (#a\:b) o utiliza un selector de atributos ([id="123"])

El elemento está dentro de un iframe

El iframe es un documento independiente

Solicita directamente la src directamente, o utiliza la función de Playwright frameLocator()

El elemento se encuentra dentro de un componente web

Se encuentra en una raíz oculta

El CSS de Playwright atraviesa las raíces de sombra. Los analizadores de HTML sin procesar no pueden acceder a ellas.

Texto de ::before o ::after falta

El contenido del pseudoelemento no está en el DOM

Busca el valor en un atributo o en la hoja de estilos, o omítelo

Los valores contienen espacios en blanco no deseados o están divididos

Los nodos de texto sin formato incluyen sangrías y saltos de línea

Elimina el texto o utiliza get_text(strip=True)

Un valor coincide en un caso pero no en otro

La coincidencia de atributos distingue entre mayúsculas y minúsculas

Añade el indicador i indicador: [data-sku="a1" i]

Scrapy genera un ExpressionError en *-of-type

Parsel necesita un nombre de elemento

Añade la etiqueta: div.product:nth-of-type(2)

Cuando la corrección se está representando, no tienes que ejecutar tú mismo una flota de navegadores. La API del navegador puede representar la página y esperar a tu selector con wait_for_css, para luego devolver el HTML o los campos extraídos. Funciona como una solicitud y una respuesta: envías la URL y las instrucciones, y recibes el resultado. No se trata de una sesión de navegador en tiempo real que controles paso a paso.

Selectores CSS frente a XPath: ¿cuándo debes cambiar?

Utiliza selectores CSS por defecto. Son más cortos, más fáciles de leer y compatibles con todas las bibliotecas de scraping y todos los navegadores. Cambia a XPath cuando necesites una coincidencia de texto portátil, un antepasado específico, lógica de posición en todo el documento o documentos XML. La mayoría de los scrapers en producción combinan ambos.

  • Coincidencia de texto: el XPath contains(text(), "Capacity") funciona en todos los motores de XPath. La coincidencia de texto con CSS depende de la biblioteca.
  • Antepasados: XPath puede ascender un número exacto de niveles con .. o el ancestor:: eje. :has() Selecciona por contención, no por distancia.
  • Posición en todo el documento: (//div[@class="product"])[2] se cuenta en toda la página, no entre elementos hermanos.
  • XML: Las fuentes y los mapas de sitio con espacios de nombres son más fáciles de manejar en XPath.

Tarea

CSS

XPath

Título de la segunda ficha

div.product:nth-child(2) .title

(//div[contains(@class, "product")])[2]//h2

Valor tras la etiqueta «Capacidad»

dt:-soup-contains("Capacity") + dd (solo BeautifulSoup)

//dt[text()="Capacity"]/following-sibling::dd[1]

Para conocer las ventajas e inconvenientes con más detalle, lee la comparación completa entre los selectores XPath y CSS.

¿Cómo se ejecutan los selectores CSS a través de una API?

Envía tus selectores junto con la solicitud y obtén campos JSON en lugar de HTML sin procesar. La API Scraper de WebScrapingAPI acepta un extract_rules objeto que asigna nombres de campos a selectores CSS o XPath. Los ejecuta en la página obtenida, con renderización de JavaScript cuando lo solicitas, y devuelve texto, HTML, valores de atributos o datos de tablas.

Esto resulta útil cuando lo complicado es la obtención de datos, no la selección. Si un sitio bloquea tus solicitudes, renderiza su contenido con JavaScript o muestra resultados diferentes según el país, puedes conservar los selectores que ya has escrito y trasladar la obtención de datos a las reglas de extracción de la API Scraper.

Cada regla asocia una clave de salida a una cadena de selector o a un objeto de regla con estas claves:

  • selector: un selector CSS o una expresión XPath.
  • selector_type: css o xpath. Si no se especifica, un selector que comience por / se interpreta como XPath, y cualquier otra cosa como CSS.
  • output: text por defecto, o html, @attr (como @href), table_json, table_array, o un objeto de regla anidado.
  • all: 1 devuelve todas las coincidencias, y 0 devuelve solo la primera.
  • clean: 1 elimina los espacios en blanco iniciales y finales, así como los saltos de línea, del texto.

extract_rules Se envía como un objeto JSON convertido a cadena, así que codifícalo para URL:

curl --get "https://api.webscrapingapi.com/v2" \
  --data-urlencode "api_key=$WSA_API_KEY" \
  --data-urlencode "url=https://shop.example.com/mugs?page=2" \
  --data-urlencode 'extract_rules={"titles":{"selector":"div.product .title","output":"text","all":1}}'

Una regla anidada selecciona cada tarjeta y, a continuación, los campos que contiene, siguiendo el mismo patrón que el código de cuatro pilas anterior:

import json, os, requests

rules = {
    "products": {
        "selector": "div.product",
        "all": 1,
        "output": {
            "name": {"selector": ".title", "output": "text", "clean": 1},
            "price": {"selector": ".price", "output": "text", "clean": 1},
            "url": {"selector": "a.link", "output": "@href"},
        },
    }
}
response = requests.get("https://api.webscrapingapi.com/v2", params={
    "api_key": os.environ["WSA_API_KEY"],
    "url": "https://shop.example.com/mugs?page=2",
    "render_js": 1,
    "extract_rules": json.dumps(rules),
}, timeout=60)
print(response.json()["products"])

Utiliza CSS estándar en tus reglas y deja que output se encargue del texto y los atributos. Las extensiones de la biblioteca como ::text o :-soup-contains() pertenecen a sus propias bibliotecas. La API ejecuta las reglas que envías. Tú sigues siendo responsable de los selectores, el esquema de salida y la validación que comprueba que cada campo sea correcto, y actualizas las reglas cuando cambia el marcado del sitio.

FAQ

¿Cuáles son los selectores CSS más útiles para el web scraping?

Los selectores de clase y los selectores de atributos, como [data-id] y a[href^="/product"], los combinadores de descendientes e hijos, :nth-child() para tablas y listas, y :has() para seleccionar contenedores en función de su contenido. En conjunto, cubren la mayoría de las tareas de extracción. Las extensiones de las bibliotecas gestionan los valores de texto y de atributos.

¿Cómo puedo obtener texto o un atributo con un selector CSS?

El CSS estándar selecciona elementos, no su texto ni sus atributos, por lo que cada biblioteca añade un paso adicional. En Scrapy, utiliza ::text o ::attr(href). En BeautifulSoup, llama a get_text() o lee tag["href"]. En Cheerio, utiliza .text() y .attr(). En Playwright, utiliza innerText() o getAttribute().

¿Pueden los selectores CSS seleccionar un elemento padre?

Sí. La :has() pseudoclase selecciona un elemento por lo que contiene, por lo que .card:has(.sale) devuelve las tarjetas que contienen una insignia de rebajas, y :has(> .sale) lo limita a los hijos directos. Los navegadores modernos, BeautifulSoup, Scrapy y Cheerio lo admiten. Utiliza XPath para ascender un número exacto de niveles.

¿Pueden los selectores CSS encontrar elementos por su texto?

No en CSS estándar. Las bibliotecas añaden sus propias extensiones: :-soup-contains() en BeautifulSoup, :contains() en Cheerio y en Parsel de Scrapy, y :has-text() en Playwright. No son portables y los navegadores los rechazan. Para una coincidencia de texto que funcione en todas las herramientas, utiliza XPath con contains(text(), "…").

¿Cuál es la diferencia entre «nth-child» y «nth-of-type»?

:nth-child(2) busca un elemento que sea el segundo hijo de su padre, sea cual sea su etiqueta. :nth-of-type(2) busca el segundo elemento hermano con la misma etiqueta dentro de ese elemento padre. En Scrapy y Parsel, las *-of-type pseudoclases necesitan un nombre de etiqueta, así que escribe div.item:nth-of-type(2), no .item:nth-of-type(2).

¿Por qué mi selector CSS funciona en DevTools pero no en mi rastreador?

DevTools muestra la página después de que se haya ejecutado JavaScript, pero un cliente HTTP recibe el HTML sin procesar que envía el servidor. Si la opción «Ver código fuente» no contiene el texto que buscas, el contenido se ha renderizado en el lado del cliente. Busca la solicitud JSON subyacente, renderiza la página en un navegador sin interfaz gráfica o utiliza una API que la renderice antes de extraerla.

¿Debería usar selectores CSS o XPath para el scraping web?

Empieza con los selectores CSS. Son más cortos, más fáciles de leer y son compatibles con todo. Cambia a XPath cuando necesites una coincidencia de texto portátil, un antepasado específico o XML. Muchos rastreadores combinan ambos, y Scrapy y Parsel te permiten utilizar cualquiera de los dos en la misma respuesta.

¿Qué selectores CSS deberías aprender primero?

Empieza por las clases y los atributos para encontrar elementos; después, utiliza el espacio y los > combinadores para delimitar el ámbito a un contenedor. Añade :nth-child() para tablas y listas, y :has() para seleccionar contenedores en función de su contenido. A continuación, aprende cómo lee tu biblioteca el texto y los atributos, ya sea mediante ::text, get_text(), o .text(). Con estos cinco elementos, podrás escribir y corregir casi cualquier selector que necesite un rastreador.

Ejecuta tus selectores sin ejecutar el scraper

Envía una URL y tus selectores CSS a la API de Scraper y obtén campos JSON limpios, con renderización en JavaScript cuando lo necesites. Empieza con 5.000 solicitudes gratuitas. No se cobran créditos adicionales por la renderización en JavaScript ni por la geolocalización, y las solicitudes fallidas no se facturan.

Consulta los precios de Scraper API

Acerca del autor

Ștefan Răcilă, Desarrollador Full Stack @ WebScrapingAPI

Ștefan Răcilă

Desarrollador Full Stack

Stefan Racila es ingeniero de DevOps y Full Stack en WebScrapingAPI, donde se encarga de desarrollar funciones para los productos y de mantener la infraestructura que garantiza la fiabilidad de la plataforma.

Extracción de datos web con AWS Lambda: guía para Python y Java 2026
Guías

Extracción de datos web con AWS Lambda: guía para Python y Java 2026

TL;DR: En resumen: el web scraping con AWS Lambda funciona mejor cuando cada invocación es breve, está delimitada y se puede reintentar de forma independiente. Empieza con HTTP directo, AWS SAM y S3, y añade SQS, contenedores, renderización en navegador, proxies o una capa de recuperación gestionada solo cuando la carga de trabajo demuestre que los necesita.

Suciu Dan33 min read
Leer artículo
Cómo utilizar GoSpider: rastrear, depurar URL y extraer datos
Guías

Cómo utilizar GoSpider: rastrear, depurar URL y extraer datos

TL;DR: En resumen: GoSpider es un rastreador de línea de comandos diseñado para descubrir URL, no un extractor completo de datos estructurados. Esta guía sobre cómo utilizar GoSpider muestra cómo realizar un rastreo limitado, gestionar correctamente los resultados, pasar los datos de Colly a CSV y seguir una ruta de diagnóstico para respuestas 403 o páginas que requieren renderización con JavaScript.

Suciu Dan24 min read
Leer artículo
Cómo raspar Redfin: Guía Python de Datos Inmobiliarios
Guías

Cómo raspar Redfin: Guía Python de Datos Inmobiliarios

TL;DR: Redfin expone puntos finales de API ocultos que devuelven JSON estructurado para los listados de propiedades, lo que permite omitir por completo el frágil análisis HTML. Esta guía te guía a través de la construcción de un raspador de Python que extrae datos de alquiler y venta, busca por ubicación, supervisa los nuevos listados a través de mapas de sitio XML y exporta resultados limpios a CSV o JSON.

Suciu Dan14 min read
Leer artículo

Empieza a crear

¿Estás listo para ampliar tu recopilación de datos?

Únete a más de 2000 empresas que utilizan WebScrapingAPI para extraer datos de la web a escala empresarial sin ningún gasto de infraestructura.