Unihra Python SDK

Features

• Umbrella Analysis (zones) — weights words by where they appear (title, H1–H6, body) and distance to your target queries, with concrete recommendations (for example, what to add to title or headings).
• Page structure — headings, meta tags, and content metrics for your URL and each competitor URL.
• Word comparison (TF‑IDF) — suggested actions per term (add, increase, decrease, ok).
• Phrases (n‑grams) — recurring phrases across competitor pages.
• Knowledge Graph (triplets) — extended mode that mines subject → predicate → object facts from competitor texts and surfaces topical gaps (critical / important / unique).
• Anchors (link texts) — identify missing internal and external link texts used by competitors to rank.
• Page coverage — see which requested URLs were included in the analysis and which were not.
• Cookies — optional per‑URL cookie strings for pages behind login or gates.
• Streaming — the client handles the live analysis stream and waits for completion.
• Retries — optional HTTP retries with backoff for unstable networks.
• Reports — export multi‑sheet Excel reports with formatting (optional dependencies).
• Progress — optional progress bar in notebooks when tqdm is installed.

💳 Cost model. Standard analysis = 1 credit per call. Extended analysis with triplet_analysis=true (Knowledge Graph) = 5 credits per call. The default is the cheap path.

Installation

pip install unihra

Optional bundles (install what you need):

Or install pieces manually, for example: pip install pandas openpyxl tqdm.

Quick start

1. Run an analysis

Pass queries — the search intents you care about — so zone recommendations and gap analysis are meaningful.

from unihra import UnihraClient

client = UnihraClient(api_key="YOUR_API_KEY", max_retries=3)

result = client.analyze(
    own_page="https://example.com/my-product",
    competitors=[
        "https://competitor.com/top-product",
        "https://market-leader.com/item",
    ],
    queries=["buy widget", "best widgets 2026"],
    lang="en",
    url_cookies={
        "https://example.com/my-product": "session_id=abc123; auth=true",
    },
    triplet_analysis=False,  # set True for the Knowledge Graph (5 credits)
    verbose=True,
)

gaps = result.get("umbrella_analysis", [])
pages = result.get("page_structure", [])
page_status = result.get("_meta", {}).get("page_status", {})
failed = page_status.get("failed", [])

print(f"Umbrella gap rows: {len(gaps)}")
print(f"Pages not included: {len(failed)}")
for p in pages:
    print(p["url"], "—", p["meta_tags"]["title"])

To enable the Knowledge Graph (extended fact‑coverage analysis):

result = client.analyze(
    own_page="https://example.com/my-product",
    competitors=["https://competitor.com/top-product"],
    queries=["buy widget"],
    lang="en",
    triplet_analysis=True,   # 5 credits — adds knowledge graph + topical gaps
    verbose=True,
)

triplets = result.get("triplets_analysis", {})
print("Total facts:", triplets.get("stats", {}).get("total_triplets"))
print("Critical topical gaps:", len(triplets.get("missing_triplets", {}).get("critical", [])))

2. Save an Excel report

client.save_report(result, "seo_report.xlsx")

Sheet names: Page Structure, Umbrella Gaps, Word Analysis, N‑Grams, Anchors, Parsed Pages, Failed Pages, and — when triplet_analysis=True — Triplets and Triplets Gaps.

What's in the result

The SDK returns a Python dictionary aligned with the API. Keys are normalized to snake_case.

{
  "lemma": "battery",
  "competitor_avg_score": 10.5,
  "own_score": 0.0,
  "gap": 10.5,
  "coverage_percent": 80.0,
  "context_snippet": "long lasting battery life",
  "recommendation": "Add to Title/H1"
}

{
  "word": "price",
  "frequency": 12.5,
  "pct_target_comp_avg": 2.5,
  "action_needed": "increase",
  "present_on_own_page": true
}

{
  "entities": [
    {
      "subject": "Mineral Wool",
      "tier": "core",
      "triplets_count": 14,
      "sources_count": 7,
      "triplets": [
        {"predicate": "operating temperature", "object": "up to 700°C",
         "sources": ["comp1.com", "comp4.com"]}
      ]
    }
  ],
  "missing_triplets": {"critical": [...], "important": [...], "unique": [...]},
  "stats": {"total_triplets": 412, "gaps_total": 74}
}

{
  "anchor": "buy online",
  "frequency_own": 0,
  "frequency_comp_avg": 5.0,
  "pages_count": 3,
  "links": [
    "https://competitor.com/products/buy",
    "https://other-competitor.com/shop"
  ]
}

Command line

python -m unihra \
  --key "YOUR_API_KEY" \
  --own "https://mysite.com" \
  --comp "https://comp1.com" \
  --comp "https://comp2.com" \
  --query "main keyword" \
  --cookies "session=secret_123" \
  --triplets \
  --save report.xlsx \
  --verbose

You can omit --key if the environment variable UNIHRA_API_KEY is set.
Without --save and without --verbose, JSON is printed to the terminal.

Cursor, Claude, and other MCP clients

The optional MCP server lets compatible assistants call Unihra as tools instead of fetching pages themselves.

1. Install: pip install "unihra[mcp]" (Python 3.10+).
2. Set your API key: environment variable UNIHRA_API_KEY, or pass --key when starting the server.
3. Start: python -m unihra.mcp_server or the command unihra-mcp.
4. Point your client's MCP settings at that Python and module (see below).

How it works: The unihra_analyze tool runs the full analysis and saves the result locally, returning only a result_id and a compact summary. You then use unihra_get_* tools with the result_id to retrieve specific data sections on demand — page coverage, gaps, anchors, words, n‑grams, triplets (Knowledge Graph), or page structure. This lets you explore the full report section by section.

Available tools:

Example MCP configuration (adjust paths to your Python executable):

{
  "mcpServers": {
    "unihra": {
      "command": "python",
      "args":["-m", "unihra.mcp_server"],
      "env": {
        "UNIHRA_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}