Guide avancé de scraping

Référence pour toutes les options disponibles sur les points de terminaison de scraping, crawling, mapping et agent de Firecrawl.”

Scraping basique

Pour extraire une seule page et obtenir un contenu Markdown propre, utilisez le point de terminaison /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)

Extraction de PDF

Firecrawl prend en charge les PDF. Utilisez l’option parsers (par exemple parsers: ["pdf"]) lorsque vous voulez garantir l’analyse des PDF. Vous pouvez contrôler la stratégie d’analyse avec l’option mode :

auto (par défaut) — tente d’abord une extraction rapide basée sur le texte, puis bascule vers l’OCR si nécessaire.
fast — analyse basée uniquement sur le texte (texte intégré). La plus rapide, mais ignore les pages scannées ou très riches en images.
ocr — force l’analyse par OCR sur chaque page. À utiliser pour les documents numérisés ou lorsque auto classe mal une page.

{ type: "pdf" } et "pdf" utilisent tous les deux mode: "auto" par défaut.

"parsers": [{ "type": "pdf", "mode": "fast", "maxPages": 50 }]

Options de scraping

Lorsque vous utilisez le point de terminaison /scrape, vous pouvez personnaliser la requête à l’aide des options suivantes.

Formats (`formats`)

Le tableau formats contrôle les types de sortie que le scraper renvoie. Valeur par défaut : ["markdown"]. Formats de type chaîne de caractères : passez le nom directement (par ex. "markdown").

Format	Description
`markdown`	Contenu de la page converti en Markdown propre.
`html`	HTML traité avec les éléments inutiles supprimés.
`rawHtml`	HTML original exactement tel que renvoyé par le serveur.
`links`	Tous les liens trouvés sur la page.
`images`	Toutes les images trouvées sur la page.
`summary`	Un résumé du contenu de la page généré par un LLM.
`branding`	Extrait l’identité de marque (couleurs, polices, typographie, espacements, composants d’UI).

Formats objet : passez un objet avec type et des options supplémentaires.

Format	Options	Description
`json`	`prompt?: string`, `schema?: object`	Extraire des données structurées à l’aide d’un LLM. Fournissez un schéma JSON et/ou un prompt en langage naturel (10 000 caractères max).
`screenshot`	`fullPage?: boolean`, `quality?: number`, `viewport?: { width, height }`	Prendre une capture d’écran. Maximum une par requête. La résolution maximale du viewport est 7680×4320. Les URL des captures d’écran expirent après 24 heures.
`changeTracking`	`modes?: ("json" \| "git-diff")[]`, `tag?: string`, `schema?: object`, `prompt?: string`	Suivre les modifications entre les scrapes. Nécessite que `"markdown"` soit également présent dans le tableau `formats`.
`attributes`	`selectors: [{ selector: string, attribute: string }]`	Extraire des attributs HTML spécifiques à partir des éléments correspondant à des sélecteurs CSS.

Scraping mobile

Définissez mobile: true pour émuler un appareil mobile. Cela est utile lorsqu’un site responsive masque du contenu sur ordinateur ou affiche une mise en page différente sur les navigateurs mobiles. Pour les sites spécifiques à une région, combinez cette option avec location et une capture d’écran mobile afin de vérifier la mise en page affichée :

from firecrawl import Firecrawl

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

doc = firecrawl.scrape(
    "https://example.com",
    mobile=True,
    location={"country": "GB", "languages": ["en-GB"]},
    formats=[
        "markdown",
        {"type": "screenshot", "fullPage": True, "viewport": {"width": 390, "height": 844}},
    ],
    only_main_content=False,
    wait_for=2000,
)

print(doc.markdown)

Si le site continue d’afficher une mise en page desktop malgré mobile: true, ajoutez un User-Agent mobile via headers :

{
  "headers": {
    "User-Agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
  }
}

Filtrage du contenu

Ces paramètres contrôlent quelles parties de la page apparaissent dans le résultat. Lorsque onlyMainContent vaut true (valeur par défaut), le boilerplate (navigation, pied de page, etc.) est supprimé. includeTags et excludeTags sont appliqués au DOM original de la page, et non au résultat après filtrage ; vos sélecteurs doivent donc cibler les éléments tels qu’ils apparaissent dans le HTML source. Si vous définissez onlyMainContent: false, le HTML complet de la page est utilisé comme point de départ pour le filtrage par balises.

Paramètre	Type	Valeur par défaut	Description
`onlyMainContent`	`boolean`	`true`	Retourne uniquement le contenu principal. Définissez sur `false` pour la page complète.
`includeTags`	`array`	—	Sélecteurs CSS à inclure — balises, classes, identifiants ou sélecteurs d’attribut (par ex. `["h1", "p", ".main-content", "[data-testid=\"main\"]"]`).
`excludeTags`	`array`	—	Sélecteurs CSS à exclure — balises, classes, identifiants ou sélecteurs d’attribut (par ex. `["#ad", "#footer", "[role=\"banner\"]"]`).

Timing et cache

Paramètre	Type	Valeur par défaut	Description
`waitFor`	`integer` (ms)	`0`	Temps d’attente supplémentaire avant le scraping, en plus du smart-wait. À utiliser avec parcimonie.
`maxAge`	`integer` (ms)	`172800000`	Retourne une version mise en cache si elle est plus récente que cette valeur (2 jours par défaut). Définissez `0` pour toujours récupérer des données fraîches.
`timeout`	`integer` (ms)	`60000`	Durée maximale d’une requête avant abandon (60 secondes par défaut). Le minimum est de 1000 (1 seconde).

Analyse de PDF

Paramètre	Type	Valeur par défaut	Description
`parsers`	`array`	`["pdf"]`	Contrôle le traitement des PDF. `[]` pour ignorer l’analyse et renvoyer le contenu en base64 (forfait de 1 crédit).

{ "type": "pdf", "mode": "fast" | "auto" | "ocr", "maxPages": 10 }

Propriété	Type	Valeur par défaut	Description
`type`	`"pdf"`	(obligatoire)	Type d’analyseur.
`mode`	`"fast" \| "auto" \| "ocr"`	`"auto"`	`fast` : extraction basée uniquement sur le texte. `auto` : rapide avec repli sur l’OCR. `ocr` : forcer l’OCR.
`maxPages`	`integer`	—	Limiter le nombre de pages à analyser.

Actions

Exécutez des actions de navigateur avant le scraping. C’est utile pour le contenu dynamique, la navigation ou les pages nécessitant une interaction de l’utilisateur. Vous pouvez inclure jusqu’à 50 actions par requête, et le temps d’attente cumulé de toutes les actions wait et de waitFor ne doit pas dépasser 60 secondes.

Action	Paramètres	Description
`wait`	`milliseconds?: number`, `selector?: string`	Attend une durée fixe ou jusqu’à ce qu’un élément soit visible (indiquez l’un ou l’autre, pas les deux). Si vous utilisez `selector`, le délai d’expiration est de 30 secondes.
`click`	`selector: string`, `all?: boolean`	Clique sur un élément correspondant au sélecteur CSS. Définissez `all: true` pour cliquer sur toutes les correspondances.
`write`	`text: string`	Saisit du texte dans le champ actuellement actif. Vous devez d’abord donner le focus à l’élément avec une action `click`.
`press`	`key: string`	Appuie sur une touche du clavier (par ex. `"Enter"`, `"Tab"`, `"Escape"`).
`scroll`	`direction?: "up" \| "down"`, `selector?: string`	Fait défiler la page ou un élément spécifique. La direction par défaut est `"down"`.
`screenshot`	`fullPage?: boolean`, `quality?: number`, `viewport?: { width, height }`	Capture une capture d’écran. La résolution maximale du viewport est de 7680×4320.
`scrape`	(aucun)	Capture le HTML actuel de la page à ce stade de la séquence d’actions.
`executeJavascript`	`script: string`	Exécute du code JavaScript dans la page. Les valeurs de retour sont disponibles dans le tableau `actions.javascriptReturns` de la réponse.
`pdf`	`format?: string`, `landscape?: boolean`, `scale?: number`	Génère un PDF. Formats pris en charge : de `"A0"` à `"A6"`, `"Letter"`, `"Legal"`, `"Tabloid"`, `"Ledger"`. La valeur par défaut est `"Letter"`.

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)

Notes sur l’exécution des actions

Write nécessite un click préalable pour placer le focus sur l’élément cible.
Scroll accepte un selector optionnel pour faire défiler un élément spécifique plutôt que la page.
Wait accepte soit milliseconds (délai fixe), soit selector (attendre jusqu’à ce que l’élément soit visible).
Les actions s’exécutent séquentiellement : chaque étape se termine avant que la suivante ne commence.
Les actions ne sont pas prises en charge pour les PDF. Si l’URL renvoie vers un PDF, la requête échouera.

Exemples d’actions avancées

Prendre une capture d’écran :

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 sur plusieurs éléments :

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"]
  }'

Générer 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 }
    ]
  }'

Exécuter JavaScript (par ex. extraire les données intégrées à la page) :

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": "executeJavascript", "script": "document.querySelector(\"#__NEXT_DATA__\").textContent" }
    ],
    "formats": ["markdown"]
  }'

La valeur de retour de chaque action executeJavascript est enregistrée dans le tableau actions.javascriptReturns de la réponse.

Exemple d’extraction complète

La requête suivante combine plusieurs options d’extraction :

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://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"]
    }'

Cette requête renvoie du Markdown, du HTML, du HTML brut, des liens et une capture d’écran de la page entière. Elle limite le contenu à <h1>, <p>, <a> et .main-content tout en excluant #ad et #footer, attend 1 seconde avant l’extraction, définit un délai d’expiration de 15 secondes et active l’analyse des PDF. Consultez la référence complète de l’API Scrape pour plus de détails.

Extraction de JSON via `formats`

Utilisez l’objet de format JSON dans formats pour extraire une donnée structurée en un seul passage :

from firecrawl import Firecrawl

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

doc = firecrawl.scrape('https://firecrawl.dev', {
  'formats': [{
    'type': 'json',
    'prompt': 'Extract the features of the product',
    'schema': {
      'type': 'object',
      'properties': { 'features': { 'type': 'object' } },
      'required': ['features']
    }
  }]
})

print(doc.json)

Endpoint de l’agent

Utilisez l’endpoint /v2/agent pour effectuer une extraction autonome de données sur plusieurs pages. L’agent fonctionne de manière asynchrone : vous démarrez un job, puis interrogez périodiquement l’API pour récupérer les résultats.

Options de l’agent

Paramètre	Type	Valeur par défaut	Description
`prompt`	`string`	(obligatoire)	Instructions en langage naturel décrivant les données à extraire (10 000 caractères maximum).
`urls`	`array`	—	URL auxquelles limiter l’agent.
`schema`	`object`	—	Schéma JSON pour structurer les données extraites.
`maxCredits`	`number`	`2500`	Nombre maximal de crédits que l’agent peut utiliser. Le tableau de bord prend en charge jusqu’à 2 500 ; pour des limites plus élevées, définissez cette valeur via l’API (les valeurs supérieures à 2 500 sont toujours facturées comme des requêtes payantes).
`strictConstrainToURLs`	`boolean`	`false`	Lorsque `true`, l’agent ne visite que les URL fournies.
`model`	`string`	`"spark-1-mini"`	Modèle d’IA à utiliser : `"spark-1-mini"` (par défaut, 60 % moins cher) ou `"spark-1-pro"` (meilleure précision).

from firecrawl import Firecrawl

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

# Lancer une tâche d'agent
started = firecrawl.start_agent(
    prompt="Extract the title and description",
    urls=["https://docs.firecrawl.dev"],
    schema={"type": "object", "properties": {"title": {"type": "string"}, "description": {"type": "string"}}, "required": ["title"]}
)

# Consulter le statut
status = firecrawl.get_agent_status(started["id"])
print(status.get("status"), status.get("data"))

Vérifier l’état de l’agent

Envoyez des requêtes GET /v2/agent/{jobId} pour suivre l’avancement. Le champ status de la réponse vaudra "processing", "completed" ou "failed".

cURL

curl -X GET https://api.firecrawl.dev/v2/agent/YOUR-JOB-ID \
  -H 'Authorization: Bearer fc-YOUR-API-KEY'

Les SDK Python et Node fournissent également une méthode pratique (firecrawl.agent()) qui lance la tâche et interroge automatiquement son état jusqu’à son achèvement.

Crawl de plusieurs pages

Pour crawler plusieurs pages, utilisez le point de terminaison /v2/crawl. Le crawl s’exécute de manière asynchrone et renvoie un ID de tâche. Utilisez le paramètre limit pour contrôler le nombre de pages explorées. S’il n’est pas indiqué, le crawl traitera jusqu’à 10 000 pages.

cURL

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

Réponse

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

Vérifier l’état d’une tâche de crawl

Utilisez l’ID de tâche pour vérifier l’état d’un crawl et récupérer ses résultats.

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'

Si le contenu dépasse 10 Mo ou si la tâche de crawl est toujours en cours, la réponse peut inclure un paramètre next, c’est-à-dire l’URL de la page de résultats suivante.

Aperçu du prompt et des paramètres de crawl

Vous pouvez fournir un prompt en langage naturel pour permettre à Firecrawl de déduire les paramètres de crawl. Prévisualisez-les d’abord :

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": "Extract docs and blog"
  }'

Options du crawler

Lorsque vous utilisez l’endpoint /v2/crawl, vous pouvez personnaliser le comportement du crawl à l’aide des options suivantes.

Filtrage des chemins

Paramètre	Type	Valeur par défaut	Description
`includePaths`	`array`	—	Motifs regex pour les URL à inclure (pathname uniquement par défaut).
`excludePaths`	`array`	—	Motifs regex pour les URL à exclure (pathname uniquement par défaut).
`regexOnFullURL`	`boolean`	`false`	Faire correspondre les motifs sur l’URL complète plutôt que seulement sur le pathname.

L’URL de départ est également vérifiée par rapport à includePaths. Si elle ne correspond à aucun motif, le crawl peut renvoyer 0 page.

Portée du crawl

Paramètre	Type	Valeur par défaut	Description
`maxDiscoveryDepth`	`integer`	—	Profondeur maximale de liens pour la découverte de nouvelles URL.
`limit`	`integer`	`10000`	Nombre maximal de pages à explorer.
`crawlEntireDomain`	`boolean`	`false`	Explorer les pages parentes et voisines pour couvrir l’ensemble du domaine.
`allowExternalLinks`	`boolean`	`false`	Suivre les liens vers des domaines externes.
`allowSubdomains`	`boolean`	`false`	Suivre les sous-domaines du domaine principal.
`delay`	`number` (s)	—	Délai entre deux extractions. Définir cette valeur force la simultanéité à 1.

Sitemap et déduplication

Paramètre	Type	Valeur par défaut	Description
`sitemap`	`string`	`"include"`	`"include"` : utiliser le sitemap + la découverte de liens. `"skip"` : ignorer le sitemap. `"only"` : explorer uniquement les URL du sitemap.
`deduplicateSimilarURLs`	`boolean`	`true`	Traite les variantes d’URL (`www.`, `https`, slash final, `index.html`) comme des doublons.
`ignoreQueryParameters`	`boolean`	`false`	Supprime les paramètres de requête avant la déduplication (par exemple `/page?a=1` et `/page?a=2` sont considérées comme une seule URL).

Options de scrape pour le crawl

Paramètre	Type	Par défaut	Description
`scrapeOptions`	`object`	`{ formats: ["markdown"] }`	Configuration de scrape page par page. Accepte toutes les options de scrape ci-dessus.

Exemple de crawl

cURL

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

Cartographie des liens d’un site web

Le point de terminaison /v2/map identifie les URL associées à un site web donné.

cURL

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

Options de cartographie

Paramètre	Type	Valeur par défaut	Description
`search`	`string`	—	Filtrer les liens par correspondance textuelle.
`limit`	`integer`	`100`	Nombre maximal de liens à renvoyer.
`sitemap`	`string`	`"include"`	`"include"`, `"skip"` ou `"only"`.
`includeSubdomains`	`boolean`	`true`	Inclure les sous-domaines.

Voici la référence de l’API : Documentation du point de terminaison « Map »

Autoriser Firecrawl

Autoriser Firecrawl à explorer votre site web

User Agent : Autorisez FirecrawlAgent dans votre pare-feu ou vos règles de sécurité.
Adresses IP : Firecrawl n’utilise pas un ensemble fixe d’adresses IP sortantes.

Autoriser votre application à appeler l’API Firecrawl

Si votre pare-feu bloque les requêtes sortantes de votre application vers des services externes, vous devez ajouter l’adresse IP du serveur de l’API Firecrawl à la liste d’autorisation afin que votre application puisse atteindre l’API Firecrawl (api.firecrawl.dev) :

Adresse IP : 35.245.250.27

Ajoutez cette adresse IP à la liste d’autorisation des connexions sortantes de votre pare-feu afin que votre backend puisse envoyer à Firecrawl des requêtes de scraping, de crawling, de mapping et des requêtes d’agent.

​Scraping basique

​Extraction de PDF

​Options de scraping

​Formats (formats)

​Scraping mobile

​Filtrage du contenu

​Timing et cache

​Analyse de PDF

​Actions

​Notes sur l’exécution des actions

​Exemples d’actions avancées

​Exemple d’extraction complète

​Extraction de JSON via formats

​Endpoint de l’agent

​Options de l’agent

​Vérifier l’état de l’agent

​Crawl de plusieurs pages

​Réponse

​Vérifier l’état d’une tâche de crawl

​Aperçu du prompt et des paramètres de crawl

​Options du crawler

​Filtrage des chemins

​Portée du crawl

​Sitemap et déduplication

​Options de scrape pour le crawl

​Exemple de crawl

​Cartographie des liens d’un site web

​Options de cartographie

​Autoriser Firecrawl

​Autoriser Firecrawl à explorer votre site web

​Autoriser votre application à appeler l’API Firecrawl

Scraping basique

Extraction de PDF

Options de scraping

Formats (`formats`)

Scraping mobile

Filtrage du contenu

Timing et cache

Analyse de PDF

Actions

Notes sur l’exécution des actions

Exemples d’actions avancées

Exemple d’extraction complète

Extraction de JSON via `formats`

Endpoint de l’agent

Options de l’agent

Vérifier l’état de l’agent

Crawl de plusieurs pages

Réponse

Vérifier l’état d’une tâche de crawl

Aperçu du prompt et des paramètres de crawl

Options du crawler

Filtrage des chemins

Portée du crawl

Sitemap et déduplication

Options de scrape pour le crawl

Exemple de crawl

Cartographie des liens d’un site web

Options de cartographie

Autoriser Firecrawl

Autoriser Firecrawl à explorer votre site web

Autoriser votre application à appeler l’API Firecrawl