DataForSEO — playbook
Accès via le serveur MCP dataforseo (outils mcp__dataforseo__*) :
docs_list_sections / docs_index / docs_search → naviguer la doc officielle en direct (gratuit, pas d'appel API facturé).api_request → exécuter n'importe quel appel authentifié de l'API DataForSEO v3.
Ces 4 outils couvrent toute l'API (pas seulement les endpoints déjà câblés dans n8n). Quand tu ne connais pas le chemin exact d'un endpoint, commence par docs_list_sections puis docs_search, puis appelle avec api_request.
Fallback sans MCP : curl en Basic Auth (voir references/recipes.md).
⚠️ Forme de la réponse : MCP api_request vs API brute (curl / HTTP)
Piège majeur : le MCP api_request déballe la réponse, pas l'API brute.
- Via le MCP : tu reçois directement le niveau tâche →
{ id, status_code, status_message, items } (en gros tasks[0].result[0], avec items).
- En curl / HTTP brut (scripts, n8n, Make…) : la réponse est enveloppée →
tasks[0].result[0].items[...].
- Conséquence vécue : les champs du
result qui ne vivent pas dans items (ex. appendix/user_data → result[0].money.balance) peuvent ne pas remonter via le MCP (renvoie items: []). Pour ces cas (dont le solde), lis la réponse brute via curl, ou repère la vraie structure.
- Le champ
cost disparaît aussi : le MCP ne renvoie pas le cost de l'appel (masqué par le déballage). Pour connaître le coût réel → curl (champ cost en racine) ou delta de solde (user_data avant/après, en curl).
- Donc : si tu valides une requête via le MCP puis la câbles en HTTP brut, adapte les chemins de parsing — passe de
items[...] (MCP) à tasks[0].result[0].items[...] (brut).
Pour tester en sandbox via le MCP : api_request avec le paramètre url (pas path) → url: "https://sandbox.dataforseo.com/v3/...".
⚠️ Règle n°1 : le coût (prioritaire)
DataForSEO est une API prépayée, facturée à chaque appel. Le solde peut se vider vite sur du batch.
- Toujours vérifier le solde avant une session de travail :
POST /v3/appendix/user_data (gratuit). ⚠️ via le MCP, le money.balance peut ne pas remonter (voir encart ci-dessus) — pour le chiffre exact du solde, passe par curl (references/recipes.md).
- Prévenir + estimer l'utilisateur AVANT tout appel “gros” : batch > ~50 tâches, crawl on-page d'un site entier, extraction backlinks massive, ou tout ce qui peut dépasser ~1 $ estimé. (Même logique que la règle Firecrawl.)
- Tester d'abord la STRUCTURE en Sandbox (gratuit, données bidons) avant de lancer en prod : base
https://sandbox.dataforseo.com/v3/. Valide le corps de requête sans dépenser, puis bascule sur https://api.dataforseo.com/v3/.
- Chaque réponse renvoie un champ
cost (total) + un cost par tâche → le logguer/annoncer après un appel réel.
Détail des modes et arbitrages coût → references/cost-and-modes.md.
Choisir le bon mode (résumé)
| Besoin |
Mode |
Pourquoi |
| 1 requête, tout de suite |
Live (.../live) |
Synchrone, réponse immédiate, mais + cher |
| Beaucoup de requêtes, pas pressé |
Task POST → Task GET (Standard queue) |
~2× moins cher que Live, asynchrone |
| Mots-clés / concurrents / idées |
DataForSEO Labs |
Base de données interne DFS, pas de scraping live → rapide et bon marché |
| Volume de recherche / CPC |
Keywords Data (Google Ads) |
Source Google Ads officielle |
Réflexe : pour de la recherche de mots-clés ou d'analyse concurrentielle, préfère Labs avant de scraper des SERP live (souvent 10× moins cher pour le même insight).
Quel endpoint pour quel job (carte rapide)
- SERP API → positions/SERP réels (Google organic, maps, news, images, YouTube…). Scraping de résultats.
- AI Optimization API (GEO / AI search) → volume de mots-clés dans les outils IA, mentions de marque dans les réponses IA (AI Overviews, ChatGPT…), interrogation de LLM au modèle choisi (Claude/ChatGPT/Gemini/Perplexity) et scraping de résultats IA. Les LLM Responses exposent un champ
fan_out_queries (Gemini/Perplexity + web_search: true) = le plus proche du query fan-out de Google. ⚠️ LLM Responses/Scraper exécutent réellement le modèle → plus cher que LLM Mentions / AI Keyword Data (base de données).
- Keywords Data API → search volume, CPC, competition, Google Trends, keywords-for-site/keywords-for-keywords.
- DataForSEO Labs API → keyword ideas, related/suggestions, ranked keywords d'un domaine, competitors, domain/page intersection, keyword difficulty, search intent, historical.
- Backlinks API → summary, backlinks, referring domains, anchors, bulk metrics, competitors, intersection.
- On-Page API → audit technique (crawl site), Lighthouse,
instant_pages (1 page live), content parsing.
- Content Analysis API → brand mentions, sentiment, phrase/category trends.
- Domain Analytics API → technologies utilisées, WHOIS.
- Merchant / App / Business Data → Google Shopping & Amazon, App Store/Play, Google Business + reviews, Trustpilot/Tripadvisor.
Carte détaillée (chemins exacts) → references/endpoints.md.
Recettes prêtes à l'emploi (dont patterns repris des workflows n8n de l'utilisateur) → references/recipes.md.
Rappels pratiques
- Base prod :
https://api.dataforseo.com/v3/ — Base sandbox : https://sandbox.dataforseo.com/v3/.
- Auth : HTTP Basic (login + password, mêmes creds que dans n8n).
- Corps = tableau JSON de tâches (même pour une seule) :
[ { ...params } ].
location_code/language_code : récupérer les codes via les endpoints .../locations et .../languages de chaque API (gratuits). Pour la France : location_name: "France", language_code: "fr".- Endpoints gratuits utiles :
appendix/user_data (solde), appendix/errors, listes locations/languages.
1---2name: dataforseo3description: Playbook pour utiliser l'API DataForSEO (SERP, AI Optimization/GEO, Keywords Data, Labs, Backlinks, On-Page, Content/Domain Analytics, Merchant/App/Business) via le serveur MCP `dataforseo`. Sert à choisir le bon endpoint + le bon mode (live vs task vs Labs) ET à maîtriser le coût (API prépayée, facturée à l'appel). À utiliser dès qu'on veut du volume de recherche, du SERP, des mentions de marque dans les réponses IA (AI Overviews/ChatGPT), des backlinks, un audit on-page, de la recherche de mots-clés/concurrents, ou tester une requête DataForSEO en local.4---56# DataForSEO — playbook78Accès via le **serveur MCP `dataforseo`** (outils `mcp__dataforseo__*`) :9- `docs_list_sections` / `docs_index` / `docs_search` → naviguer la doc officielle en direct (gratuit, pas d'appel API facturé).10- `api_request` → exécuter **n'importe quel** appel authentifié de l'API DataForSEO v3.1112Ces 4 outils couvrent **toute** l'API (pas seulement les endpoints déjà câblés dans n8n). Quand tu ne connais pas le chemin exact d'un endpoint, commence par `docs_list_sections` puis `docs_search`, puis appelle avec `api_request`.1314Fallback sans MCP : `curl` en Basic Auth (voir `references/recipes.md`).1516## ⚠️ Forme de la réponse : MCP `api_request` vs API brute (curl / HTTP)1718Piège majeur : **le MCP `api_request` déballe la réponse**, pas l'API brute.1920- **Via le MCP** : tu reçois directement le niveau tâche → `{ id, status_code, status_message, items }` (en gros `tasks[0].result[0]`, avec `items`).21- **En curl / HTTP brut** (scripts, n8n, Make…) : la réponse est **enveloppée** → `tasks[0].result[0].items[...]`.22- **Conséquence vécue** : les champs du `result` qui ne vivent **pas** dans `items` (ex. `appendix/user_data` → `result[0].money.balance`) **peuvent ne pas remonter via le MCP** (renvoie `items: []`). Pour ces cas (dont **le solde**), lis la réponse **brute via curl**, ou repère la vraie structure.23- **Le champ `cost` disparaît aussi** : le MCP ne renvoie pas le `cost` de l'appel (masqué par le déballage). Pour connaître le coût réel → **curl** (champ `cost` en racine) ou **delta de solde** (`user_data` avant/après, en curl).24- **Donc** : si tu valides une requête via le MCP puis la câbles en HTTP brut, **adapte les chemins de parsing** — passe de `items[...]` (MCP) à `tasks[0].result[0].items[...]` (brut).2526Pour tester en **sandbox via le MCP** : `api_request` avec le paramètre **`url`** (pas `path`) → `url: "https://sandbox.dataforseo.com/v3/..."`.2728## ⚠️ Règle n°1 : le coût (prioritaire)2930DataForSEO est une **API prépayée, facturée à chaque appel**. Le solde peut se vider vite sur du batch.3132- **Toujours vérifier le solde avant une session de travail** : `POST /v3/appendix/user_data` (gratuit). ⚠️ via le MCP, le `money.balance` peut ne pas remonter (voir encart ci-dessus) — pour le **chiffre exact du solde**, passe par **curl** (`references/recipes.md`).33- **Prévenir + estimer l'utilisateur AVANT tout appel “gros”** : batch > ~50 tâches, crawl on-page d'un site entier, extraction backlinks massive, ou tout ce qui peut dépasser ~1 $ estimé. (Même logique que la règle Firecrawl.)34- **Tester d'abord la STRUCTURE en Sandbox** (gratuit, données bidons) avant de lancer en prod : base `https://sandbox.dataforseo.com/v3/`. Valide le corps de requête sans dépenser, puis bascule sur `https://api.dataforseo.com/v3/`.35- Chaque réponse renvoie un champ **`cost`** (total) + un `cost` par tâche → **le logguer/annoncer** après un appel réel.3637Détail des modes et arbitrages coût → `references/cost-and-modes.md`.3839## Choisir le bon mode (résumé)4041| Besoin | Mode | Pourquoi |42|---|---|---|43| 1 requête, tout de suite | **Live** (`.../live`) | Synchrone, réponse immédiate, mais + cher |44| Beaucoup de requêtes, pas pressé | **Task POST → Task GET** (Standard queue) | ~2× moins cher que Live, asynchrone |45| Mots-clés / concurrents / idées | **DataForSEO Labs** | Base de données interne DFS, pas de scraping live → rapide et bon marché |46| Volume de recherche / CPC | **Keywords Data** (Google Ads) | Source Google Ads officielle |4748Réflexe : pour de la **recherche de mots-clés ou d'analyse concurrentielle**, préfère **Labs** avant de scraper des SERP live (souvent 10× moins cher pour le même insight).4950## Quel endpoint pour quel job (carte rapide)5152- **SERP API** → positions/SERP réels (Google organic, maps, news, images, YouTube…). Scraping de résultats.53- **AI Optimization API** (GEO / AI search) → volume de mots-clés *dans les outils IA*, **mentions de marque dans les réponses IA** (AI Overviews, ChatGPT…), interrogation de LLM au **modèle choisi** (Claude/ChatGPT/Gemini/Perplexity) et scraping de résultats IA. Les **LLM Responses** exposent un champ **`fan_out_queries`** (Gemini/Perplexity + `web_search: true`) = le plus proche du **query fan-out** de Google. ⚠️ LLM Responses/Scraper **exécutent réellement le modèle → plus cher** que LLM Mentions / AI Keyword Data (base de données).54- **Keywords Data API** → search volume, CPC, competition, Google Trends, keywords-for-site/keywords-for-keywords.55- **DataForSEO Labs API** → keyword ideas, related/suggestions, ranked keywords d'un domaine, competitors, domain/page intersection, keyword difficulty, search intent, historical.56- **Backlinks API** → summary, backlinks, referring domains, anchors, bulk metrics, competitors, intersection.57- **On-Page API** → audit technique (crawl site), Lighthouse, `instant_pages` (1 page live), content parsing.58- **Content Analysis API** → brand mentions, sentiment, phrase/category trends.59- **Domain Analytics API** → technologies utilisées, WHOIS.60- **Merchant / App / Business Data** → Google Shopping & Amazon, App Store/Play, Google Business + reviews, Trustpilot/Tripadvisor.6162Carte détaillée (chemins exacts) → `references/endpoints.md`.63Recettes prêtes à l'emploi (dont patterns repris des workflows n8n de l'utilisateur) → `references/recipes.md`.6465## Rappels pratiques6667- Base prod : `https://api.dataforseo.com/v3/` — Base sandbox : `https://sandbox.dataforseo.com/v3/`.68- Auth : HTTP **Basic** (login + password, mêmes creds que dans n8n).69- Corps = **tableau JSON de tâches** (même pour une seule) : `[ { ...params } ]`.70- `location_code`/`language_code` : récupérer les codes via les endpoints `.../locations` et `.../languages` de chaque API (gratuits). Pour la France : `location_name: "France"`, `language_code: "fr"`.71- Endpoints gratuits utiles : `appendix/user_data` (solde), `appendix/errors`, listes locations/languages.
sergeesteves