# Franchise FDD & Filing Change Monitor (`n0geegee/franchise-filing-offer-change-monitor`) Actor Track the franchise pages you already know state filing portals, FDD libraries, and franchisor opportunity pages and get structured evidence when disclosure PDFs, filing status, fees, dates, territories, contacts, or application CTAs change. - **URL**: https://apify.com/n0geegee/franchise-filing-offer-change-monitor.md - **Developed by:** [Jurand Węgrzyn](https://apify.com/n0geegee) (community) - **Categories:** Lead generation, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $10.00 / 1,000 successful page checks 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 ## Franchise FDD & Filing Change Monitor Stop reopening the same franchise filing portals, FDD libraries, and franchisor opportunity pages just to check whether anything changed. Give the Actor the public pages you already track and receive structured before/after evidence when an FDD/PDF link, filing status, fee, date, territory, contact, or application call to action changes. Built for franchise counsel, compliance teams, due-diligence analysts, brokers, and competitive-intelligence teams. The Actor keeps persistent snapshots in Apify Key-Value Store, so a scheduled watchlist produces auditable dataset rows without an external database. Every target reports whether a baseline was created, the page stayed unchanged, meaningful content changed, policy blocked the request, or fetching failed. ### Why use this Actor? - Track known state registry, franchisor disclosure, and franchise opportunity pages. - Detect new or changed FDD/PDF links, filing language, dates, fees, territories, contacts, and calls to action. - Replace manual page checking with structured JSON, CSV, Excel, XML, RSS, or API output from Apify Dataset. - Keep deterministic hashes, diffs, and persistent history without an external database. - Pay only for successfully checked pages. Failed or policy-blocked fetches are not charged. This is a known-URL watchlist and change-intelligence tool—not a crawler of every state registry, not an FDD legal-review service, and not legal advice. ### Quick start ```json { "targets": [ { "url": "https://www.franchisedirect.com/", "label": "Franchise Direct", "pageRole": "franchise" } ], "runMode": "compare_with_previous", "snapshotNamespace": "competitor-watch", "maxPages": 20, "requestDelayMs": 1000, "respectRobotsTxt": true } ```` The first successful check creates a baseline. Later runs compare the current normalized page text with the previous snapshot. For continuous monitoring, create an Apify Schedule for the same input. Keep `snapshotStoreName` and `snapshotNamespace` unchanged across scheduled runs. ### Input #### `targets` An array of 1–50 public HTTP(S) pages. Each target supports: - `url` — required public URL. - `label` — optional human-readable label. - `pageRole` — one of `pricing`, `courses`, `camps`, `open_days`, `franchise`, `locations`, `contact`, `recruitment`, or `generic_offer`. Private, loopback, link-local, reserved, credential-bearing, and non-HTTP URLs are rejected before fetching. #### Persistence - `runMode`: `compare_with_previous` or `baseline_only`. - `snapshotStoreName`: named Apify Key-Value Store used for normalized snapshots. - `snapshotNamespace`: separates independent campaigns inside the store. #### Network and noise controls - `maxPages`: maximum targets processed, up to 50. - `maxBytesPerPage`: response-size limit, up to 2 MB. - `timeoutSecs`: timeout for each page. - `requestDelayMs`: delay between requests. - `respectRobotsTxt`: skip pages disallowed by robots.txt. - `noisePatterns`: regular expressions for routine text to remove before comparison. - `blockedUrlPatterns`: additional URL patterns to skip. ### Output Each target produces one dataset row. Important fields: - `status`: `baseline_created`, `unchanged`, `changed`, `blocked_by_policy`, or `fetch_failed`. - `addedText` and `removedText`: compact line-level diff, capped to keep output manageable. - `detectedEvents`: categorized changes with severity, confidence, evidence, and old/new values. - `offerSignals`: PDF document links, prices/fees, dates, locations, contacts, and calls to action currently visible. - `contentHashPrevious` and `contentHashCurrent`: SHA-256 hashes for deterministic comparison. - `snapshotKeyCurrent`: persistent Apify KVS reference. - `error`: explicit failure reason when a page could not be checked. Example event: ```json { "category": "price", "severity": "high", "confidence": 0.91, "summary": "Price-like value or pricing wording changed or appeared.", "evidence": ["Tuition fee: £125"], "oldValue": "£100", "newValue": "£125" } ``` ### Pricing **$0.01 per successfully checked page.** There is no charge event for `fetch_failed` or `blocked_by_policy` results. The Actor uses a lightweight HTTP-first runtime; no proxy or browser cost is added by default. ### Limitations - Public, server-rendered HTML pages only. - PDF links found on monitored HTML pages are preserved and compared. The current version does not parse the contents of PDF files. - No JavaScript rendering, login, CAPTCHA solving, or private-page access. - Dynamic widgets rendered only in the browser may not appear in extracted text. - Detection is deterministic pattern matching, not an AI interpretation. - Website structures and access policies can change. Review failed rows and respect each site's terms and applicable law. ### Privacy and responsible use Use the Actor only for pages you are permitted to access and monitor. It intentionally rejects local/private network destinations and URLs containing credentials. Snapshots and datasets are stored in the Apify account running the Actor and follow that account's retention and access settings. The output is monitoring data, not legal, regulatory, or investment advice. Verify filing status and disclosure documents with the responsible authority before relying on them. ### Support When reporting a problem, include the run ID, target domain, row status, and sanitized error message. Never include passwords, session cookies, or private URLs. # Actor input Schema ## `targets` (type: `array`): Known public HTTP(S) franchise registry, filing, FDD-link, disclosure, or opportunity pages. ## `runMode` (type: `string`): Create/refresh a baseline only, or compare each page with its previous persistent snapshot. ## `snapshotNamespace` (type: `string`): Use a different namespace for each independent monitoring campaign. ## `snapshotStoreName` (type: `string`): Named Apify Key-Value Store used to persist normalized page snapshots between runs. ## `maxPages` (type: `integer`): Hard cap on successfully attempted targets in this run. ## `maxBytesPerPage` (type: `integer`): Maximum bytes downloaded from one page. ## `requestDelayMs` (type: `integer`): Polite delay in milliseconds between target requests. ## `timeoutSecs` (type: `integer`): HTTP timeout for each target page in seconds. ## `respectRobotsTxt` (type: `boolean`): Skip pages disallowed by the target site's robots.txt. ## `noisePatterns` (type: `array`): Case-insensitive regular expressions for lines to exclude before comparison, such as cookie banners or timestamps. ## `blockedUrlPatterns` (type: `array`): Case-insensitive regular expressions for URL paths that should be skipped. ## `includeSignalsWhenUnchanged` (type: `boolean`): Include documents, fees, dates, contacts, locations, and CTAs even when no change is detected. ## Actor input object example ```json { "targets": [ { "url": "https://www.franchisedirect.com/", "label": "Franchise Direct", "pageRole": "franchise" } ], "runMode": "compare_with_previous", "snapshotNamespace": "default", "snapshotStoreName": "franchise-filing-offer-monitor-state", "maxPages": 20, "maxBytesPerPage": 2000000, "requestDelayMs": 1000, "timeoutSecs": 30, "respectRobotsTxt": true, "noisePatterns": [ "cookie", "last updated", "©", "privacy policy" ], "blockedUrlPatterns": [ "/login", "/account", "/cart", "/checkout", "/admin" ], "includeSignalsWhenUnchanged": true } ``` # 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("n0geegee/franchise-filing-offer-change-monitor").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("n0geegee/franchise-filing-offer-change-monitor").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 n0geegee/franchise-filing-offer-change-monitor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=n0geegee/franchise-filing-offer-change-monitor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Franchise FDD & Filing Change Monitor", "description": "Track the franchise pages you already know state filing portals, FDD libraries, and franchisor opportunity pages and get structured evidence when disclosure PDFs, filing status, fees, dates, territories, contacts, or application CTAs change.", "version": "1.0", "x-build-id": "Kc7Uy9EdSFcSqfL3y" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/n0geegee~franchise-filing-offer-change-monitor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-n0geegee-franchise-filing-offer-change-monitor", "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/n0geegee~franchise-filing-offer-change-monitor/runs": { "post": { "operationId": "runs-sync-n0geegee-franchise-filing-offer-change-monitor", "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/n0geegee~franchise-filing-offer-change-monitor/run-sync": { "post": { "operationId": "run-sync-n0geegee-franchise-filing-offer-change-monitor", "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", "required": [ "targets" ], "properties": { "targets": { "title": "Pages to monitor", "minItems": 1, "maxItems": 50, "type": "array", "description": "Known public HTTP(S) franchise registry, filing, FDD-link, disclosure, or opportunity pages.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "title": "Public page URL", "description": "A public http:// or https:// URL. Private networks, localhost, credentials, and non-HTTP schemes are rejected.", "type": "string", "editor": "textfield" }, "label": { "title": "Label", "description": "Human-readable name included in the output row.", "type": "string", "editor": "textfield" }, "pageRole": { "title": "Page role", "description": "Business context used to classify detected changes.", "type": "string", "enum": [ "pricing", "courses", "camps", "open_days", "franchise", "locations", "contact", "recruitment", "generic_offer" ], "enumTitles": [ "Pricing", "Courses", "Camps", "Open days", "Franchise", "Locations", "Contact", "Recruitment", "Generic offer" ], "default": "generic_offer", "editor": "select" } } }, "default": [ { "url": "https://www.franchisedirect.com/", "label": "Franchise Direct", "pageRole": "franchise" } ] }, "runMode": { "title": "Run mode", "enum": [ "compare_with_previous", "baseline_only" ], "type": "string", "description": "Create/refresh a baseline only, or compare each page with its previous persistent snapshot.", "default": "compare_with_previous" }, "snapshotNamespace": { "title": "Snapshot namespace", "minLength": 1, "maxLength": 100, "type": "string", "description": "Use a different namespace for each independent monitoring campaign.", "default": "default" }, "snapshotStoreName": { "title": "Persistent snapshot store", "minLength": 1, "maxLength": 63, "type": "string", "description": "Named Apify Key-Value Store used to persist normalized page snapshots between runs.", "default": "franchise-filing-offer-monitor-state" }, "maxPages": { "title": "Maximum pages per run", "minimum": 1, "maximum": 50, "type": "integer", "description": "Hard cap on successfully attempted targets in this run.", "default": 20 }, "maxBytesPerPage": { "title": "Maximum response size", "minimum": 10000, "maximum": 2000000, "type": "integer", "description": "Maximum bytes downloaded from one page.", "default": 2000000 }, "requestDelayMs": { "title": "Delay between requests", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Polite delay in milliseconds between target requests.", "default": 1000 }, "timeoutSecs": { "title": "Per-page timeout", "minimum": 5, "maximum": 60, "type": "integer", "description": "HTTP timeout for each target page in seconds.", "default": 30 }, "respectRobotsTxt": { "title": "Respect robots.txt", "type": "boolean", "description": "Skip pages disallowed by the target site's robots.txt.", "default": true }, "noisePatterns": { "title": "Noise patterns", "type": "array", "description": "Case-insensitive regular expressions for lines to exclude before comparison, such as cookie banners or timestamps.", "items": { "type": "string" }, "default": [ "cookie", "last updated", "©", "privacy policy" ] }, "blockedUrlPatterns": { "title": "Additional blocked URL patterns", "type": "array", "description": "Case-insensitive regular expressions for URL paths that should be skipped.", "items": { "type": "string" }, "default": [ "/login", "/account", "/cart", "/checkout", "/admin" ] }, "includeSignalsWhenUnchanged": { "title": "Extract signals from unchanged pages", "type": "boolean", "description": "Include documents, fees, dates, contacts, locations, and CTAs even when no change is detected.", "default": true } } }, "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 } } } } } } } } } } ```