> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-capy-docs-factual-copy-fixes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Mode JSON - Résultat structuré
> Extraire des données structurées à partir de pages via des LLM
**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](/fr/features/agent).
* Comparaison complète : [Choisir l’extracteur de données](/fr/developer-guides/usage-guides/choosing-the-data-extractor).
**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](/fr/api-reference/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 :
1. **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.
2. **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](https://docs.firecrawl.dev/api-reference/endpoint/scrape)
3. **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.
Mode JSON via /scrape
Permet d’extraire des données structurées à partir de pages explorées.
```python Python theme={null}
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)
```
```js Node theme={null}
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);
```
```bash cURL theme={null}
# 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 JSON theme={null}
{
"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.
```python Python theme={null}
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)
```
```js Node theme={null}
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);
```
```bash cURL theme={null}
# 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 JSON theme={null}
{
"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/"
},
}
}
```
Voici un exemple complet montrant comment extraire des informations structurées sur une entreprise à partir d’un site web :
```python Python theme={null}
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)
```
```js Node theme={null}
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);
```
```bash cURL theme={null}
# 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 Output theme={null}
{
"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
}
}
}
```
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](#prompt-injection-detection)). 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` :
```json theme={null}
{
"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.
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é :**
```json theme={null}
{
"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 :
```json theme={null}
{
"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](https://www.firecrawl.dev/agent-onboarding/SKILL.md) pour obtenir les instructions d’intégration automatisée.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.