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
Valores de cadena: ["markdown", "links", "html", "rawHtml", "summary"]
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)
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 que esperar antes de hacer scraping (úsalo con moderación).
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`)

Al usar el endpoint /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 por 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 de la extracción.
Acciones compatibles:
- wait { milliseconds }
- click { selector }
- write { selector, text }
- press { key }
- scroll { direction: "up" | "down" }
- scrape { selector } (extrae un subelemento)
- executeJavascript { script }
- pdf (inicia el renderizado de PDF en algunos flujos)

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: 'write', selector: '#q', text: 'firecrawl' },
    { type: 'press', key: 'Enter' }
  ],
  formats: ['markdown']
})

print(doc.markdown)

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 de JSON mediante formatos

Usa el objeto de formato JSON en formats para extraer datos estructurados en una sola pasada:

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": "Extrae las funciones del producto",
      "schema": {"type": "object", "properties": {"features": {"type": "object"}}, "required": ["features"]}
    }]
  }'

Endpoint /extract

Usa la API dedicada de trabajos de extracción cuando necesites extracción asíncrona con sondeo de estado.

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

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

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

// Consultar 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 verificar 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-TU-API-KEY'

Paginación/URL siguiente

Si el contenido supera los 10 MB o si el trabajo de rastreo aún se está ejecutando, la respuesta puede incluir un parámetro next, que es una URL a 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 un sitio web

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

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

Funciones estándar

Funciones agenticas

Webhooks

Casos de uso

Contribuciones

​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)

​Ejemplo de uso

​Extracción de JSON mediante formatos

​Endpoint /extract

​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 un sitio 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`)

Ejemplo de uso

Extracción de JSON mediante formatos

Endpoint /extract

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 un sitio web

Uso

Opciones de mapeo

search

limit

sitemap

includeSubdomains