Structured API & Web Change Feed

Typed changes, not screenshots

Structured API & Web Change Feed turns JSON, XML, HTML, and text changes into deterministic events that automation can consume directly. Track exactly what changed, where it changed, whether a value changed type, and how far a numeric value moved—without parsing screenshots or natural-language summaries.

Use it for API contract monitoring, competitor pricing, catalog changes, XML feeds, automation pipelines, MCP tools, and scheduled checks.

What this Actor produces

• Exact ADD, REMOVE, and REPLACE operations with stable paths.
• Typed before and after values with beforeType, afterType, and typeChanged.
• Exact decimal delta and percentChange metadata for numeric changes.
• Identity-aware JSON array comparison that ignores item reordering.
• JSON Pointer, XPath, and CSS selector scoping.
• A versioned event contract with schemaVersion: 1.

Quick start

Run the Actor with one or more public HTTP targets:

{
  "monitorId": "competitor-pricing",
  "targets": [
    {
      "id": "products-api",
      "url": "https://example.com/api/products",
      "type": "JSON",
      "ignoreJsonPointers": ["/generatedAt", "/requestId"],
      "arrayIdentityKeys": {
        "/products": "id"
      }
    }
  ]
}

The first successful run creates a baseline and emits BASELINE_CREATED with changed=false. Run the same monitor again to receive UNCHANGED or a typed change event.

Example numeric change

{
  "path": "/products/@id=pro/price",
  "operation": "REPLACE",
  "before": 19,
  "after": 25,
  "beforeType": "NUMBER",
  "afterType": "NUMBER",
  "typeChanged": false,
  "numeric": {
    "delta": 6,
    "percentChange": 31.578947
  }
}

Example API type change

{
  "path": "/id",
  "operation": "REPLACE",
  "before": 123,
  "after": "123",
  "beforeType": "NUMBER",
  "afterType": "STRING",
  "typeChanged": true,
  "numeric": null
}

JSON change detection

Object keys and decimal values are canonicalized before comparison, so formatting and key order do not create false positives. Use jsonPointer to monitor a subtree and ignoreJsonPointers to exclude volatile fields.

For arrays of entities, map an array path to a direct identity field:

{
  "arrayIdentityKeys": {
    "/products": "id"
  }
}

Product order changes then remain UNCHANGED, while a product update is reported under a stable path such as /products/@id=42/price. Duplicate or missing identities produce explicit error events rather than silently falling back to index comparison.

XML, HTML, and text

• XML: scope content with XPath. The parser removes comments, sorts attributes deterministically, and blocks DOCTYPE, external entities, external DTDs, and external schemas.
• HTML: select visible content with cssSelector and remove volatile elements with ignoreSelectors. Scripts, styles, templates, and comments are excluded by default.
• Text: normalize line endings and trailing whitespace while preserving meaningful line structure.

Automation on Apify

Each target produces exactly one item in the run's default Dataset. Baselines are stored across runs in the named Key-Value Store structured-api-web-change-feed-state-v1.

Use Apify schedules for recurring checks, access events through the Dataset API, or connect runs to integrations and automation platforms. Stable event fields mean downstream systems do not need to parse prose.

Reliability and security

• Supports ETag, Last-Modified, and HTTP 304 responses.
• Revalidates SSRF rules after every redirect.
• Limits redirects, request duration, retries, concurrency, and decompressed body size.
• Blocks private, loopback, link-local, and metadata addresses, URL credentials, and binary content.
• HTTP and network errors never overwrite the last successful content baseline.
• Logs never include query strings, response bodies, cookies, authorization headers, or Apify tokens.

Pricing and resource use

The Actor has no additional developer charge. Standard Apify platform usage may apply to runs according to your Apify plan. It is designed for 256 MB memory and uses no browser, proxy, LLM, paid API, or external database.

Limits

• Public HTTP and HTTPS URLs only.
• Up to 100 targets per run.
• Maximum decompressed response body: 2 MiB per target.
• No JavaScript execution, authenticated pages, screenshots, CAPTCHA handling, or anti-bot bypass.
• JSON identity keys must be direct scalar fields: string, number, or boolean.

Local development

Without ACTOR_RUN_ID, the application starts in local mode:

cp examples/api-price.json input.json
mvn clean test
mvn package
java -jar target/app.jar

Set APP_INPUT_FILE to use another input file. Local state is stored under local-data/state/, and events are appended to local-data/results.jsonl.

docker build -t structured-api-web-change-feed .
docker run --rm \
  -v "$PWD/input.json:/app/input.json:ro" \
  -v "$PWD/local-data:/app/local-data" \
  structured-api-web-change-feed

FAQ

Is this a screenshot monitor?

No. It produces deterministic structured events for APIs, XML, selected HTML text, and plain text.

Can it detect breaking API type changes?

Yes. A change such as JSON Number 123 to String "123" emits typeChanged=true.

Will reordered JSON arrays create false positives?

Not when arrayIdentityKeys is configured. Items are matched by identity before comparison.

Can it calculate price changes?

Yes. Number-to-Number replacements include an exact decimal delta and percentage change. A zero baseline produces percentChange=null instead of infinity.

Does it support XML?

Yes. It supports XPath scoping, deterministic normalization, and XXE protection.

Does it use AI?

No. Normalization and diff results are deterministic.