# Overture Local Leads (`gmanner/overture-local-leads`) Actor

Local business leads from the open Overture Maps Places dataset: name, category, phone, website or no-website flag, address, brand and confidence for any bounding box, without touching Google Maps.

- **URL**: https://apify.com/gmanner/overture-local-leads.md
- **Developed by:** [Hwangjun Choi](https://apify.com/gmanner) (community)
- **Categories:** Lead generation, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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

## Overture Local Leads

Local business leads for any area on the map, from the open Overture Maps Places dataset (about 60 million places worldwide, refreshed monthly, sourced from Meta, Microsoft and community data). Draw a bounding box or give a centre point and radius, optionally filter by category, and get name, category, phone, website or a no-website flag, street address, coordinates, brand and a confidence score.

No Google Maps scraping, no proxies, no captchas: the data is read directly from Overture's public release with DuckDB, so runs are fast and never blocked.

### What you can do with it

- **Web design and local SEO prospecting** - `websiteFilter: without_website` with `requirePhone: true` returns businesses you can call today that have no site. In downtown Austin (2 km x 2 km) 19% of all places have no website listed.
- **Territory and market mapping** - count dentists, gyms, cafes or car dealers per neighbourhood; export with coordinates to a map.
- **CRM enrichment at scale** - 100,000 leads per run, ranked by confidence, with Overture's stable place IDs for deduplication across months.
- **Replacing per-query Maps scrapers** - one run covers a whole city instead of one search box at a time.

### Input

| Field | Meaning |
|---|---|
| `bbox` | `west,south,east,north` in decimal degrees (copy from bboxfinder.com). Up to 10 square degrees per run. |
| `centerLat`, `centerLon`, `radiusKm` | Alternative to `bbox`: a square of `radiusKm` half-width around the point. |
| `categories` | Overture category names: `restaurant`, `cafe`, `bar`, `dentist`, `plumber`, `hair_salon`, `real_estate_agent`, `lawyer`, `gym`, `hotel`, `car_dealer`, `bakery` ... Matched against the primary category, its parents and alternates, so `bar` also returns pubs and cocktail bars. |
| `websiteFilter` | `any`, `without_website`, `with_website`. |
| `requirePhone`, `minConfidence`, `countries`, `excludeClosed`, `nameContains` | Further filters. |
| `maxResults` | Cap on leads (highest confidence first). Default 1,000, maximum 100,000. |

Example:

```json
{
  "bbox": "-97.75,30.26,-97.73,30.28",
  "categories": ["restaurant", "cafe", "bar"],
  "websiteFilter": "without_website",
  "requirePhone": true,
  "minConfidence": "0.5",
  "maxResults": 500
}
```

### Output

One row per business:

```json
{
  "id": "928a635c-dcb9-4282-b2ab-4a1151ba8b2f",
  "name": "The Iron Bear",
  "category": "bar",
  "categoryHierarchy": ["food_and_drink", "alcoholic_beverage_venue", "bar"],
  "altCategories": [],
  "basicCategory": "bar",
  "operatingStatus": "open",
  "confidence": 0.9967,
  "hasWebsite": false,
  "website": null,
  "websites": [],
  "phone": "15124828993",
  "phones": ["15124828993"],
  "emails": [],
  "socials": [],
  "brand": null,
  "street": "301 W 6th St",
  "city": "Austin",
  "region": "TX",
  "postcode": "78701-2915",
  "country": "US",
  "lat": 30.268,
  "lon": -97.7456,
  "googleMapsUrl": "https://www.google.com/maps/search/?api=1&query=30.268000,-97.745600",
  "sourceDatasets": ["Microsoft", "Overture"],
  "overtureRelease": "2026-09-23.1",
  "scrapedAt": "2026-10-10T20:15:02+00:00"
}
```

`emails` and `socials` (Facebook, Instagram pages) are filled when Overture has them, which is common for places sourced from Meta. The key-value store record `SUMMARY` holds the bbox, filters, lead count and duration.

### Pricing

Pay per event:

| Event | Price |
|---|---|
| Run start | $0.003 |
| Lead | $0.003 |

200 leads cost $0.003 + 200 x $0.003 = **$0.60**; a 5,000-lead city export costs $15.00. Only rows written to the dataset are charged, so narrow filters (no website + phone + category) cost exactly what they return.

### Speed

Measured on the current release: a 2 km x 2 km downtown box returns 200 leads in about 18 seconds and a filtered no-website query in about 20 to 25 seconds, most of it the one-time scan of the parquet metadata. Larger boxes grow roughly with the number of places inside them.

### Limits

- Data comes from the monthly Overture release (default `2026-09-23.1`, selectable). It is not live: a business that opened last week is unlikely to be there yet.
- No ratings, reviews, opening hours or photos; Overture Places does not carry them. Use the `googleMapsUrl` field to look a lead up.
- Coverage and field completeness vary by country. North America and Western Europe are dense; phone numbers are present on most US records, websites on roughly 80%.
- `confidence` is Overture's own estimate that the place exists as described; 0.5 and above is a reasonable default for outreach lists.
- Phone numbers are returned as stored (mixed formats such as `+15129004740` and `15124828993`); normalise them downstream if needed.
- A single run covers at most 10 square degrees (roughly a large metro area); split countries into tiles.

Overture Maps places data is licensed under CDLA Permissive 2.0; keep the attribution when you republish it.

### Local test

`.venv/Scripts/python test/run_local.py` (Windows) or `.venv/bin/python test/run_local.py` runs four scenarios against the live S3 release and asserts the fields, counts and ordering.

# Actor input Schema

## `bbox` (type: `string`):

Area to search, in decimal degrees: west,south,east,north (min longitude, min latitude, max longitude, max latitude). Copy it from bboxfinder.com or any map tool. Up to 10 square degrees per run; split larger regions into several runs.

## `centerLat` (type: `string`):

Alternative to bbox: latitude of the center point, e.g. 30.27. Used only when bbox is empty.

## `centerLon` (type: `string`):

Alternative to bbox: longitude of the center point, e.g. -97.74. Used only when bbox is empty.

## `radiusKm` (type: `string`):

Half-width of the square around the center point, 0.05 to 150 km. Default 2.

## `categories` (type: `array`):

Overture category names, matched against the primary category, its parents and alternates. Examples: restaurant, cafe, dentist, plumber, hair_salon, real_estate_agent, lawyer, gym, hotel, car_dealer, bar, bakery. Lower case with underscores; leave empty for all businesses.

## `websiteFilter` (type: `string`):

Pick 'without a website' for web-design and local-SEO prospecting.

## `requirePhone` (type: `boolean`):

Drop places without a phone number. Combine with 'without a website' for call lists.

## `minConfidence` (type: `string`):

Overture's existence confidence score. 0.5 keeps most real businesses; 0.8 keeps only well-corroborated ones. Default 0 (no filter).

## `countries` (type: `array`):

Optional ISO 3166-1 alpha-2 codes (US, GB, DE ...). Useful when the bbox crosses a border.

## `excludeClosed` (type: `boolean`):

Skip places Overture marks as permanently closed. Temporarily closed places are kept.

## `nameContains` (type: `string`):

Optional case-insensitive substring filter on the business name.

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

Stop after this many leads (highest confidence first). The run cost is bounded by this number.

## `release` (type: `string`):

Overture Maps release to read (monthly). See docs.overturemaps.org/release for the list.

## `threads` (type: `integer`):

Parallelism for reading parquet row groups. 4 is right for a 1 GB run.

## `memoryLimit` (type: `string`):

Keep below the run's memory. Raise together with the run memory for very large areas.

## Actor input object example

```json
{
  "bbox": "-97.75,30.26,-97.73,30.28",
  "radiusKm": "2",
  "categories": [],
  "websiteFilter": "any",
  "requirePhone": false,
  "minConfidence": "0",
  "countries": [],
  "excludeClosed": true,
  "maxResults": 1000,
  "release": "2026-09-23.1",
  "threads": 4,
  "memoryLimit": "768MB"
}
```

# Actor output Schema

## `results` (type: `string`):

One row per business: name, category, phone, website or no-website flag, address, coordinates, brand, confidence.

# 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 = {
    "bbox": "-97.75,30.26,-97.73,30.28",
    "categories": [],
    "countries": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("gmanner/overture-local-leads").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 = {
    "bbox": "-97.75,30.26,-97.73,30.28",
    "categories": [],
    "countries": [],
}

# Run the Actor and wait for it to finish
run = client.actor("gmanner/overture-local-leads").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 '{
  "bbox": "-97.75,30.26,-97.73,30.28",
  "categories": [],
  "countries": []
}' |
apify call gmanner/overture-local-leads --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,gmanner/overture-local-leads"
        }
    }
}
```

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/hhKes0Qq6hc5isUHl/builds/WFjXoUwPnEBBlzvOG/openapi.json