# SISTRIX API Endpoints and Reports Mapping

**Last Updated:** 2026-03-29

Single source of truth: endpoint → script → data file → report(s) → decision/action. Use this when adding or changing SISTRIX usage. See [SEO_DATA_MANAGEMENT.md](SEO_DATA_MANAGEMENT.md) for credit limits and [DATA_COLLECTION_SCRIPTS_INVENTORY.md](DATA_COLLECTION_SCRIPTS_INVENTORY.md) for script usage.

**Tools / Rechner:** Per-tool scripts (`collect-tool-keywords-sistrix.php`, `collect-tool-paa-questions.php`, `collect-tool-competitor-analysis.php`) and global `collect-tools-keywords-sistrix.php` are summarized in [../tools/DATA_COLLECTION_TOOLS.md](../tools/DATA_COLLECTION_TOOLS.md) (avoid duplicating the full table here).

**2026-02-16:** Collection limits increased for more data-driven content. See `v2/config/sistrix-collection-limits.php`: related_keywords 25, competitor_keywords 8, competitor_analysis_top_count 15, keyword_questions 25, secondary_paa 4.

**Keyword spelling (2026-02-23):** Keywords sent to SISTRIX must use proper German spelling (ü, ä, ö, ß). ASCII expansion (ue, ae, oe, ss) returns incorrect/low volume data. Scripts apply `getSearchKeywordForApi()` before API calls. See [PRIMARY_KEYWORD_MANAGEMENT_GUIDE.md](PRIMARY_KEYWORD_MANAGEMENT_GUIDE.md).

## Endpoints in Use

| Endpoint | Credits | Script(s) | Output file(s) | Report(s) / consumer | Drives decision |
|----------|---------|-----------|----------------|----------------------|-----------------|
| **keyword.seo.serpfeatures** | 1/kw | collect-post-serp-features.php, collect-faq-research-data.php | posts/{cat}/{slug}/data/serp-features.json, faq-research.json | SEO_REPORT, keyword-opportunities, FAQ generation, prioritization-data | PAA/snippet targeting, FAQ questions, SERP feature optimization |
| **keyword.seo.metrics** | 5/kw (batch) | collect-post-keywords-sistrix.php, collect-tools-keywords-sistrix.php, collect-template-keywords-sistrix.php | posts/{cat}/{slug}/data/keywords-sistrix.json; docs/content/tools/tools-keyword-sistrix.json; docs/systems/templates/template-data/{id}/data/keywords-sistrix.json | SEO_REPORT, keyword-opportunities, prioritization, priority dashboard; template content blocks | Keyword volume/difficulty, content focus, competition view |
| **keyword.seo** | 1/kw | collect-post-competitor-analysis.php, collect-template-competitor-analysis.php, **collect-tool-competitor-analysis.php** | posts/{cat}/{slug}/data/competitor-analysis.json; docs/systems/templates/template-data/{id}/data/competitor-analysis.json; **docs/content/tools/{slug}/data/competitor-analysis.json** | Competitor insights in docs; template SERP/content outline; **tools** competitive scrape | Who ranks for target keywords. **Unified limit:** 8 keywords for all posts (config: `competitor_keywords_count`). **Competitor count:** Collects top 15 competitor URLs per post (config: `competitor_analysis_top_count`). **Tools:** primary keyword per tool. |
| **keyword.seo.competition** | (see API) | collect-post-competition-levels.php | posts/{cat}/{slug}/data/competition-levels.json | prioritization-data, calculate-comprehensive-priority, priority dashboard | Low/avg competition → priority score, quick wins |
| **keyword.seo.searchintent** | 1/kw | collect-post-search-intent.php | posts/{cat}/{slug}/data/search-intent.json | prioritization-data, SEO_REPORT, keyword-opportunities | Content type and intent alignment |
| **keyword.questions** | (see API) | collect-post-paa-questions.php, collect-post-paa-questions-parallel.php, collect-template-paa-questions.php, **collect-tool-paa-questions.php** | posts/{cat}/{slug}/data/paa-questions.json; docs/systems/templates/template-data/{id}/data/paa-questions.json; **docs/content/tools/{slug}/data/paa-questions.json** | FAQ generation, PAA coverage; template FAQs; **tools** | PAA question list for FAQs. **Primary:** 25 questions (config: `keyword_questions_limit`). **Secondary PAA:** Top 4 secondary keywords (config: `secondary_paa_keywords_limit`). Use `--no-secondary-paa` to skip. **Tools:** primary keyword only. |
| **keyword.domain.seo** | 100 (with kw) | collect-post-serp-data.php, collect-high-value-serp-data.php, collect-competitor-keywords.php | domain-level-data/serp-results.json, posts/…/serp-data; competitor-keywords.json | High-value SERP data, competitor gaps | Domain visibility per keyword; use sparingly (Tier 1). **Optional Tier 2:** If used for Tier 2, cap e.g. 1,000 cr/month (top 5–10 posts, 1 kw each). See [MONITORING_RUNBOOK.md](MONITORING_RUNBOOK.md). |
| **domain.opportunities** | (see API) | analyze-topical-authority.php, collect-domain-opportunities.php | domain-level-data/domain-opportunities.json | aggregate-prioritization-data, keyword-opportunities, manual review checklist; **CONTENT_BACKLOG**, **CONTENT_GAP_ANALYSIS** (URLs classified by surface: Tools, Comparison, Blog, Product, etc.) | Content opportunities at domain level |
| **domain.ideas** | (see API) | collect-domain-content-ideas.php | domain-level-data/content-ideas.json | Content ideas for ideation | Content ideation |
| **domain.keywords** | (see API) | pull-sistrix-data.php | v2/data/blog/sistrix-domain-keywords.json | Internal linking, domain keyword list | Domain-level keyword set |
| **keyword.overview** | 1/kw | pull-sistrix-data.php | v2/data/blog/sistrix-keyword-positions.json | Keyword positions for domain | Position tracking for top keywords |
| **marketplace.keyword.search.ideas** | 1 cr/entry | collect-post-keywords-sistrix.php, collect-all-keywords-cross-post.php | keywords-sistrix.json (related_keywords) | Semantic keyword variations, FAQ research (getRelatedKeywords) | Broader keyword coverage. **Unified limit:** 25 ideas for all posts (config: `related_keywords_limit`). **Mode:** `include` (default, broad semantic), `same` (all words any order), `exact` (exact match). **For ambiguous lexikon terms** (e.g. "Generation Alpha" → returns iPad/Alexa with include): use `--mode=same` to get topic-relevant ideas. FAQ research filters related_keywords by primary-keyword substring. |
| **links.overview** | (see API) | collect-domain-backlinks.php | domain-level-data/backlinks.json | Backlink overview | Domain backlink health |
| **links.linktargets** | (see API) | collect-domain-backlinks.php | domain-level-data/backlinks.json | Backlink targets | Link target analysis |
| **links.linktexts** | (see API) | collect-domain-backlinks.php | domain-level-data/backlinks.json | Anchor text mix | Anchor text distribution |
| **domain.visibilityindex** | 1/entry | collect-domain-visibilityindex.php | domain-level-data/domain-visibilityindex.json | COLLECTION_HEALTH_DASHBOARD (Domain SEO health) | Domain visibility trend, health check |
| **domain.overview** | 5 | collect-domain-seo-overview.php | domain-level-data/domain-overview.json | COLLECTION_HEALTH_DASHBOARD (Domain SEO overview) | Visibility + SEO kw count + AdWords count in one call |
| **domain.ranking.distribution** | 1 | collect-domain-seo-overview.php | domain-level-data/domain-ranking-distribution.json | COLLECTION_HEALTH_DASHBOARD (Domain SEO overview) | Keywords per SERP page (page1–page10) for reporting/health |
| **domain.competitors.seo** | 1/competitor (limit=10) | collect-domain-seo-overview.php | domain-level-data/domain-competitors-seo.json | COLLECTION_HEALTH_DASHBOARD (Domain SEO overview) | Top 10 SEO competitors + similarity % for strategy |
| **domain.urls** | 1/entry returned | collect-competitor-lexikon-top-pages.php | lexikon-inventory/sistrix/{domain}-top-pages.json | LEXIKON_INVENTORY_REPORT, LEXIKON_CONTENT_GAPS | Competitor lexikon top-ranking URLs for content gap prioritization. **~3,000 cr** for 60 domains × 50 URLs; use `--max-domains=20` (~1,000 cr) or `--skip-existing` for batch runs. Run quarterly. **Audit:** `audit-sistrix-coverage.py` or `--list`. **Complement:** Sitemap fetch (`fetch-sitemap-terms.py`) is free—no credits. |

### Domain-level data directory

**Location:** `docs/content/blog/domain-level-data/`

Contains: domain-opportunities.json, content-ideas.json, backlinks.json, competitor-keywords.json, competitive-gaps.json, serp-results.json, **domain-visibilityindex.json** (from collect-domain-visibilityindex.php), **domain-overview.json**, **domain-ranking-distribution.json**, **domain-competitors-seo.json** (from collect-domain-seo-overview.php, ~16 cr/run). **Consumers:** aggregate-prioritization-data, generate-automated-reports, COLLECTION_HEALTH_DASHBOARD, [CONTENT_BACKLOG.md](CONTENT_BACKLOG.md) (generate-content-backlog.php), [CONTENT_GAP_ANALYSIS.md](CONTENT_GAP_ANALYSIS.md) (generate-content-gap-analysis.php), [competitive analysis report](reports/competitive-analysis-YYYY-Q.md) (generate-competitive-analysis.php). Domain-opportunities URLs are **classified by surface** (Tools, Comparison, Blog, Product, etc.) when generating the backlog and content-gap report so "Create new" lists only true content gaps. Tier 2 SISTRIX (serp-features, search-intent, competition-levels) uses same endpoints on Tier 2 posts; see [MONITORING_RUNBOOK.md](MONITORING_RUNBOOK.md).

## Endpoints Not Used (reference)

- **keyword.seo.traffic** (1/entry) – **Not used.** We rely on GA4 and GSC for traffic. Optional use for Tier 1 validation only; not implemented to keep credits for existing endpoints.

## Do NOT Add (Phase 3 – Value-Driven Optimization)

**Explicitly avoid these endpoints/uses to preserve credits for high-value data:**

| Endpoint / Use | Reason |
|----------------|--------|
| **keyword.domain.seo** (100 cr/kw) | GSC is free and sufficient for domain visibility per keyword. Use sparingly only if already in workflow (Tier 1). |
| **keyword.seo.traffic** | GA4 and GSC cover traffic. Redundant. |
| **Historical trends** (history=true) | Do not add unless explicitly needed for trend reports. Increases credit cost. |
| **More domain-level calls** (domain.opportunities, domain.ideas) beyond current monthly cadence | Run monthly; avoid increasing frequency unless audit shows underutilization. |
| **Data for posts that never consume it** | e.g. inside-ordio posts with no improvement workflow. Skip SISTRIX collection for posts that do not feed into content/FAQ scripts. |

## Gap-fill workflow

When posts are missing competition-levels, competitor-analysis, or search-intent:

1. **Audit:** Run `php v2/scripts/blog/audit-keyword-data-completeness.php` or `python3 v2/scripts/blog/audit-sistrix-usage.py`
2. **Fill gaps:** Run `php v2/scripts/blog/run-sistrix-gap-fill.php --data-type=TYPE` where TYPE is `competition-levels`, `competitor-analysis`, `search-intent`, or `all`
3. **Options:** `--limit=N`, `--tier=1|2|all`, `--dry-run`
4. **When to use:** Monthly audit, post-migration, or after adding new posts

See [SISTRIX_USAGE_AUDIT_REPORT.md](SISTRIX_USAGE_AUDIT_REPORT.md) for gap-fill runbook.

## Report actionability gaps (audit)

- **Priority dashboard** ([generate-priority-dashboard.php](v2/scripts/blog/generate-priority-dashboard.php)): Section 7 “Recommended actions (SISTRIX & data-driven)” added; derives from quick wins, competition, search intent, and PAA/FAQ gaps.
- **Per-post reports** ([generate-automated-reports.php](v2/scripts/blog/generate-automated-reports.php)): Keyword opportunities report now includes “Competition (SISTRIX)” and “Recommended actions (SISTRIX)” with 1–2 concrete recommendations (intent, low-competition, PAA/FAQ, featured snippet).
- **Aggregate**: [SEO_ACTION_LIST.md](SEO_ACTION_LIST.md) generated by [generate-seo-action-list.php](v2/scripts/blog/generate-seo-action-list.php) (monthly optional); aggregates top N posts with quick wins and 1–2 SISTRIX-backed actions per post.