Guía avanzada de scraping

Esta guía te mostrará los distintos endpoints de Firecrawl y cómo aprovecharlos al máximo con todos sus parámetros.

Scraping básico con Firecrawl

Para extraer una sola página y obtener contenido limpio en Markdown, puedes usar el endpoint /scrape.

# pip install firecrawl-py

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

doc = firecrawl.scrape("https://firecrawl.dev")

print(doc.markdown)

Extracción de PDF

Firecrawl admite PDF. Usa la opción parsers (por ejemplo, parsers: ["pdf"]) cuando quieras asegurar el análisis de PDF.

Opciones de extracción

Al usar el endpoint /scrape, puedes personalizar la extracción con las siguientes opciones.

Formatos (`formats`)

Tipo: array
Cadenas: ["markdown", "links", "html", "rawHtml", "summary", "images"]
Formatos de objeto:
- JSON: { type: "json", prompt, schema }
- Captura de pantalla: { type: "screenshot", fullPage?, quality?, viewport? }
- Seguimiento de cambios: { type: "changeTracking", modes?, prompt?, schema?, tag? } (requiere markdown)
Valor predeterminado: ["markdown"]

Contenido completo de la página vs contenido principal (`onlyMainContent`)

Tipo: boolean
Descripción: De forma predeterminada, el scraper devuelve solo el contenido principal. Configúralo en false para devolver el contenido completo de la página.
Predeterminado: true

Incluir etiquetas (`includeTags`)

Tipo: array
Descripción: Etiquetas, clases o IDs de HTML que se incluirán en el scraping.

Excluir etiquetas (`excludeTags`)

Tipo: array
Descripción: Etiquetas/clases/ids HTML que se excluirán del scraping.

Esperar a que la página esté lista (`waitFor`)

Tipo: integer
Descripción: Milisegundos de espera adicional antes de realizar el scraping (usar con moderación). Este tiempo de espera se suma a la función de espera inteligente de Firecrawl.
Valor predeterminado: 0

Actualidad y caché (`maxAge`)

Tipo: integer (milisegundos)
Descripción: Si existe una versión en caché de la página más reciente que maxAge, Firecrawl la devuelve al instante; de lo contrario, vuelve a extraerla y actualiza la caché. Establece 0 para forzar siempre una obtención en vivo.
Predeterminado: 172800000 (2 días)

Tiempo de espera de la solicitud (`timeout`)

Tipo: integer
Descripción: Duración máxima, en milisegundos, antes de cancelar.
Valor predeterminado: 30000 (30 segundos)

Análisis de PDF (`parsers`)

Tipo: array
Descripción: Controla el comportamiento del análisis. Para analizar PDFs, establece parsers: ["pdf"].

Acciones (`actions`)

Cuando utilizas el punto de conexión /scrape, Firecrawl te permite realizar varias acciones en una página web antes de extraer su contenido. Esto es especialmente útil para interactuar con contenido dinámico, navegar entre páginas o acceder a contenido que requiere interacción del usuario.

Tipo: array
Descripción: Secuencia de pasos del navegador que se ejecutan antes del scraping.
Acciones compatibles:
- wait - Esperar a que la página cargue: { type: "wait", milliseconds: number } o { type: "wait", selector: string }
- click - Hacer clic en un elemento: { type: "click", selector: string, all?: boolean }
- write - Escribir texto en un campo: { type: "write", text: string } (el elemento debe estar enfocado primero con un clic)
- press - Pulsar una tecla del teclado: { type: "press", key: string }
- scroll - Desplazar la página: { type: "scroll", direction: "up" | "down", selector?: string }
- screenshot - Tomar una captura de pantalla: { type: "screenshot", fullPage?: boolean, quality?: number, viewport?: { width: number, height: number } }
- scrape - Extraer un subelemento: { type: "scrape" }
- executeJavascript - Ejecutar código JS: { type: "executeJavascript", script: string }
- pdf - Generar un PDF: { type: "pdf", format?: string, landscape?: boolean, scale?: number }

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')

doc = firecrawl.scrape('https://example.com', {
  'actions': [
    { 'type': 'wait', 'milliseconds': 1000 },
    { 'type': 'click', 'selector': '#accept' },
    { 'type': 'scroll', 'direction': 'down' },
    { 'type': 'click', 'selector': '#q' },
    { 'type': 'write', 'text': 'firecrawl' },
    { 'type': 'press', 'key': 'Enter' },
    { 'type': 'wait', 'milliseconds': 2000 }
  ],
  'formats': ['markdown']
})

print(doc.markdown)

Notas sobre la ejecución de acciones

Acción de escritura: Primero debes enfocar el elemento usando una acción de click antes de usar write. El texto se escribe carácter por carácter para simular la entrada por teclado.
Selector de scroll: Si quieres desplazar un elemento específico en lugar de toda la página, pasa el parámetro selector a scroll.
Espera con selector: Puedes esperar a que un elemento específico sea visible usando wait con un parámetro selector, o esperar un tiempo fijo usando milliseconds.
Las acciones son secuenciales: Las acciones se ejecutan en orden y Firecrawl espera a que se completen las interacciones con la página antes de pasar a la siguiente acción.

Ejemplos de acciones avanzadas

Tomar una captura de pantalla:

cURL

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://example.com",
    "actions": [
      { "type": "click", "selector": "#load-more" },
      { "type": "wait", "milliseconds": 1000 },
      { "type": "screenshot", "fullPage": true, "quality": 80 }
    ]
  }'

Clic en varios elementos:

cURL

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://example.com",
    "actions": [
      { "type": "click", "selector": ".expand-button", "all": true },
      { "type": "wait", "milliseconds": 500 }
    ],
    "formats": ["markdown"]
  }'

Generación de un PDF:

cURL

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://example.com",
    "actions": [
      { "type": "pdf", "format": "A4", "landscape": false }
    ]
  }'

Ejemplo de uso

cURL

curl -X POST https://api.firecrawl.dev/v2/scrape \
    -H '
    Content-Type: application/json' \
    -H 'Authorization: Bearer fc-TU-API-KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "formats": [
        "markdown",
        "links",
        "html",
        "rawHtml",
        { "type": "screenshot", "fullPage": true, "quality": 80 }
      ],
      "includeTags": ["h1", "p", "a", ".main-content"],
      "excludeTags": ["#ad", "#footer"],
      "onlyMainContent": false,
      "waitFor": 1000,
      "timeout": 15000,
      "parsers": ["pdf"]
    }'

En este ejemplo, el scraper:

Devuelve el contenido completo de la página en markdown.
Incluye el markdown, el HTML sin procesar, el HTML, los enlaces y una captura de pantalla en la respuesta.
Incluye solo las etiquetas HTML <h1>, <p>, <a> y los elementos con la clase .main-content, excluyendo cualquier elemento con los IDs #ad y #footer.
Espera 1000 milisegundos (1 segundo) antes de realizar el scraping para permitir que la página cargue.
Establece la duración máxima de la solicitud de scraping en 15000 milisegundos (15 segundos).
Analiza PDF explícitamente mediante parsers: ["pdf"].

Referencia de la API: Scrape Endpoint Documentation

Extracción JSON mediante formatos

Usa el objeto de formato JSON en formats para extraer datos estructurados en una sola operación:

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://firecrawl.dev",
    "formats": [{
      "type": "json",
      "prompt": "Extract the features of the product",
      "schema": {"type": "object", "properties": {"features": {"type": "object"}}, "required": ["features"]}
    }]
  }'

Endpoint de extracción

Utiliza la API específica de trabajos de extracción cuando necesites una extracción asíncrona con consulta del estado.

import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR-API-KEY' });

// Inicia un trabajo de extracción
const started = await firecrawl.startExtract({
  urls: ['https://docs.firecrawl.dev'],
  prompt: 'Extraer título',
  schema: { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] }
});

// Consulta el estado
const status = await firecrawl.getExtractStatus(started.id);
console.log(status.status, status.data);

Rastreo de múltiples páginas

Para rastrear varias páginas, usa el endpoint /v2/crawl.

cURL

curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer fc-TU-CLAVE-DE-API' \
    -d '{
      "url": "https://docs.firecrawl.dev"
    }'

Devuelve un ID

{ "id": "1234-5678-9101" }

Consultar trabajo de rastreo

Se utiliza para consultar el estado de un trabajo de rastreo y obtener su resultado.

cURL

curl -X GET https://api.firecrawl.dev/v2/crawl/1234-5678-9101 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY'

Paginación/URL siguiente

Si el contenido es superior a 10 MB o si la tarea de rastreo aún se está ejecutando, la respuesta puede incluir un parámetro next, una URL de la siguiente página de resultados.

Vista previa del prompt y parámetros de rastreo

Puedes proporcionar un prompt en lenguaje natural para que Firecrawl derive la configuración de rastreo. Primero, prévisualízala:

cURL

curl -X POST https://api.firecrawl.dev/v2/crawl/params-preview \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://docs.firecrawl.dev",
    "prompt": "Extrae la documentación y el blog"
  }'

Opciones del rastreador

Al usar el endpoint /v2/crawl, puedes personalizar el comportamiento del rastreo con:

includePaths

Tipo: array
Descripción: Patrones de expresiones regulares a incluir.
Ejemplo: ["^/blog/.*$", "^/docs/.*$"]

excludePaths

Tipo: array
Descripción: Patrones de expresiones regulares para excluir.
Ejemplo: ["^/admin/.*$", "^/private/.*$"]

maxDiscoveryDepth

Tipo: integer
Descripción: Profundidad máxima de descubrimiento para encontrar nuevas URLs.

limit

Tipo: integer
Descripción: Número máximo de páginas a rastrear.
Valor predeterminado: 10000

crawlEntireDomain

Type: boolean
Description: Explorar a través de páginas hermanas y superiores para cubrir todo el dominio.
Default: false

allowExternalLinks

Tipo: boolean
Descripción: Seguir enlaces a dominios externos.
Valor predeterminado: false

allowSubdomains

Tipo: boolean
Descripción: Seguir los subdominios del dominio principal.
Valor predeterminado: false

delay

Tipo: number
Descripción: Retraso en segundos entre scrapes.
Predeterminado: undefined

scrapeOptions

Tipo: object
Descripción: Opciones para el scraper (consulta los formatos arriba).
Ejemplo: { "formats": ["markdown", "links", {"type": "screenshot", "fullPage": true}], "includeTags": ["h1", "p", "a", ".main-content"], "excludeTags": ["#ad", "#footer"], "onlyMainContent": false, "waitFor": 1000, "timeout": 15000}
Valores predeterminados: formats: ["markdown"], caché habilitada de forma predeterminada (maxAge ~ 2 días)

Ejemplo de uso

cURL

curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer fc-TU-API-KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "includePaths": ["^/blog/.*$", "^/docs/.*$"],
      "excludePaths": ["^/admin/.*$", "^/private/.*$"],
      "maxDiscoveryDepth": 2,
      "limit": 1000
    }'

Mapeo de enlaces de sitios web

El endpoint /v2/map identifica las URL relacionadas con un sitio web dado.

Uso

cURL

curl -X POST https://api.firecrawl.dev/v2/map \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer fc-TU-API-KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev"
    }'

Opciones de mapeo

search

Tipo: string
Descripción: Filtra enlaces que contengan el texto.

limit

Tipo: integer
Descripción: Número máximo de enlaces a retornar.
Valor por defecto: 100

sitemap

Tipo: "only" | "include" | "skip"
Descripción: Controla el uso del sitemap durante el mapeo.
Predeterminado: "include"

includeSubdomains

Tipo: boolean
Descripción: Incluye los subdominios del sitio web.
Valor predeterminado: true

Consulta la referencia de la API: Documentación del endpoint /map ¡Gracias por leer!

Primeros pasos

Novedades

Funciones principales

Webhooks

Guías para desarrolladores

Casos de uso

Cómo contribuir

​Scraping básico con Firecrawl

​Extracción de PDF

​Opciones de extracción

​Formatos (formats)

​Contenido completo de la página vs contenido principal (onlyMainContent)

​Incluir etiquetas (includeTags)

​Excluir etiquetas (excludeTags)

​Esperar a que la página esté lista (waitFor)

​Actualidad y caché (maxAge)

​Tiempo de espera de la solicitud (timeout)

​Análisis de PDF (parsers)

​Acciones (actions)

​Notas sobre la ejecución de acciones

​Ejemplos de acciones avanzadas

​Ejemplo de uso

​Extracción JSON mediante formatos

​Endpoint de extracción

​Rastreo de múltiples páginas

​Consultar trabajo de rastreo

​Paginación/URL siguiente

​Vista previa del prompt y parámetros de rastreo

​Opciones del rastreador

​includePaths

​excludePaths

​maxDiscoveryDepth

​limit

​crawlEntireDomain

​allowExternalLinks

​allowSubdomains

​delay

​scrapeOptions

​Ejemplo de uso

​Mapeo de enlaces de sitios web

​Uso

​Opciones de mapeo

​search

​limit

​sitemap

​includeSubdomains

Scraping básico con Firecrawl

Extracción de PDF

Opciones de extracción

Formatos (`formats`)

Contenido completo de la página vs contenido principal (`onlyMainContent`)

Incluir etiquetas (`includeTags`)

Excluir etiquetas (`excludeTags`)

Esperar a que la página esté lista (`waitFor`)

Actualidad y caché (`maxAge`)

Tiempo de espera de la solicitud (`timeout`)

Análisis de PDF (`parsers`)

Acciones (`actions`)

Notas sobre la ejecución de acciones

Ejemplos de acciones avanzadas

Ejemplo de uso

Extracción JSON mediante formatos

Endpoint de extracción

Rastreo de múltiples páginas

Consultar trabajo de rastreo

Paginación/URL siguiente

Vista previa del prompt y parámetros de rastreo

Opciones del rastreador

includePaths

excludePaths

maxDiscoveryDepth

limit

crawlEntireDomain

allowExternalLinks

allowSubdomains

delay

scrapeOptions

Ejemplo de uso

Mapeo de enlaces de sitios web

Uso

Opciones de mapeo

search

limit

sitemap

includeSubdomains