> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/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
}
}
}
```
### 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` : invite facultative pour guider l’extraction (également utilisée pour l’extraction sans schéma).
**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`.
**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.