# Local Lead Opportunity Finder (`0xgollum/local-lead-opportunity-finder`) Actor

Find and score local businesses worldwide that may need websites, SEO, reputation management, or automation.

- **URL**: https://apify.com/0xgollum/local-lead-opportunity-finder.md
- **Developed by:** [0xGollum](https://apify.com/0xgollum) (community)
- **Categories:** Lead generation, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Local Lead Opportunity Finder

This Apify Actor finds local businesses worldwide with visible signals that they may need a website, local SEO, reputation management, or automation.

It delegates Google Maps collection to a compatible source Actor, then normalizes the results and calculates an explainable `opportunityScore` from 0 to 100. No private data is collected.

### Example input

```json
{
  "sourceActorInput": {
    "searchStringsArray": ["dentists in New York, USA"],
    "maxCrawledPlacesPerSearch": 100
  },
  "minimumOpportunityScore": 35,
  "maxBusinesses": 500,
  "onlyNewLeads": true,
  "historyStoreName": "my-client-lead-history"
}
```

The default source is `compass/crawler-google-places`. If you use another Google Maps Actor, pass its compatible input through `sourceActorInput`.

### Scoring

- No website: +53
- Google rating under 3.8: +20
- Fewer than 20 reviews: +15; fewer than 50: +8
- No phone: +8
- No category: +4

Weights sum to exactly 100 in the worst case, so the advertised 0-100 scale is actually reachable. The score is deliberately transparent: it identifies visible business-development opportunities; it does not claim to predict a company's budget or intent to buy.

### Scheduled runs and deduplication

Keep the same `historyStoreName` across scheduled runs for a given client or search: only leads not already delivered in a previous run are pushed to the dataset (`onlyNewLeads: true`, the default). Use a new store name, or set `onlyNewLeads: false`, to re-deliver every currently qualifying lead.

The Actor also refuses to score results from a source run that didn't fully succeed, rather than silently delivering a partial or stale dataset.

### Local development

```bash
npm install
npm test
npm run lint
```

Deploy with `apify push`, configure searches in the Console, and schedule recurring runs as needed. Use public data responsibly and comply with applicable privacy, marketing, and platform rules.

# Actor input Schema

## `sourceActorId` (type: `string`):

Compatible Actor that returns Google Maps businesses. Default: Apify's maintained Google Maps Scraper.

## `sourceActorInput` (type: `object`):

Input passed directly to the Google Maps source Actor. For the default Actor, use searchStringsArray and maxCrawledPlacesPerSearch.

## `maxBusinesses` (type: `integer`):

Maximum number of businesses read from the source Actor's dataset and scored in this run.

## `minimumOpportunityScore` (type: `integer`):

Only output businesses at or above this score (0-100).

## `includeClosedBusinesses` (type: `boolean`):

By default, businesses marked permanently closed by the source Actor are skipped and never scored.

## `onlyNewLeads` (type: `boolean`):

On scheduled runs, only output leads not already delivered in a previous run (tracked via the history store). Turn off to re-deliver every qualifying lead each run.

## `historyStoreName` (type: `string`):

Key-value store used to remember which leads were already delivered. Keep the same name across scheduled runs for a given client/search; use a new name to reset and treat all current leads as new.

## Actor input object example

```json
{
  "sourceActorId": "compass/crawler-google-places",
  "sourceActorInput": {
    "searchStringsArray": [
      "dentists in New York, USA"
    ],
    "maxCrawledPlacesPerSearch": 20
  },
  "maxBusinesses": 500,
  "minimumOpportunityScore": 35,
  "includeClosedBusinesses": false,
  "onlyNewLeads": true,
  "historyStoreName": "local-lead-opportunity-history"
}
```

# Actor output Schema

## `qualifiedLeads` (type: `string`):

Businesses meeting the requested opportunity-score threshold.

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

Counts and score distribution for the current run.

# 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 = {
    "sourceActorInput": {
        "searchStringsArray": [
            "dentists in New York, USA"
        ],
        "maxCrawledPlacesPerSearch": 20
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("0xgollum/local-lead-opportunity-finder").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 = { "sourceActorInput": {
        "searchStringsArray": ["dentists in New York, USA"],
        "maxCrawledPlacesPerSearch": 20,
    } }

# Run the Actor and wait for it to finish
run = client.actor("0xgollum/local-lead-opportunity-finder").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 '{
  "sourceActorInput": {
    "searchStringsArray": [
      "dentists in New York, USA"
    ],
    "maxCrawledPlacesPerSearch": 20
  }
}' |
apify call 0xgollum/local-lead-opportunity-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,0xgollum/local-lead-opportunity-finder"
        }
    }
}

```

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/OeAtJK0t5LSchqkaJ/builds/oJqjyxLBwOZ0aE0QT/openapi.json