# Internal Link Opportunity Mapper (`junipr/internal-link-opportunity-mapper`) Actor Suggest internal link opportunities based on crawl text, pages, topics, anchors, and site graph context. - **URL**: https://apify.com/junipr/internal-link-opportunity-mapper.md - **Developed by:** [junipr](https://apify.com/junipr) (community) - **Categories:** SEO tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $6.50 / 1,000 source processeds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Internal Link Opportunity Mapper ### Store Positioning **Store title:** Internal Link Opportunity Mapper **Short description:** Suggest internal link opportunities based on crawl text, pages, topics, anchors, and site graph context. **SEO title:** Internal Link Opportunity Mapper — evidence-backed report and intelligence workflow **SEO description:** Suggest internal link opportunities based on crawl text, pages, topics, anchors, and site graph context. Use it to turn sources into decision-ready rollups, executive summaries, and evidence-backed recommendations. **Categories:** SEO_TOOLS **Keywords:** internal, link, opportunity, mapper, premium report/intelligence actor ### Fixed-Inclusive PPE Pricing This actor uses pay-per-event pricing. Event prices include Apify platform usage; users are not expected to pay a separate platform-usage pass-through charge for the configured pricing model. - Tier: R1 — Premium report/intelligence actor - Primary event: `source-processed` at $0.00892 base - Default max charge: $25.00 - Store discounts: FREE/BRONZE base, SILVER discounted, GOLD deepest approved discount Event set: - `actor-start`: base $0.02000, GOLD $0.01600. Internal Link Opportunity Mapper: charged when actor start is completed. The price includes Apify platform usage; no separate usage pass-through is intended. - `source-processed`: base $0.00892, GOLD $0.00714. Internal Link Opportunity Mapper: charged when source processed is completed. The price includes Apify platform usage; no separate usage pass-through is intended. - `finding-emitted`: base $0.00892, GOLD $0.00714. Internal Link Opportunity Mapper: charged when finding emitted is completed. The price includes Apify platform usage; no separate usage pass-through is intended. - `report-section-generated`: base $0.03600, GOLD $0.02880. Internal Link Opportunity Mapper: charged when report section generated is completed. The price includes Apify platform usage; no separate usage pass-through is intended. - `executive-report-generated`: base $0.25000, GOLD $0.20000. Internal Link Opportunity Mapper: charged when executive report generated is completed. The price includes Apify platform usage; no separate usage pass-through is intended. ### Public Task Concepts - Build an Internal Link Opportunity stakeholder brief from source rows - Prioritize Internal Link Opportunity findings with evidence and confidence - Summarize Internal Link Opportunity metrics into recommended actions - Prepare an Internal Link Opportunity source table with uncertainty notes - Export Internal Link Opportunity decision rows for review Suggest evidence-backed internal links from supplied page and site-graph context. ### What This Actor Does Internal Link Opportunity Mapper evaluates a proposed source page, target page, and anchor against supplied page text or topic labels. It measures topical overlap, verifies that the anchor is grounded in the source context, checks same-site identity, and detects self-links or links that already exist. Each result includes a `linkOpportunityRows` evidence object with normalized source and target topics, overlap, existing links, same-origin status, anchor support, outbound-link count, and target inbound-link count. Optional JSON and Markdown reports summarize the resulting findings. ### What This Actor Does Not Do - It does not crawl an entire site or choose target pages without supplied graph context. - Fetching a source URL can supply source text, but target text, target topics, and graph evidence must still be provided. - It does not render JavaScript or bypass access controls. - It does not guarantee that a suggested link improves rankings; the output is editorial and technical evidence for review. ### Best Use Cases - validate links proposed during content refreshes - find duplicate, self, external, or weakly related targets - verify anchor text against nearby source wording - prioritize underlinked target pages with supplied graph counts - export internal-link QA evidence for editors or clients ### Input Fields | Field | Type | Default | Notes | | --- | --- | --- | --- | | `records` | array | two built-in records | Proposed opportunities. Put graph and text evidence in each record's `metadata`. | | `urls` | array | `[]` | Explicit source URLs; these override schema-populated default records. | | `fetchUrls` | boolean | `false` | Fetch source text for URL records. | | `fetchTimeoutMs` | integer | `12000` | Per-request timeout, capped at 30 seconds. | | `watchTerms` | array | anchor/link terms | Terms retained in the general result summary. | | `includeReport` | boolean | `true` | Writes JSON and Markdown report artifacts. | | `maxItems` | integer | `2` | Result cap; maximum 50. | | `maxTextBytes` | integer | `500000` | Text cap per record. | Important metadata fields are `sourcePage`, `targetPage`, `anchorSuggestion`, `sourceText` or `sourceTopics`, `targetText` or `targetTopics`, `existingLinks`, `outboundLinkCount`, and `targetInboundLinkCount`. ### Example Input ```json { "records": [ { "sourceId": "roof-guide-link", "sourceUrl": "https://example.com/guides/roof-maintenance", "title": "Roof maintenance guide", "metadata": { "sourcePage": "https://example.com/guides/roof-maintenance", "targetPage": "https://example.com/services/roof-repair", "anchorSuggestion": "roof repair service", "sourceText": "Inspect roof damage and choose a roof repair service before leaks spread.", "targetText": "Roof repair service for storm damage and active leaks.", "existingLinks": ["https://example.com/contact"], "targetInboundLinkCount": 1 } } ], "maxItems": 1, "includeReport": true } ```` ### Output Evidence The top-level row contains source identity, status, severity, score, findings, recommendations, timestamps, and the primary PPE event. `metadata.sourceSpecific.linkOpportunityRows[0]` contains the normalized link decision evidence. A valid opportunity emits `link-opportunity`; invalid cases can emit `already-linked`, `self-link`, `external-target`, `low-topic-overlap`, `generic-anchor`, or `anchor-not-grounded`. ### Cost Control - Start with one or two supplied opportunities. - Keep URL fetching off when page text is already available. - Supply explicit topic labels for deterministic large-text comparisons. - Disable report artifacts when only dataset rows are needed. ### Public Task Examples - build a stakeholder brief from link-opportunity evidence - prioritize contextual links with topic and graph support - summarize same-site and duplicate-link findings - prepare a source-target evidence table - export decision rows for editorial review ### Limitations Topic extraction is lexical and does not replace semantic search, embeddings, or editorial judgment. Relative URLs are compared against the supplied source page. JavaScript-rendered links, crawl discovery, and sitewide PageRank calculations require separate crawl data. ### Source And Safety Notes Use public or permissioned pages. Do not include credentials, private user data, or restricted content. Treat recommendations as QA evidence and review each insertion in its paragraph context. ### Changelog - 2026-07-10: Added topic-overlap, anchor-grounding, same-origin, duplicate-link, and graph evidence with expanded regression coverage. # Actor input Schema ## `records` (type: `array`): Records, snapshots, or source observations to process. Defaults to a tiny deterministic fixture. ## `urls` (type: `array`): Optional URLs reserved for live fetching when Fetch URLs is true. ## `fetchUrls` (type: `boolean`): Fetch sourceUrl text over HTTP. Default is false for deterministic local runs. ## `fetchTimeoutMs` (type: `integer`): Timeout for each bounded HTTP request. ## `watchTerms` (type: `array`): Keywords or topics used to flag relevant records. ## `includeReport` (type: `boolean`): Write JSON and Markdown report artifacts to the key-value store. ## `maxItems` (type: `integer`): Maximum records to process in one run. ## `maxTextBytes` (type: `integer`): Maximum searchable text bytes per record. ## `dryRun` (type: `boolean`): Validate input and write a dry-run summary without PPE charges or dataset output. ## `debug` (type: `boolean`): Enable debug logging. ## Actor input object example ```json { "records": [ { "sourceId": "link-opp-1", "sourceUrl": "https://example.com/blog/roof-maintenance", "title": "Roof maintenance article to repair service page", "description": "Topic gap found. Suggested anchor internal link from roof maintenance article to roof repair service page.", "category": "internal links", "keywords": [ "anchor", "internal link" ], "metadata": { "sourcePage": "/blog/roof-maintenance", "targetPage": "/services/roof-repair", "anchorSuggestion": "roof repair service", "score": 82, "sourceText": "Inspect roof damage and choose a roof repair service before leaks spread.", "targetText": "Roof repair service for storm damage, active leaks, and inspection findings.", "existingLinks": [ "/contact" ], "targetInboundLinkCount": 1 } }, { "sourceId": "link-opp-thin", "sourceUrl": "https://example.com/blog/thin", "title": "Unmapped topic gap", "description": "Potential internal link opportunity without targetPage metadata.", "category": "internal links", "keywords": [ "topic gap" ], "metadata": { "sourcePage": "/blog/thin", "anchorSuggestion": "service guide" } } ], "urls": [], "fetchUrls": false, "fetchTimeoutMs": 12000, "watchTerms": [ "anchor", "topic gap", "internal link" ], "includeReport": true, "maxItems": 2, "maxTextBytes": 500000, "dryRun": false, "debug": false } ``` # Actor output Schema ## `results` (type: `string`): Structured result rows in the default dataset. ## `summary` (type: `string`): Summary JSON in the key-value store when includeReport is enabled. ## `markdownReport` (type: `string`): Markdown report in the key-value store when includeReport is enabled. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("junipr/internal-link-opportunity-mapper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("junipr/internal-link-opportunity-mapper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call junipr/internal-link-opportunity-mapper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=junipr/internal-link-opportunity-mapper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Internal Link Opportunity Mapper", "description": "Suggest internal link opportunities based on crawl text, pages, topics, anchors, and site graph context.", "version": "1.0", "x-build-id": "vIIRQgdMeg3tl2UsL" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/junipr~internal-link-opportunity-mapper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-junipr-internal-link-opportunity-mapper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/junipr~internal-link-opportunity-mapper/runs": { "post": { "operationId": "runs-sync-junipr-internal-link-opportunity-mapper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/junipr~internal-link-opportunity-mapper/run-sync": { "post": { "operationId": "run-sync-junipr-internal-link-opportunity-mapper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "records": { "title": "Records To Check", "type": "array", "description": "Records, snapshots, or source observations to process. Defaults to a tiny deterministic fixture.", "items": { "type": "object" }, "default": [ { "sourceId": "link-opp-1", "sourceUrl": "https://example.com/blog/roof-maintenance", "title": "Roof maintenance article to repair service page", "description": "Topic gap found. Suggested anchor internal link from roof maintenance article to roof repair service page.", "category": "internal links", "keywords": [ "anchor", "internal link" ], "metadata": { "sourcePage": "/blog/roof-maintenance", "targetPage": "/services/roof-repair", "anchorSuggestion": "roof repair service", "score": 82, "sourceText": "Inspect roof damage and choose a roof repair service before leaks spread.", "targetText": "Roof repair service for storm damage, active leaks, and inspection findings.", "existingLinks": [ "/contact" ], "targetInboundLinkCount": 1 } }, { "sourceId": "link-opp-thin", "sourceUrl": "https://example.com/blog/thin", "title": "Unmapped topic gap", "description": "Potential internal link opportunity without targetPage metadata.", "category": "internal links", "keywords": [ "topic gap" ], "metadata": { "sourcePage": "/blog/thin", "anchorSuggestion": "service guide" } } ] }, "urls": { "title": "URLs To Fetch", "type": "array", "description": "Optional URLs reserved for live fetching when Fetch URLs is true.", "items": { "type": "string" }, "default": [] }, "fetchUrls": { "title": "Fetch URLs", "type": "boolean", "description": "Fetch sourceUrl text over HTTP. Default is false for deterministic local runs.", "default": false }, "fetchTimeoutMs": { "title": "Fetch Timeout (ms)", "minimum": 1000, "maximum": 30000, "type": "integer", "description": "Timeout for each bounded HTTP request.", "default": 12000 }, "watchTerms": { "title": "Watch Terms", "type": "array", "description": "Keywords or topics used to flag relevant records.", "items": { "type": "string" }, "default": [ "anchor", "topic gap", "internal link" ] }, "includeReport": { "title": "Include Report Artifacts", "type": "boolean", "description": "Write JSON and Markdown report artifacts to the key-value store.", "default": true }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum records to process in one run.", "default": 2 }, "maxTextBytes": { "title": "Max Text Bytes", "minimum": 100, "maximum": 2000000, "type": "integer", "description": "Maximum searchable text bytes per record.", "default": 500000 }, "dryRun": { "title": "Dry Run", "type": "boolean", "description": "Validate input and write a dry-run summary without PPE charges or dataset output.", "default": false }, "debug": { "title": "Debug Logs", "type": "boolean", "description": "Enable debug logging.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```