unihra 1.7.0

Official Python Client for Unihra API (semantic SEO analysis & Knowledge Graph triplets)

Unihra Python SDK

SEO content analysis for your pages and competitors.
Compare content, find umbrella gaps, and get actionable recommendations using zone analysis and knowledge graphs.

English · Русский

---

Resources

Product	API reference	API key
unihra.ru	unihra.ru/docs	unihra.ru

---

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.
• 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):

Command	Includes
pip install "unihra[report]"	Excel export (pandas, openpyxl)
pip install "unihra[full]"	Report export + progress bar (tqdm)
pip install "unihra[mcp]"	MCP server for Cursor / Claude Code (requires Python 3.10+)

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", [])

print(f"Umbrella gap rows: {len(gaps)}")
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, 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.

1. Page structure

A list of pages (yours first, then competitors). Each item includes:

• url
• meta_tags — title, description, etc.
• content — h1_heading, heading_structure_raw (heading outline as text)
• metrics — e.g. char_count_no_spaces, uniqueness_percentage

2. Umbrella Analysis

Zone‑weighted comparison of lemmas vs your queries:

• lemma — base form
• competitor_avg_score, own_score — weighted scores (0.0 on your side often means missing or weak placement)
• gap — how far behind competitors you are (higher = higher priority)
• coverage_percent — share of competitors using the term in a strong context
• context_snippet — short example from competitors
• recommendation — suggested action (e.g. add to title/H1)

{
  "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"
}

3. Block comparison (lexical)

TF‑IDF style comparison:

• frequency, frequency_own_page, pct_target_comp_avg
• action_needed — add, increase, decrease, ok (after normalization for English)

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

4. N‑grams

Phrases (bigrams / trigrams) and how many competitor pages contain them.

• ngram, pages_count, etc.

5. Triplets — Knowledge Graph (extended mode, 5 credits)

Available only when triplet_analysis=True. Extracts subject → predicate → object facts from competitor texts and groups topical gaps by how many competitor sources cover them.

• entities[] — for each subject:
  • tier — importance bucket: core → main → additional → unique
  • triplets_count, sources_count
  • triplets[] — list of {predicate, object, sources[]} claims
• missing_triplets — subjects absent from your page, grouped by source coverage:
  • critical — appears on 3+ competitor sites
  • important — appears on 2 competitor sites
  • unique — appears on 1 competitor site
• stats — total_triplets, sources_with_content, per‑severity gap counts, gaps_total, batches.

{
  "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}
}

6. Anchors analysis

Comparison of link texts (anchors) used across pages.

• anchor — the link text
• frequency_own — occurrences on your page
• frequency_comp_avg — average occurrences across competitors
• pages_count — number of competitor pages using this anchor
• links — list of href URLs where this anchor text was found across all pages (own + competitors)

{
  "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

Option	Meaning
--own	Your page URL (required)
--comp	Competitor URL (repeat for multiple; at least one required)
--query	Target query (repeatable; recommended)
--lang	ru or en (default ru)
--cookies	Cookie string for your own page
--triplets	Enable Knowledge Graph extraction (cost: 5 credits instead of 1)
--save	Write .xlsx or .csv report
--retries	HTTP retry count
--verbose	Show progress
--no-style	Plain Excel without extra styling
--limits	Print API key balance and exit

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 — gaps, anchors, words, n‑grams, triplets (Knowledge Graph), or page structure. This lets you explore the full report section by section.

Available tools:

Tool	Purpose
unihra_health	Check that the service is reachable
unihra_get_limits	Check API key balance and daily credit limits
unihra_analyze	Primary tool: runs full analysis, saves to disk, returns result_id + summary. triplet_analysis=true enables the Knowledge Graph (5 credits)
unihra_list_results	List all saved analysis results on disk
unihra_delete_result	Delete a saved analysis result by result_id
unihra_get_page_structure	Fetch heading/meta report for a result_id
unihra_get_gaps	Get umbrella gaps and zone recommendations from a result_id
unihra_get_anchors	Get anchor text (link texts) analysis from a result_id
unihra_get_triplets	Get Knowledge Graph entities and topical gaps (only for results created with triplet_analysis=true)
unihra_get_word_actions	TF‑IDF words grouped by action
unihra_get_ngrams	Phrase list from a result_id

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"
      }
    }
  }
}

---

Unihra Team

unihra.ru · API docs