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."

Pour extraire une seule page et obtenir un contenu Markdown propre, utilisez le point de terminaison /scrape.

# pip install firecrawl-pyfrom firecrawl import Firecrawlfirecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")doc = firecrawl.scrape("https://firecrawl.dev")print(doc.markdown)

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

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

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").

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

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 Firecrawlfirecrawl = 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"  }}

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.

{ "type": "pdf", "mode": "fast" | "auto" | "ocr", "maxPages": 10, "pages": true, "blocks": true, "pageMarkers": true }

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.

from firecrawl import Firecrawlfirecrawl = 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)

• 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.

Prendre une capture d’écran :

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 -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 -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 -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.

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

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.

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

from firecrawl import Firecrawlfirecrawl = 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)

Utilisez le point de terminaison /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.

Agent est la référence canonique pour ce point de terminaison, y compris les traces d’exécution, les webhooks et la liste complète des paramètres.

from firecrawl import Firecrawlfirecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')# Lancer une tâche d'agentstarted = 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"]})# Interroger l'étatstatus = firecrawl.get_agent_status(started["id"])print(status.get("status"), status.get("data"))

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 -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.

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

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

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

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.

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

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

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

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

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

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

• 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.

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.