# New Business Opening (`fryingken/new-business-opening`) Actor

Discover early business-opening leads across New York using public licensing and construction signals. Get ranked, deduplicated opportunities with source evidence for sales and market research.

- **URL**: https://apify.com/fryingken/new-business-opening.md
- **Developed by:** [宣哲 黃](https://apify.com/fryingken) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 results

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## New Business Opening Lead Intelligence — New York

Find potential upcoming businesses using public New York liquor applications,
business-license applications and commercial construction records. Export deduplicated
leads with deterministic evidence scores and the original public signals behind each lead.

**Private preview. Opening signals are not confirmations. Scores are not probabilities
or estimates of an opening date.** This independent tool is not affiliated with New York
State, NYC, SLA, DCWP or DOB. Verify public records before acting on a lead.

### Coverage and sources

| Source | Coverage | Publisher cadence | Role |
| --- | --- | --- | --- |
| [Current SLA Pending Licenses](https://data.ny.gov/d/f8i8-k2gm) | New York State premises | Daily | Pending liquor application |
| [DCWP License Applications](https://data.cityofnewyork.us/d/ptev-4hud) | NYC licensing; only NY premises retained | Weekly | New premises application; individual licenses and renewals excluded |
| [DOB NOW Job Application Filings](https://data.cityofnewyork.us/d/w9ak-ipjd) | NYC | Daily | Commercial construction support |
| [DOB NOW Approved Permits](https://data.cityofnewyork.us/d/rbx6-tga4) | NYC | Daily | Initial commercial permit support |

Publisher cadence does not guarantee current records. On September 17, 2026, DCWP's
latest `New` application date was April 17, 2026, although renewal records were more
recent. A 30-day DCWP query can legitimately return zero. SLA is a current pending
snapshot, not a complete historical archive. Separate DOB electrical/elevator/LAA
datasets are outside this release.

`examples/input-dcwp-history.json` uses a 180-day window and a zero score threshold
to verify older DCWP records. It is a source diagnostic, not a fresh-lead benchmark.

### Input

```json
{"state":"NY","city":"New York","lookbackDays":30,"maxResults":100}
```

| Field | Default | Meaning |
| --- | --- | --- |
| `state` | `NY` | Only New York State |
| `city` | `New York` | NYC's five boroughs; empty string selects statewide NY coverage |
| `boroughs` | `[]` | Optional Manhattan, Bronx, Brooklyn, Queens, Staten Island filter |
| `lookbackDays` | `30` | Inclusive New York calendar-day age, 1–365; excludes future dates |
| `businessCategories` | `[]` | Exact case-insensitive source category labels, e.g. `Restaurant`; no invented category mapping |
| `signalTypes` | All four | `liquor_license`, `business_license`, `building_application`, `building_permit` |
| `minimumSignalScore` | `30` | Minimum score, 0–100 |
| `maxResults` | `1000` | Final deduplicated result cap, 1–10000; fewer results are possible |
| `includeLowConfidence` | `false` | Include construction candidates without an identified operator |
| `includeRawSourceData` | `false` | Include allowlisted original business/source fields, never unrestricted raw rows |

Statewide liquor search:

```json
{"city":"","signalTypes":["liquor_license"],"lookbackDays":30,"maxResults":100}
```

Commercial construction review, including unknown operators:

```json
{"signalTypes":["building_application","building_permit"],"lookbackDays":7,
 "includeLowConfidence":true,"minimumSignalScore":0,"maxResults":100}
```

### Matching and scoring

Names normalize Unicode, spacing, punctuation and trailing legal suffixes. Displayed
names and source addresses remain original. Matching retains house-number hyphens,
ZIP codes, boroughs and unit information. Different units, conflicting ZIP/government
business IDs or missing versus known units prevent a merge.

Records can merge at the same normalized premises using matching government identity,
an exact legal/DBA relationship or conservative name similarity (95/100, long names,
same first token and matching numeric tokens). Every group member must be compatible;
ambiguous and transitive-only relationships remain separate. A shared building never
proves a shared business. Conservative matching can miss real relationships.

DOB property owners, contractors and applicants are **not treated as future tenants**.
Job and permit records can join by exact filing number and compatible premises. DOB
records without operator evidence do not join a liquor/DCWP business on address alone.
They retain `businessName: null` and low identity confidence. Use the construction
input above to review them. This protects against assigning a landlord's or architect's
name to a potential opening.

Initial weights: liquor 45, new premises license 35, permit 20, job application 10.
Only the most recent signal of each type contributes its base weight. Ages 0–30,
31–60, 61–90 and 91–365 days receive 100%, 80%, 60% and 30% of that weight.
Two independent agencies add 20; a third adds 10. Business identity adds 5;
commercial work adds 5; unknown identity subtracts 10. DOB's two datasets count as
**one agency**, not independent corroboration. Scores clamp to 0–100.

Levels: low 0–29, medium 30–49, high 50–69, very\_high 70–100. Renewals,
denied/withdrawn/expired/closed records, future/stale records, individual licenses,
residential-only work and construction without commercial evidence are excluded.
No LLM, contact enrichment or estimated opening date is used.

### Output and failure behavior

One default Dataset item is one deduplicated potential opening. Fields include
`leadId`, business/DBA/category, address, score/level/reasons, identity confidence,
signals, dataset/agency counts, first/latest signal dates and retrieval timestamp.
Each signal preserves its source record ID, source link, date, status, original name
and address. Unknown phone, website, email and opening date remain `null`.

[Example output](examples/output.json) is fictional test data, not a real business lead.
`leadId` is deterministic for the same evidence and independent of input order or exact
duplicates. It is anchored to a source record and premises; it can change when that
anchor disappears, changes or is superseded by new source evidence. This is not a
persistent change-monitoring service.

DOB permit source IDs include filing number, work permit, sequence and work type,
because the official export can repeat the first three across different work types.
Those evidence rows do not create extra leads or repeated base-score contributions.
Job record IDs include filing number and floor/unit scope. If a source still supplies
conflicting versions of the same record key, all versions are excluded and counted
as ambiguous in OUTPUT; coverage is marked partial rather than choosing one status.

The default Key-Value Store's `OUTPUT` contains source counts, source update times,
failures, exclusions, duplicate count, qualified count and actual Dataset count.
`ambiguousSourceIdentities` counts quarantined contradictory identities; per-source
`rejectedRecords` includes their excluded rows.
If some requested sources fail, remaining sources produce partial results with explicit
coverage gaps. A failed source count is `null`, never zero. If all sources fail, the
Run fails. Check `sourceCoverageComplete` before treating results as comprehensive.

Dataset writes are sequential and never automatically retried. If a write fails after
partial delivery, saved items can remain accessible. Uncertain delivery counts are
`null` in failed OUTPUT. Restart of a run with prior output intent is rejected; start
a fresh run. No automatic cross-run deduplication is promised.

### Privacy and limitations

Only public business and regulatory evidence is used. Personal license applicants,
owner/architect names, phone numbers and mailing addresses are not selected for output.
Optional raw fields are allowlisted; construction descriptions remain public work
descriptions, not independently verified claims. No email, website, social profile,
Google Maps or automated outreach enrichment is performed.

An application can concern an existing business or a change of operator. Commercial
renovation does not guarantee a new opening. Missing units, incomplete identities,
source delays and conservative matching affect recall. Nationwide coverage is absent.

### Pricing and usage

Approved launch price: **$0.005 per delivered qualified lead ($5 per 1,000)**,
with platform usage included. 100 leads cost $0.50; 500 cost $2.50; 1,000 cost $5.00.
Apify's standard `apify-actor-start` charge is separate: $0.00005 at 1024 MB.
There is no custom base/run fee. Private Cloud billing verification has passed; publication remains a separate step.

Every default Dataset item is one final lead. Apify automatically bills
`apify-default-dataset-item`; no custom `qualified-lead` event is charged. Source
records, signals, duplicates, merged-away entities, rejected/conflicting/below-threshold
candidates, source failures and OUTPUT are never result events. Zero leads means zero
result charges; the standard start event still applies. Optional low-confidence leads
must still satisfy the user's filters and are billed only when delivered.

The Actor respects the remaining run budget after startup, delivering only the affordable
prefix of the ranked results, always within `maxResults`. OUTPUT reports actual
`datasetItems`/`returnedLeads` and `budgetTruncated=true` when the spending cap removes
otherwise selected leads. Source coverage status is independent of budget truncation.
A smaller live population can also underfill maxResults without budget truncation.

Failed source/process runs may fail with no result charges. Failed appends can leave
successfully delivered, billable items; no automatic POST retry occurs. Interrupted or
restarted writes to an already used Dataset are rejected rather than replayed. A failed
delivery reports count `null` when its committed count is uncertain; inspect the Dataset
and platform event ledger. Fresh runs are independent purchases, not cross-run deduplication.

Use Apify API or schedules with the same input JSON. Export nested provenance as JSON;
CSV is useful for the flat overview. Scheduling repeats a fresh source scan and can
return previously observed leads. Contact the Actor's Store Issues/support route once
published; during private preview, report run ID, INPUT, OUTPUT and stage logs to the owner.

### Development and private deployment

Python 3.12; independent dependencies and storage, no imports from the NDIS Actor.

```bash
python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/python scripts/generate_schemas.py
.venv/bin/pytest -q
.venv/bin/ruff check .
.venv/bin/ruff format --check .
.venv/bin/python scripts/smoke_local.py
.venv/bin/python scripts/smoke_local.py --ppe
.venv/bin/python scripts/smoke_local.py --live examples/input.json
apify run
docker build -t new-business-opening:local .
```

`apify run` uses `storage/key_value_stores/default/INPUT.json`; start with clean storage.
The smoke script uses temporary storage. Optional owner secret `SOCRATA_APP_TOKEN`
improves public API quotas; core operation requires no token.

Transport: 10s connect/pool/write, 45s read inactivity, three GET attempts for transport,
429 or 5xx failures, 1s/2s backoff, 180s per-source deadline. Four sources fetch concurrently.
Pages contain at most 500 rows and responses at most 8 MiB. More than 25,000 rows per
source fails that source explicitly; narrow the date window. Stable row ordering,
repeated-row checks and before/after publisher update checks guard pagination, but the
API does not provide a transactional snapshot. Entity comparisons cap at 500,000;
exceeding this fails rather than silently truncating results.

Create a **second independent private Apify Actor** from:

`git@github.com:Ken0002/apify-intelligence-actors.git#dev:actors/new-business-opening`

Use a read-only deploy key, hide source files, **LIMITED\_PERMISSIONS, 1024 MB and 600
seconds**: Cloud-verified and approved production settings. Keep the Actor private.
For private billing verification, configure PPE with **Pay per event + usage OFF**,
primary `apify-default-dataset-item=$0.005`, and `apify-actor-start=$0.00005` only.
Do not add custom events or tier discounts; runtime rejects unapproved effective prices.
See the repository release checklist for spending-cap and event-ledger tests before main
or Store publication. Existing NDIS Actor source/settings must remain unchanged.

# Changelog

This Actor's version history is a separate document: https://apify.com/fryingken/new-business-opening/changelog.md

# Actor input Schema

## `state` (type: `string`):

Only New York State is supported.

## `city` (type: `string`):

New York means NYC's five boroughs. Empty means statewide NY; only SLA has statewide coverage.

## `boroughs` (type: `array`):

Optional NYC borough filter: Manhattan, Bronx, Brooklyn, Queens, Staten Island.

## `lookbackDays` (type: `integer`):

Signal age in calendar days, inclusive. Maximum 365; current pending SLA is not a history archive.

## `businessCategories` (type: `array`):

Exact case-insensitive source category labels, such as Restaurant. Empty means all.

## `signalTypes` (type: `array`):

Requested datasets by signal type. At least one required.

## `minimumSignalScore` (type: `integer`):

Minimum deterministic evidence score. Not an opening probability.

## `maxResults` (type: `integer`):

Cap after classification, deduplication, scoring and sorting. May return fewer.

## `includeLowConfidence` (type: `boolean`):

Allow candidates without an identified business operator. DOB-only candidates normally need a score threshold below 30.

## `includeRawSourceData` (type: `boolean`):

Include allowlisted original source fields only. Contacts, applicant and owner identities are excluded.

## Actor input object example

```json
{
  "state": "NY",
  "city": "New York",
  "boroughs": [],
  "lookbackDays": 30,
  "businessCategories": [],
  "signalTypes": [
    "liquor_license",
    "business_license",
    "building_application",
    "building_permit"
  ],
  "minimumSignalScore": 30,
  "maxResults": 1000,
  "includeLowConfidence": false,
  "includeRawSourceData": false
}
```

# Actor output Schema

## `leads` (type: `string`):

No description

## `summary` (type: `string`):

No description

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("fryingken/new-business-opening").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("fryingken/new-business-opening").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).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 fryingken/new-business-opening --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fryingken/new-business-opening"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/6uE2S4EBQz1m6xTHB/builds/8lrBl5EZSoFrwfd0F/openapi.json