OpportunityFilter — Local Business Opportunity Finder

What it does

OpportunityFilter ranks appointment-driven businesses whose public websites show demand but no detected online-booking mechanism. It combines supplied source records, bounded static-HTML analysis, comparable businesses already in the same input, and deterministic evidence. It is a prospect-qualification aid for agencies, consultants and operators evaluating digital booking work; it does not contact businesses or claim that a booking feature is absent.

Quick start

The simplest first run is the default Google Maps route: enter a search term, location and maximum number of records. Google Maps sourcing is performed by the configured upstream Actor and has separate provider charges. For a no-upstream-cost test, choose source=direct and provide normalized businesses, or choose source=dataset to reuse an existing Dataset.

Start with 20–100 source records. maxResults is a source-record budget; duplicates, malformed records, filters and missing fields can reduce the number of final rows. The default settings use bounded HTTP only, at most two pages per website, one retry and ten concurrent business tasks.

What you provide

• Search route: searchTerms, location, maxResults, and optional filters.
• Dataset route: datasetId and datasetAdapter (google_maps or normalized).
• Direct route: an array of businesses; name is required and category, geography, demand fields and websiteUrl improve the evidence.

The complete input form is generated in input_schema.json. It rejects unknown fields, contradictory source selections and values outside the documented limits with a named diagnostic.

What you receive

The default Dataset contains stable schemaVersion=1.0 rows with a deterministic resultId, rank, normalized business data, website status, booking state, evidence, competitor comparison, score components, confidence and bounded errors. The output_schema.json links the ranked Dataset as JSON and the run summary in OUTPUT.

Example result shape (real fields, abbreviated):

{
  "schemaVersion": "1.0",
  "resultId": "cbfe976bf2d5a5b35783f98e25f54421",
  "product": "NO_BOOKING_FINDER",
  "rank": 1,
  "status": "COMPLETE",
  "business": { "name": "Synthetic poor", "city": "Lyon", "category": "dentist" },
  "website": { "status": "AVAILABLE", "booking": { "state": "NOT_DETECTED" } },
  "opportunityScore": 59,
  "confidence": 0.65,
  "evidence": [],
  "errors": []
}

NOT_DETECTED is an observation, not proof of absence. Static HTML, consent walls, client rendering and inaccessible pages can hide a mechanism. Version 1 caps apparent gaps at 59/100 and preserves uncertain rows for manual review.

API example

Replace <ACTOR_ID> with the account's secure value. Keep the token in the environment; do not put it in source control, a URL or a shell history.

$input = Get-Content examples/input-direct.json -Raw
Invoke-RestMethod `
  -Method Post `
  -Uri "https://api.apify.com/v2/acts/<ACTOR_ID>/runs" `
  -Headers @{ Authorization = "Bearer $env:APIFY_TOKEN" } `
  -ContentType 'application/json' `
  -Body $input

Fetch the default Dataset through the run's defaultDatasetId, or use the output link rendered by output_schema.json.

Cost and PPE status

The configured price is $0.003 per result written to the default Dataset, using the single apify-default-dataset-item event. A resumed run appends only missing rows; a new, independent run is a new processing request. Invalid input that produces no Dataset item produces no result event. Google Maps sourcing has separate upstream provider costs; check the current Apify pricing panel before running a search.

Remote qualification has verified one result/one event, zero results/zero events, ten results/ten events and a same-run restart without a duplicate event. These tests used a Free account and do not establish paid-customer revenue or payouts. The configured price is distinct from measured platform usage and developer earnings.

Limitations and privacy

• No browser automation; JavaScript-only booking widgets may remain UNKNOWN.
• At most three same-origin pages, bounded response bytes, deadlines and retries.
• Competitor rates describe the supplied comparable sample, not the whole market.
• No authentication, CAPTCHA bypass, private data access, outreach or contact harvesting.
• Raw HTML is not persisted; Dataset and checkpoint retention is controlled by the Apify account owner.

Support and version

For a failed run, inspect the structured run_start, source_initialization, analysis_complete, run_summary, run_end or run_failed records, then inspect OUTPUT and the default Dataset. OUTPUT_CONFLICT requires a fresh storage/run after checking the existing Dataset; an uncertain upstream launch must be verified before retrying.

This documentation describes OpportunityFilter package 1.0.4 and Actor version 1.3. See the repository changelog and the production qualification for the exact release and remaining external gates.