Navinspire-ia SEO Data Provider
Use the seo engine's serp_snapshot and serp_history actions first. They enforce source and confidence on every result and write atomic append-only history. Never invent volume/KD/backlink counts or positions. If no keys are present, preserve the returned data_gap and continue with qualitative research.
When to use
- Keyword maps that need monthly volume or KD
- Competitor backlink / overlap snapshots
- SERP feature checks at scale
When not to use
- Keys missing (do not fake numbers)
- Pure on-page copy edits
Credentials (never print secrets)
| Provider | Env | Notes |
|---|---|---|
| DataForSEO | DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD |
Basic auth to api.dataforseo.com |
| Semrush | SEMRUSH_API_KEY |
Query param key= |
Prefer DataForSEO when both exist. Prefer Semrush if only that key exists.
Check presence with printenv DATAFORSEO_LOGIN SEMRUSH_API_KEY - report only which are set, never values.
DataForSEO examples
curl -s -u "$DATAFORSEO_LOGIN:$DATAFORSEO_PASSWORD" \
"https://api.dataforseo.com/v3/keywords_data/google_ads/search_volume/live" \
-H "Content-Type: application/json" \
-d '[{"keywords":["crm logiciel","outil crm"],"location_code":2250,"language_code":"fr"}]'
curl -s -u "$DATAFORSEO_LOGIN:$DATAFORSEO_PASSWORD" \
"https://api.dataforseo.com/v3/serp/google/organic/live/advanced" \
-H "Content-Type: application/json" \
-d '[{"keyword":"crm logiciel","location_code":2250,"language_code":"fr","depth":10}]'
Parse with jq/python; save raw JSON under seo/api/ and a clean table for the report. Cite provider + date in the keyword map columns.
Semrush examples
curl -s "https://api.semrush.com/?type=phrase_these&key=$SEMRUSH_API_KEY&phrase=crm%20logiciel&database=fr&export_columns=Ph,Nq,Kd"
curl -s "https://api.semrush.com/?type=backlinks_overview&key=$SEMRUSH_API_KEY&target=example.com&target_type=root_domain"
Workflow
- Call
seoactionserp_snapshotwithprovider=dataforseoorprovider=semrush. - If credentials are absent, preserve
status=data_gap; do not add numeric results. - Read trends through
seoactionserp_history; the store is append-only. - Use direct API calls only for unsupported metrics, then retain source, date, and confidence.
- Never log full API keys; redact in reports.
Rules
- One source of truth per metric cell (provider name in Notes).
- Respect API rate limits; batch keywords.
- On HTTP/auth errors: report failure, fall back qualitative - do not invent.
Anti-patterns
- Pasting API keys into markdown reports
- Mixing Semrush KD with invented volumes