U.S. Ghost Kitchen Market Intelligence

Turn public delivery-listing evidence into a directional market brief for one U.S. market or a bounded batch. The Actor combines reachability-based source coverage, shared-address candidate dossiers, qualitative scorecards, and a standalone HTML report without presenting the result as an official or legal determination.

Product scope: Ghost 0.4.0 includes deterministic fictional demo mode, v2 summaries, and a standalone HTML report. Store pricing, rendered presentation, support, and ongoing operations remain separate evidence surfaces.

What You Get

Every successful run produces a linked product bundle:

1. Directional positioning — candidate language and explicit evidence limits instead of an official-detector claim.
2. A simpler input experience — choose fictional demo or live execution, then follow separate live market, scan-control, and optional Yelp sections. Existing single-market and batch keys remain compatible.
3. A deterministic fictional demo — three versioned scenarios exercise the real v2 product without delivery-source, geocoder, proxy, Yelp, reservation, idempotency-key, or charge activity.
4. marketScorecard — a qualitative, coverage-gated signal with observable counts; it is not a probability, accuracy score, demand estimate, or market size.
5. addressClusters — bounded dossiers for emitted brands sharing an exact location and normalized-address identity. A shared address does not establish ownership, legal status, demand, or official verification.
6. sourceCoverage — a reachability-based grade that distinguishes reached, partial, failed, and not-started source observations instead of using result count as a coverage proxy.
7. OUTPUT.html — a self-contained, script-free HTML view of the same typed OUTPUT summary, stored with text/html; charset=utf-8.

The default dataset remains the restaurant-level evidence surface. The JSON OUTPUT record is the machine-readable run summary, and OUTPUT.html is the buyer-readable view. Live charge eligibility begins only after all three artifacts are durable.

Quick Start

Inspect the product without live collection or billing

{
  "demoMode": true,
  "demoScenario": "shared_kitchen_cluster"
}

Demo mode ignores submitted live locations, scan controls, concurrency, and the Yelp secret. It still writes fictional dataset rows, OUTPUT, and OUTPUT.html to the run's platform storage. Every demo row is visibly marked with runMode: "demo" and evidenceMode: "synthetic_demo"; billing and idempotency fields remain ineligible or null.

The following table is checked against the real demo-v1 fixtures and the same execution path used by the Actor:

The default scenario also generates this plain-English preview through the same versioned route; the values are not copied from a marketing example:

Fictional default-demo brief: Candidate activity at shared addresses. Coverage: Complete declared source reachability (3 of 3 declared observations reached). Observable evidence: 4 classified rows, 3 confirmed-or-likely candidate rows, and 1 notable shared-address cluster with 3 fictional brands at 100 Fictional Foundry Way, Exampleville, ZZ 00000. This is deterministic synthetic demo evidence, not live-source, ownership, legal-status, or official-verification proof.

All names, addresses, locations, timestamps, and observations in those scenarios are fictional. Demo output proves deterministic product behavior; it does not prove live source availability or accuracy.

Run the recommended live path

{
  "demoMode": false,
  "demoScenario": "shared_kitchen_cluster",
  "location": "Austin, TX",
  "radiusMiles": 3,
  "maxRestaurants": 25,
  "confidenceThreshold": 0.5,
  "includeTraditionalRestaurants": false,
  "batchConcurrency": 1
}

This is the canonical live smoke input. A legacy input that omits both demo fields still follows the live route, and demoScenario receives the additive default without changing live behavior.

Inspect A Finished Run

Open HTML Market Report first when you want the plain-English market brief. It leads with the directional signal, declared source reachability, observable counts, notable shared-address dossiers, and the limitations that constrain interpretation. Then use the remaining output links for the evidence or operational detail you need:

1. Results opens the default dataset and its restaurant-level evidence.
2. Run Summary opens JSON OUTPUT, the machine-readable source-coverage, scorecard, dossier, artifact, and per-location contract.
3. Batch Charge Checkpoint opens BATCH_STATE; Location Charge States lists the LOCATION-#### records. These are operational retry and charge-state evidence with output-safe identifiers, not market evidence and not settled platform charge-counter proof.

The checkpoint links help an operator or agent decide whether a retry is safe. They do not replace OUTPUT, prove that Apify settled an event counter, or turn retry metadata into broader market evidence or settled billing proof.

How It Works

1. Resolve one location or plan a bounded locations[] batch. Do not provide both.
2. Attempt public-source collection from DoorDash, Uber Eats, and Grubhub for each unique market fingerprint. Optional Yelp Fusion enrichment can add storefront context.
3. Standardize emitted addresses, preserve source-health facts, and classify each listing from the evidence available to that row.
4. Derive reachability-based coverage, exact shared-address dossiers, and a qualitative market scorecard from the emitted evidence.
5. Publish dataset rows, JSON OUTPUT, and raw OUTPUT.html in that order.
6. For live work only, attempt the location-analyzed event after the complete artifact bundle is durable and eligible.

The Actor preserves partial, quiet, failed, skipped, duplicate, spend-limited, and post-output charge-failure states. A low result count is never used as a shortcut for source coverage.

Input Parameters

The Console form presents four ordered sections: demo/live choice, live market selection, live scan controls, and optional live Yelp context.

Each locations[] row may override radius, cuisine, maximum restaurant count, confidence threshold, and traditional-restaurant inclusion. It may not override the global Yelp secret.

For a first live run, use one location with the prefilled smoke controls. For a first batch, start with two or three markets and keep batchConcurrency at 1 until you have inspected the output and source-coverage shape.

Output Format

Dataset results

The default dataset contains one row per emitted business. V2 adds runMode and evidenceMode while preserving the names, JSON types, and meanings of the legacy row fields.

Important fields include:

Pair dataset rows with OUTPUT.sourceCoverage before interpreting a missing source, quiet market, or unknown classification.

JSON OUTPUT summary

The structured summary uses

schemaVersion: "ghost-kitchen-batch-output-v2"

• runMode — live or demo.
• sourceCoverage — aggregate grade, reachability counts, explanation, limitations, and deterministic per-source/per-location rows.
• addressClusters — basis, limitation, total/embedded/omitted counts, bounded dossiers, classification counts, strongest existing evidence, and exact dataset trace identity.
• marketScorecard — qualitative signal, coverage context, observable counts, explanation, and limitations.

OUTPUT.locations[] carries the same three intelligence products for each request row. Duplicate, spend-limit, timeout, queued, and pre-output rows remain not_started / insufficient_coverage; they do not borrow another market's evidence. A charge failure after complete output preserves valid collection evidence while keeping the billing failure explicit.

Deadline-safe nonchargeable finalization

Once whole-location source work starts, the Actor derives its remaining budget from the platform deadline and preserves a separate 45-second finalization reserve. If that source-work budget is exhausted, the incomplete location uses the existing zero_event_pre_output_failure / ineligible_pre_output_failure contract, releases its reserved charge slot, and attempts the complete dataset, JSON OUTPUT, OUTPUT.html, and checkpoint finalization path. After those artifacts are durable, the Actor reports durable nonchargeable deadline output; it does not attach a charged event name or make a charge attempt.

A deadline-exhausted location carries no completed direct source observation, stays not_started / insufficient_coverage, and does not borrow evidence from a completed sibling. If HTML or another required artifact cannot be finalized, the incomplete bundle remains nonchargeable. This cooperative async deadline protects reserved finalization time when source work yields to the runtime; it does not guarantee source availability, artifact storage, or every-run success.

Source coverage grades

Coverage is based on declared source-location reachability, not restaurant count:

A reached-empty market can be complete; that means the declared sources were reached, not that no ghost kitchens exist. An all-source blackout is unavailable, writes diagnostics when storage permits, fails the run, and is not charge eligible.

Market scorecard signals

The scorecard deliberately has no 0–100 score, probability, accuracy claim, demand estimate, or official-status field.

Address-cluster dossiers

A notable dossier requires at least two distinct emitted brand identities that share the exact location, emitted cluster id, and emitted normalized address. The product embeds at most 25 dossiers and reports omitted count plus truncation state. Exact duplicate row copies do not inflate distinct-brand or classification counts.

Every dossier includes an exact dataset trace tuple. It remains observational public-source evidence and does not establish common ownership, shared operations, legal ghost-kitchen status, commercial demand, or exhaustive market coverage.

HTML market report

OUTPUT.html is stored in the default key-value store under the exact key OUTPUT.html with content type text/html; charset=utf-8. The Actor output link points directly to that record.

The report renders the same typed summary as JSON OUTPUT. It is self-contained, script-free, remote-resource-free, contextually escaped, and capped at 512 KiB. If rendering exceeds the bound, it fails closed instead of publishing a truncated report.

Billing and artifact states

OUTPUT.locations[] is the quickest place to audit live billing semantics:

If a dataset, JSON, or HTML write fails, no charge is attempted for that incomplete bundle. Successful earlier writes remain inspectable, and the Actor attempts a truthful non-chargeable checkpoint and corrected views when the remaining storage surfaces permit it.

How To Read Classifications

confidenceScore measures strength of the local heuristic evidence. It is not verified accuracy and should not be interpreted as a probability.

Agent And API Use

Read the Actor output links for all three surfaces:

• dataset rows for business-level evidence;
• runSummary for JSON OUTPUT; and
• htmlReport for OUTPUT.html.

Before chaining a result, inspect runMode, sourceCoverage, marketScorecard, addressClusters, locations[], sourceHealth, partialData, and charge status. For live API work, use Apify's maxTotalChargeUsd run option when a hard budget is required.

Limitations

• The Actor currently attempts public-source collection from DoorDash, Uber Eats, and Grubhub. Those sources can return partial data, rate limits, blocked requests, schema drift, or no usable listing data.
• Optional Yelp Fusion enrichment can add storefront context, but missing Yelp evidence stays unknown rather than false.
• Address normalization and shared-address grouping are heuristic and depend on source formatting.
• The product supports U.S. locations only.
• Batch mode admits at most 50 requested rows and 25 unique market fingerprints.
• Radius filtering is best effort when a source omits usable distance data.
• The embedded dossier list is bounded; omitted dossiers remain counted but do not support candidate-bearing cluster claims.
• Demo output proves deterministic local behavior only. It does not prove live source coverage, Store propagation, production scale, support readiness, or paid-event behavior.

Disclaimer

This is an unofficial market-research Actor. It is not an official business registry and does not make legal, regulatory, ownership, health, licensing, or exhaustive-coverage determinations. It is not affiliated with, endorsed by, or associated with DoorDash, Uber Eats, Grubhub, or Yelp. Product names and trademarks belong to their respective owners.

Use the output to prioritize manual research, not as the sole basis for legal, credit, investment, leasing, employment, enforcement, or other high-impact decisions.

Permissions

This Actor is designed to run with limited permissions. It uses its own default dataset and key-value store plus outbound HTTP requests to delivery platforms, Nominatim geocoding, and optional Yelp Fusion. It does not require access to your other Apify storages or account resources.

Memory posture

Ghost 0.4.0 declares a 128 MiB minimum and default with a 1024 MiB maximum. The fixed Actor default is 128 MiB, while callers can still override a run within those bounds. This smaller default was selected from bounded local benchmark and live smoke evidence.

That evidence supports the observed default and smoke workload class. It does not prove every future workload, guarantee production-scale headroom, or establish realized cost savings.

Pricing

Live execution uses Pay Per Event pricing at $0.10 per eligible location-analyzed event. The unchanged event boundary is one unique requested location and scan-control fingerprint that reaches a complete durable artifact bundle and remains charge eligible.

The following are not separate charge units:

• demo scenarios;
• exact duplicate aliases;
• spend-limit skips;
• all-source blackouts;
• deadline-exhausted locations;
• pre-output failures; and
• incomplete dataset/JSON/HTML publication bundles.

An honestly reached empty market may still be eligible because reached-empty coverage is useful evidence. A partial-source success may also be eligible when the product bundle is durable and the missing coverage remains explicit.

Apify may display the same rate as $100.00 / 1,000 analyzed locations. There are no separate pass-through compute or platform-usage charges added on top of the event price by this Actor.

For batch and agent/API runs, set maxTotalChargeUsd to the maximum number of full events you are willing to allow. Rows skipped by local spend-limit accounting remain visible in OUTPUT.locations[].

Release History

See ./CHANGELOG.md for version-by-version notes. The leading 0.4.0 entry describes the current product contract. Release evidence is tracked separately from version notes, so a changelog entry does not by itself prove GitHub, Apify build/run/storage, Store, or rendered propagation.