Mode JSON | Firecrawl

Choisir le bon outil. Le mode JSON (cette page) est adapté si vous avez une seule URL et souhaitez extraire des champs depuis cette page uniquement.

Pour tout ce qui dépasse une seule URL — plusieurs URL, des modèles d’URL ou une découverte pilotée par agent — consultez Agent.
Comparaison complète : Choisir l’extracteur de données.

Changement de l’API v2 : L’extraction de schémas JSON est entièrement prise en charge en v2, mais le format de l’API a changé. En v2, le schéma est directement intégré dans l’objet formats sous la forme formats: [{type: "json", schema: {...}}]. Le paramètre jsonOptions de la v1 n’existe plus en v2.

Pour les échecs de validation de schéma et les autres erreurs d’extraction, consultez Errors — les problèmes spécifiques à l’extraction se manifestent généralement par des réponses 400 ou 422.

Extraire et structurer des données avec Firecrawl

Firecrawl utilise l’IA pour obtenir des données structurées à partir de pages web en 3 étapes :

Définir le schéma (optionnel) : Définissez un schéma JSON (au format OpenAI) pour préciser les données souhaitées, ou fournissez simplement un prompt si vous n’avez pas besoin d’un schéma strict, ainsi que l’URL de la page web.
Envoyer la requête : Envoyez votre URL et votre schéma au point de terminaison /scrape en utilisant le mode JSON. Découvrez comment ici : Scrape Endpoint Documentation
Récupérer vos données : Recevez des données propres et structurées correspondant à votre schéma, prêtes à l’emploi.

Cela rend l’obtention de données web, au format dont vous avez besoin, rapide et simple.

Extraire des données structurées

Mode JSON via /scrape

Permet d’extraire des données structurées à partir de pages explorées.

from firecrawl import Firecrawl
from pydantic import BaseModel

app = Firecrawl(
  # Aucune clé API requise pour démarrer — ajoutez-en une pour des limites de débit plus élevées :
  # api_key="fc-YOUR-API-KEY",
)

class CompanyInfo(BaseModel):
    company_mission: str
    supports_sso: bool
    is_open_source: bool
    is_in_yc: bool

result = app.scrape(
    'https://firecrawl.dev',
    formats=[{
      "type": "json",
      "schema": CompanyInfo.model_json_schema()
    }],
    only_main_content=False,
    timeout=120000
)

print(result)

import { Firecrawl } from "firecrawl";
import { z } from "zod";

const app = new Firecrawl({
  // Aucune clé API requise pour démarrer — ajoutez-en une pour des limites de débit plus élevées :
  // apiKey: "fc-YOUR_API_KEY",
});

// Définir le schéma pour extraire les contenus
const schema = z.object({
  company_mission: z.string(),
  supports_sso: z.boolean(),
  is_open_source: z.boolean(),
  is_in_yc: z.boolean()
});

const result = await app.scrape("https://firecrawl.dev", {
  formats: [{
    type: "json",
    schema: schema
  }],
});

console.log(result);

# Aucune clé API requise pour démarrer — ajoutez -H "Authorization: Bearer VOTRE_CLÉ_API" pour des limites de débit plus élevées :
curl -X POST https://api.firecrawl.dev/v2/scrape \
    -H 'Content-Type: application/json' \
    -d '{
      "url": "https://firecrawl.dev",
      "formats": [ {
        "type": "json",
        "schema": {
          "type": "object",
          "properties": {
            "company_mission": {
                      "type": "string"
            },
            "supports_sso": {
                      "type": "boolean"
            },
            "is_open_source": {
                      "type": "boolean"
            },
            "is_in_yc": {
                      "type": "boolean"
            }
          },
          "required": [
            "company_mission",
            "supports_sso",
            "is_open_source",
            "is_in_yc"
          ]
        }
      } ]
    }'

Résultat :

JSON

{
    "success": true,
    "data": {
      "json": {
        "company_mission": "Scraping et extraction de données web propulsés par l’IA",
        "supports_sso": true,
        "is_open_source": true,
        "is_in_yc": true
      },
      "metadata": {
        "title": "Firecrawl",
        "description": "Scraping et extraction de données web propulsés par l’IA",
        "robots": "suivre, indexer",
        "ogTitle": "Firecrawl",
        "ogDescription": "Scraping et extraction de données web propulsés par l’IA",
        "ogUrl": "https://firecrawl.dev/",
        "ogImage": "https://firecrawl.dev/og.png",
        "ogLocaleAlternate": [],
        "ogSiteName": "Firecrawl"
        "sourceURL": "https://firecrawl.dev/"
      },
    }
}

Données structurées sans schéma

Vous pouvez aussi extraire sans schéma en passant simplement un prompt au point de terminaison. Le LLM détermine la structure des données.

from firecrawl import Firecrawl

app = Firecrawl(
  # Aucune clé API requise pour démarrer — ajoutez-en une pour des limites de débit plus élevées :
  # api_key="fc-YOUR-API-KEY",
)

result = app.scrape(
    'https://firecrawl.dev',
    formats=[{
      "type": "json",
      "prompt": "Extract the company mission from the page."
    }],
    only_main_content=False,
    timeout=120000
)

print(result)

import { Firecrawl } from "firecrawl";

const app = new Firecrawl({
  // Aucune clé API requise pour démarrer — ajoutez-en une pour des limites de débit plus élevées :
  // apiKey: "fc-VOTRE_CLÉ_API",
});

const result = await app.scrape("https://firecrawl.dev", {
  formats: [{
    type: "json",
    prompt: "Extract the company mission from the page."
  }]
});

console.log(result);

# Aucune clé API requise pour démarrer — ajoutez -H "Authorization: Bearer VOTRE_CLÉ_API" pour des limites de débit plus élevées :
curl -X POST https://api.firecrawl.dev/v2/scrape \
    -H 'Content-Type: application/json' \
    -d '{
      "url": "https://firecrawl.dev",
      "formats": [{
        "type": "json",
        "prompt": "Extract the company mission from the page."
      }]
    }'

Résultat :

JSON

{
    "success": true,
    "data": {
      "json": {
        "company_mission": "Collecte et extraction de données web propulsées par l’IA",
      },
      "metadata": {
        "title": "Firecrawl",
        "description": "Collecte et extraction de données web propulsées par l’IA",
        "robots": "follow, index",
        "ogTitle": "Firecrawl",
        "ogDescription": "Collecte et extraction de données web propulsées par l’IA",
        "ogUrl": "https://firecrawl.dev/",
        "ogImage": "https://firecrawl.dev/og.png",
        "ogLocaleAlternate": [],
        "ogSiteName": "Firecrawl",
        "sourceURL": "https://firecrawl.dev/"
      },
    }
}

Exemple concret : extraction d’informations d’entreprise

Voici un exemple complet montrant comment extraire des informations structurées sur une entreprise à partir d’un site web :

from firecrawl import Firecrawl
from pydantic import BaseModel

app = Firecrawl(
  # Aucune clé API requise pour démarrer — ajoutez-en une pour des limites de débit plus élevées :
  # api_key="fc-YOUR-API-KEY",
)

class CompanyInfo(BaseModel):
    company_mission: str
    supports_sso: bool
    is_open_source: bool
    is_in_yc: bool

result = app.scrape(
    'https://firecrawl.dev/',
    formats=[{
        "type": "json",
        "schema": CompanyInfo.model_json_schema()
    }]
)

print(result)

import { Firecrawl } from "firecrawl";
import { z } from "zod";

const app = new Firecrawl({
  // Aucune clé API requise pour démarrer — ajoutez-en une pour des limites de débit plus élevées :
  // apiKey: "fc-VOTRE_CLÉ_API",
});

const companyInfoSchema = z.object({
  company_mission: z.string(),
  supports_sso: z.boolean(),
  is_open_source: z.boolean(),
  is_in_yc: z.boolean()
});

const result = await app.scrape("https://firecrawl.dev/", {
  formats: [{
    type: "json",
    schema: companyInfoSchema
  }]
});

console.log(result);

# Aucune clé API requise pour démarrer — ajoutez -H "Authorization: Bearer VOTRE_CLÉ_API" pour des limites de débit plus élevées :
curl -X POST https://api.firecrawl.dev/v2/scrape \
    -H 'Content-Type: application/json' \
    -d '{
      "url": "https://firecrawl.dev/",
      "formats": [{
        "type": "json",
        "schema": {
          "type": "object",
          "properties": {
            "company_mission": {
              "type": "string"
            },
            "supports_sso": {
              "type": "boolean"
            },
            "is_open_source": {
              "type": "boolean"
            },
            "is_in_yc": {
              "type": "boolean"
            }
          },
          "required": [
            "company_mission",
            "supports_sso",
            "is_open_source",
            "is_in_yc"
          ]
        }
      }]
    }'

Résultat :

Output

{
  "success": true,
  "data": {
    "json": {
      "company_mission": "Transformer les sites web en données prêtes pour les LLM",
      "supports_sso": true,
      "is_open_source": true,
      "is_in_yc": true
    }
  }
}

Options du format JSON

Lorsque vous utilisez le mode JSON dans la v2, incluez un objet dans formats avec le schéma directement intégré : formats: [{ type: 'json', schema: { ... }, prompt: '...' }] Paramètres :

schema : schéma JSON décrivant la sortie structurée souhaitée (obligatoire pour l’extraction basée sur un schéma).
prompt : prompt facultatif pour guider l’extraction (également utilisé pour l’extraction sans schéma).
checkPromptInjection : obsolète. Utilisez plutôt l’option d’extraction checkPromptInjection de premier niveau (consultez Détection des injections de prompts). Une valeur définie ici reste toutefois prise en compte.

Important : Contrairement à la v1, il n’existe pas de paramètre distinct jsonOptions dans la v2. Le schéma doit être inclus directement dans l’objet de format du tableau formats.

Détection des injections de prompts

Les pages web peuvent contenir du texte caché conçu pour détourner un LLM, par exemple des instructions demandant au modèle d’ignorer votre schéma et de renvoyer des données contrôlées par un attaquant. Si vous effectuez une extraction à partir d’URL non fiables ou soumises par les utilisateurs, définissez l’option d’extraction de premier niveau checkPromptInjection afin de vérifier le contenu de la page avant l’exécution de tout format reposant sur un LLM (comme json, summary ou question). Elle fonctionne avec tous les formats sauf rawBase64, y compris une simple extraction au format markdown :

{
  "url": "https://example.com",
  "formats": [
    {
      "type": "json",
      "schema": { "type": "object", "properties": { "title": { "type": "string" } } }
    }
  ],
  "checkPromptInjection": true
}

Fonctionnement :

Un appel dédié au classifieur inspecte le contenu de la page une fois par extraction, avant l’exécution de tout format reposant sur un LLM ; il ajoute donc la latence du classifieur à la requête.
Si une tentative d’injection de prompt est détectée, la requête échoue avec un code HTTP 403 et le code d’erreur SCRAPE_PROMPT_INJECTION_DETECTED. Aucune sortie n’est renvoyée.
Si la vérification ne peut pas analyser l’intégralité du contenu (par exemple, parce que l’appel au classifieur a échoué ou que le contenu de la page dépasse 2 000 000 caractères), l’extraction se poursuit, la réponse inclut un warning et la vérification n’est pas facturée.
La vérification est facturée +4 crédits lorsqu’elle s’exécute. Si l’extraction échoue après l’exécution de la vérification (y compris lorsqu’une injection est détectée et que la requête est bloquée), 5 crédits sont facturés au lieu des 0 habituels pour une extraction ayant échoué, car l’appel au classifieur a tout de même été exécuté.

L’option fonctionne également avec l’extraction par lot, ainsi que dans scrapeOptions pour le crawl, la recherche et les monitors. Définir checkPromptInjection sur l’objet de format json fonctionne toujours, mais cette méthode est obsolète. Dans la v1, l’option est jsonOptions.checkPromptInjection. Les SDK l’exposent sous la forme checkPromptInjection (JS) et check_prompt_injection (Python).

Les attributs HTML ne sont pas accessibles dans l’extraction JSON. L’extraction JSON s’applique à la conversion de la page en markdown, qui ne préserve que le contenu textuel visible. Les attributs HTML (par exemple, data-id, attributs personnalisés sur les éléments) sont supprimés lors de la conversion et le LLM ne peut pas les voir. Si vous devez extraire des valeurs d’attribut HTML, utilisez le format rawHtml et analysez les attributs côté client, ou utilisez une action executeJavascript pour injecter les valeurs d’attribut dans le texte visible avant l’extraction.

Conseils pour une extraction cohérente

Si vous observez des résultats incohérents ou incomplets lors de l’extraction JSON, ces pratiques peuvent aider :

Gardez les prompts courts et ciblés. Des prompts longs avec de nombreuses règles augmentent la variabilité. Placez plutôt les contraintes spécifiques (comme les valeurs autorisées) dans le schéma.
Utilisez des noms de propriétés concis. Évitez d’inclure des instructions ou des listes d’énumération dans les noms de propriétés. Utilisez une clé courte comme "installation_type" et placez les valeurs autorisées dans un tableau enum.
Ajoutez des tableaux enum pour les champs contraints. Lorsqu’un champ possède un ensemble fixe de valeurs, listez-les dans enum et assurez-vous qu’elles correspondent exactement au texte affiché sur la page.
Incluez la gestion de null dans les descriptions de champs. Ajoutez "Return null if not found on the page." à la description de chaque champ afin que le modèle ne devine pas les valeurs manquantes.
Ajoutez des indications de localisation. Indiquez au modèle où trouver les données sur la page, par exemple : "Flow rate in GPM from the Specifications table.".
Divisez les grands schémas en requêtes plus petites. Les schémas avec de nombreux champs (par exemple 30+) produisent des résultats moins cohérents. Divisez-les en 2–3 requêtes de 10–15 champs chacune.
Évitez minItems/maxItems sur les tableaux. Les mots-clés de validation JSON Schema comme minItems et maxItems ne contrôlent pas la quantité de contenu collectée par le scraper. Définir minItems: 20 n’amènera pas le LLM à renvoyer davantage d’éléments — il peut au contraire halluciner des entrées pour satisfaire la contrainte. Supprimez ces mots-clés et utilisez plutôt un prompt (par exemple "Extract ALL reviews from the page. Do not skip any.") pour guider l’exhaustivité.
Utilisez "type": "array" pour extraire des listes d’éléments. Si vous devez extraire plusieurs éléments (par exemple une liste de personnes, de produits ou d’avis), encapsulez-les dans une propriété tableau avec un bloc items. Utiliser "type": "object" pour une liste ne renverra qu’un seul élément. Consultez l’exemple de schéma de tableau ci-dessous.

Exemple de schéma bien structuré :

{
  "type": "object",
  "properties": {
    "product_name": {
      "type": ["string", "null"],
      "description": "Full descriptive product name as shown on the page. Return null if not found."
    },
    "installation_type": {
      "type": ["string", "null"],
      "description": "Installation type from the Specifications section. Return null if not found.",
      "enum": ["Deck-mount", "Wall-mount", "Countertop", "Drop-in", "Undermount"]
    },
    "flow_rate_gpm": {
      "type": ["string", "null"],
      "description": "Flow rate in GPM from the Specifications section. Return null if not found."
    }
  }
}

Exemple d’extraction d’une liste d’éléments : Lorsqu’une page contient plusieurs éléments (par exemple des membres d’équipe, des produits ou des avis), utilisez "type": "array" avec "items" pour obtenir la liste complète :

{
  "type": "object",
  "properties": {
    "people": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "role": { "type": "string" },
          "department": { "type": "string" }
        }
      }
    }
  }
}

Vous êtes un agent IA et vous avez besoin d’une clé API Firecrawl ? Consultez firecrawl.dev/agent-onboarding/SKILL.md pour obtenir les instructions d’intégration automatisée.

Prise en main

Points de terminaison de base

Plus

Démarrages rapides

Guides développeur

Webhooks

Cas d'utilisation

Autres

Contribuer

Mode JSON - Résultat structuré

Extraire et structurer des données avec Firecrawl

Extraire des données structurées

Mode JSON via /scrape

Données structurées sans schéma

Exemple concret : extraction d’informations d’entreprise

Options du format JSON

Détection des injections de prompts

Conseils pour une extraction cohérente

​Extraire et structurer des données avec Firecrawl

​Extraire des données structurées

​Mode JSON via /scrape

​Données structurées sans schéma

​Exemple concret : extraction d’informations d’entreprise

​Options du format JSON

​Détection des injections de prompts

​Conseils pour une extraction cohérente

Extraire et structurer des données avec Firecrawl

Extraire des données structurées

Mode JSON via /scrape

Données structurées sans schéma

Exemple concret : extraction d’informations d’entreprise

Options du format JSON

Détection des injections de prompts

Conseils pour une extraction cohérente