# Contractor Leads — Plumbers, Electricians, HVAC & Roofers (`actor-forge/home-services-contractor-leads`) Actor

Plumbers, electricians, HVAC companies, roofers, painters, landscapers, cleaners and other home-service businesses in any city worldwide, with phone, website, email where published, address and a normalised trade field. Open data. $0.003 per city + $1 per 1,000 businesses.

- **URL**: https://apify.com/actor-forge/home-services-contractor-leads.md
- **Developed by:** [ActorForge](https://apify.com/actor-forge) (community)
- **Categories:** Lead generation, Travel
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 area queries

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

## Contractor Leads — Plumbers, Electricians, HVAC & Roofers

Plumbers, electricians, HVAC companies, roofers, painters, landscapers, cleaners and other home-service businesses in any city worldwide, with phone, website, email where published, address and a normalised trade field. Open data. $0.003 per city + $1 per 1,000 businesses.

**Find plumbers, electricians, HVAC companies, roofers and other trades in any city, with their business phone numbers.** Type a city or draw a radius, pick trades, and get one row per business with **phone (E.164), website, business email where published, full address and coordinates**, plus a normalised **trade** field (Plumbing, Electrical, HVAC, Roofing & exteriors, General contractor & remodeling, Painting, Landscaping & garden, Cleaning, Pest control, Locksmith & security, Solar and more) worked out from the business's own categories, so mixed lists sort cleanly.

Made for companies that sell to the trades: field-service and scheduling software, lead-gen and marketing agencies, suppliers and distributors, insurers and franchise developers. Unlike directory scrapers limited to the US, it works in any country Overture covers.

The data is the open **Overture Maps** places dataset (Meta, Microsoft, Foursquare and other sources). Nothing is scraped from Google, Yelp, Angi, Houzz or the BBB, so there are **no reviews, ratings or licence numbers**.

**$0.003 per city query + $1 per 1,000 businesses.** A query with no matching businesses is free.

### What data does it return?

Every run outputs clean, schema-validated rows like these:

| name | trade | category | phones | websites | fullAddress |
| --- | --- | --- | --- | --- | --- |
| Public Service Plumbers | Plumbing | plumbing | +12148311959 | https://www.publicserviceplumbers.com | 5610 Dyer St, Dallas, TX 75206-5004, US |
| Kpost Roofing & Waterproofing | Roofing & exteriors | roofing | +14698988099 | https://www.kpostcompany.com | 1841 W Northwest Hwy, Dallas, TX 75220-7017, US |
| Excell Electric | Electrical | electrician | +12143910040 | www.excellelectric.com | 11510 Data Dr, Dallas, TX 75218-1419, US |
| M. B. Kiser Heating & Air Conditioning Co. Inc. | HVAC | hvac_service | +12148239958 | https://mbkiser.com | 1221 Round Table Dr, Dallas, TX 75247-3503, US |
| Kpost Roofing & Waterproofing | Roofing & exteriors | roofing | +14698988099 | https://www.kpostcompany.com | 1841 W Northwest Hwy, Dallas, TX 75220-7017, US |

### How much does it cost?

Transparent pay-per-event pricing — you only pay for what you get, and the
actor **always respects your run budget**: set a maximum total charge and it
stops cleanly at the cap instead of overrunning.

| Event | Price | Charged | Worked example |
| --- | --- | --- | --- |
| `area-query` | $0.003 | once per run, when the area query returns at least one place | Any city, bbox or radius = $0.003; a query with no matching places is free |
| `place-result` | $0.001 | per place row delivered (contacts, address, coordinates, sources and attribution included) | 200 dentists in Austin = $0.003 + $0.20 = $0.203; 1,000 restaurants in Berlin = $1.003 |
| `apify-actor-start` | $0.00005 | per run per GB of memory (platform start fee) | One run at 1 GB = $0.00005 |

### Input options

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `location` | string | no | — | A city, optionally with region or country: "Austin, TX", "Berlin", "London, Ontario", "Paris France". You can also type "dentists in Austin TX" (the part before "in" becomes the category when Categories is empty), coordinates "30.2672,-97.7431,3km", or a bbox "west,south,east,north". 32,000+ cities with 15,000+ people are built in; smaller towns are looked up in Overture's own divisions data and need a region or country. Ignored when bbox or lat/lon are set. |
| `categories` | array | no | `["plumbing","electrician","hvac_service","roofing","contractor","painting","landscaping","home_cleaning","pest_control_service","handyman"]` | Home-service trades (Overture ids or plain words): plumbing, electrician, hvac_service, roofing, contractor, painting, landscaping, home_cleaning, pest_control_service, handyman, key_and_locksmith, flooring_contractor, solar_installation, tree_service, mover … Use home_service for every trade at once. |
| `maxPlaces` | integer | no | `1000` | Stop after this many places. Highest-confidence places come first (nearest first for a radius search). Places beyond the cap are never charged. |
| `keyword` | string | no | `""` | Optional. Only places whose name (or brand name) contains this text, case-insensitive, e.g. "Starbucks" or "dental". |
| `radiusKm` | number | no | — | Radius for lat/lon (default 5 km). With a city name it searches this radius around the city centre instead of the whole city. Results get distanceKm and come nearest first. |
| `countryCode` | string | no | `""` | Optional two-letter ISO code (US, DE, GB...). Picks the right city when a name exists in several countries and keeps only places whose address is in that country. |
| `requirePhone` | boolean | no | `false` | Skip places without a phone number. |
| `requireWebsite` | boolean | no | `false` | Skip places without a website. Skipped places are never charged. |
| `requireEmail` | boolean | no | `false` | Skip places without a business email (after the personal-email filter). |
| `includePhones` | boolean | no | `true` | Business phone numbers as published for the place, normalised to E.164 (+15125550100) where possible. |
| `includeEmails` | boolean | no | `true` | Business emails from the source data. Addresses on the business's own website domain and role mailboxes (info@, office@, bookings@...) are kept; free-mail addresses (gmail, outlook...) are kept only when they contain the business name. Others are dropped as possibly personal and counted in droppedPersonalEmails. |
| `matchAlternateCategories` | boolean | no | `true` | Also return businesses whose secondary categories match (many contractors list several trades). On by default here. |
| `minConfidence` | number | no | `0.5` | Overture's 0-1 confidence that the place exists as described. 0.5 drops most stale or duplicate records; 0.9 keeps only well-corroborated places; 0 returns everything. |
| `bbox` | array | no | — | Optional \[west, south, east, north] in degrees (longitude, latitude, longitude, latitude), e.g. \[-9.20, 38.69, -9.10, 38.76]. Up to 1.5 x 1.5 degrees (about one metro area). Takes priority over location. |
| `lat` | number | no | — | Optional centre latitude for a radius search (with lon and radiusKm). Takes priority over location. |
| `lon` | number | no | — | Optional centre longitude for a radius search. |
| `includeFields` | array | no | `[]` | Optional. Keep only these fields in each row (id is always kept). Any of: id, name, category, basicCategory, categoryHierarchy, alternateCategories, confidence, operatingStatus, address, fullAddress, lat, lon, distanceKm, phones, websites, emails, socials, brand, sources, licence, licenceUrls, attribution, googleMapsUrl, overtureRelease, droppedPersonalEmails. Keep attribution if you republish the data. |
| `release` | string | no | `""` | Optional, advanced: pin an Overture release such as 2026-09-23.1. Empty = the newest release (Overture publishes monthly). |

### Limits & honest notes

- No reviews, ratings, licence or insurance numbers (open data). trade is derived from Overture categories; "Other home service" covers the rarer ones.
- Works worldwide: any city, a radius around a point, or a bounding box (one metro area per run).
- Open data, not Google: no reviews, ratings, review counts, opening hours, photos, popular times or price levels. The Google Maps link in each row is a plain search URL built from the name and address; nothing is fetched from Google.
- Freshness follows Overture's monthly releases. The newest release is found automatically (or pin one with release). operatingStatus is often empty, so a closed business can still appear until a source drops it; minConfidence (default 0.5) filters most stale records.
- One query per run, up to 1.5 x 1.5 degrees (about one metro area). For a region or country, run once per city. A city query typically reads 15-45 MB of public GeoParquet in 5-15 seconds at 1 GB memory.
- City names resolve offline from a built-in list of 32,000+ cities (Overture divisions, OpenStreetMap-based); smaller towns are looked up in Overture's divisions data and need a region or country ("Dripping Springs, TX"). No external geocoder is called.
- The run's spend limit is respected: the area query is reserved first, places are charged before delivery, and the run stops cleanly at the limit.

### Data licence and attribution

Places come from the [Overture Maps Foundation](https://overturemaps.org) places theme. Each row's `sources` lists the contributing datasets with their record ids, `licence` and `licenceUrls` give the licences, and `attribution` holds the required credit lines. If you republish the data, keep the `attribution` field (or show the lines below).

- © Overture Maps Foundation, overturemaps.org
- Meta, Microsoft, PinMeTo, Krick, RenderSEO, DAC, BrightQuery: "Data from <source>. Available under CDLA Permissive 2.0." ([CDLA-Permissive-2.0](https://cdla.dev/permissive-2-0/))
- Foursquare: "Copyright 2024 Foursquare Labs, Inc. All rights reserved. Available under Apache 2.0. Foursquare data was transformed to the Overture schema. Changed: 2026-03-18." ([Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0))
- AllThePlaces: "Data from AllThePlaces. Available under CC0 1.0."

None of these licences is share-alike, so the rows may be used commercially, stored, merged with your own data and redistributed, provided the attribution and licence texts travel with them.

City boundaries used to turn a city name into a search area come from the Overture divisions theme: © OpenStreetMap contributors, Overture Maps Foundation, available under the [Open Database License (ODbL) 1.0](https://opendatacommons.org/licenses/odbl/1-0/). They are used only for the search area and are not part of the output rows. The built-in city list is a derivative database offered under the ODbL; it is rebuilt from the public Overture release by a documented query.

**Changes made by this actor:** rows are selected by area, category, name and confidence; fields are flattened and renamed; phone numbers are normalised to E.164; possibly personal emails are removed.

**Foursquare OS Places NOTICE** (preserved in full, as Apache-2.0 requires; also included in the run's OUTPUT record whenever Foursquare rows are delivered):

> © 2026 Foursquare Labs, Inc. All rights reserved.
>
> The Foursquare OS Places dataset (the "Data") is licensed under the Apache License, Version 2.0 (the "License"). You may not use, modify, or distribute the Data except in compliance with the License.
>
> As set forth more fully in the License, if you use, modify, or distribute the Data, you must: provide recipients with a copy of the License; if applicable, include prominent notices to the extent you've changed the Data; preserve attribution to Foursquare, including preserving the full content of this NOTICE.txt file.
>
> To ensure appropriate attribution to Foursquare, we recommend the following: if using/distributing the Data in flat file form as-is or after making changes/modifications: include this NOTICE.txt file, which may be modified to include an additional notice of your changes/modifications, if any; if using/distributing the Data in API form as-is or after making changes/modifications: include a copy of the content from this NOTICE.txt file prominently in your developer documentation for such API, which may be modified to include an additional notice of your changes/modifications, if any.
>
> You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law or agreed to in writing, the Data distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This actor is not affiliated with, endorsed by or sponsored by Google, the Overture Maps Foundation or any data contributor. "Google Maps" is a trademark of Google LLC and is used only to describe what this actor is an alternative to.

### Related ActorForge actors

- [Business Places Data](https://apify.com/actor-forge/business-places-data) — any of 2,100+ categories, worldwide
- [Business Leads with Emails](https://apify.com/actor-forge/business-leads-with-emails) — the same places plus emails read from each business website

### Changelog

- **2026-10-23** — Initial release: home-services preset of Business Places Data with a normalised trade field, $0.003 per city + $1 per 1,000 businesses.

***

*Built and maintained by **ActorForge**. Reliability first: every actor in the
portfolio is monitored by an automated nightly self-test, and breakages are
typically fixed the same day.*

# Actor input Schema

## `location` (type: `string`):

A city, optionally with region or country: "Austin, TX", "Berlin", "London, Ontario", "Paris France". You can also type "dentists in Austin TX" (the part before "in" becomes the category when Categories is empty), coordinates "30.2672,-97.7431,3km", or a bbox "west,south,east,north". 32,000+ cities with 15,000+ people are built in; smaller towns are looked up in Overture's own divisions data and need a region or country. Ignored when bbox or lat/lon are set.

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

Home-service trades (Overture ids or plain words): plumbing, electrician, hvac_service, roofing, contractor, painting, landscaping, home_cleaning, pest_control_service, handyman, key_and_locksmith, flooring_contractor, solar_installation, tree_service, mover … Use home_service for every trade at once.

## `maxPlaces` (type: `integer`):

Stop after this many places. Highest-confidence places come first (nearest first for a radius search). Places beyond the cap are never charged.

## `keyword` (type: `string`):

Optional. Only places whose name (or brand name) contains this text, case-insensitive, e.g. "Starbucks" or "dental".

## `radiusKm` (type: `number`):

Radius for lat/lon (default 5 km). With a city name it searches this radius around the city centre instead of the whole city. Results get distanceKm and come nearest first.

## `countryCode` (type: `string`):

Optional two-letter ISO code (US, DE, GB...). Picks the right city when a name exists in several countries and keeps only places whose address is in that country.

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

Skip places without a phone number.

## `requireWebsite` (type: `boolean`):

Skip places without a website. Skipped places are never charged.

## `requireEmail` (type: `boolean`):

Skip places without a business email (after the personal-email filter).

## `includePhones` (type: `boolean`):

Business phone numbers as published for the place, normalised to E.164 (+15125550100) where possible.

## `includeEmails` (type: `boolean`):

Business emails from the source data. Addresses on the business's own website domain and role mailboxes (info@, office@, bookings@...) are kept; free-mail addresses (gmail, outlook...) are kept only when they contain the business name. Others are dropped as possibly personal and counted in droppedPersonalEmails.

## `matchAlternateCategories` (type: `boolean`):

Also return businesses whose secondary categories match (many contractors list several trades). On by default here.

## `minConfidence` (type: `number`):

Overture's 0-1 confidence that the place exists as described. 0.5 drops most stale or duplicate records; 0.9 keeps only well-corroborated places; 0 returns everything.

## `bbox` (type: `array`):

Optional \[west, south, east, north] in degrees (longitude, latitude, longitude, latitude), e.g. \[-9.20, 38.69, -9.10, 38.76]. Up to 1.5 x 1.5 degrees (about one metro area). Takes priority over location.

## `lat` (type: `number`):

Optional centre latitude for a radius search (with lon and radiusKm). Takes priority over location.

## `lon` (type: `number`):

Optional centre longitude for a radius search.

## `includeFields` (type: `array`):

Optional. Keep only these fields in each row (id is always kept). Any of: id, name, category, basicCategory, categoryHierarchy, alternateCategories, confidence, operatingStatus, address, fullAddress, lat, lon, distanceKm, phones, websites, emails, socials, brand, sources, licence, licenceUrls, attribution, googleMapsUrl, overtureRelease, droppedPersonalEmails. Keep attribution if you republish the data.

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

Optional, advanced: pin an Overture release such as 2026-09-23.1. Empty = the newest release (Overture publishes monthly).

## Actor input object example

```json
{
  "location": "Dallas, TX",
  "categories": [
    "plumbing",
    "electrician",
    "hvac_service",
    "roofing"
  ],
  "maxPlaces": 50,
  "keyword": "",
  "countryCode": "",
  "requirePhone": false,
  "requireWebsite": false,
  "requireEmail": false,
  "includePhones": true,
  "includeEmails": true,
  "matchAlternateCategories": true,
  "minConfidence": 0.5,
  "includeFields": [],
  "release": ""
}
```

# Actor output Schema

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

One row per home-service business with trade, contacts and address (charged).

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

OUTPUT record: the resolved area and categories, Overture release, query time and MiB read, billing summary, licences and (when Foursquare rows are present) the Foursquare NOTICE.

# 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 = {
    "location": "Dallas, TX",
    "categories": [
        "plumbing",
        "electrician",
        "hvac_service",
        "roofing"
    ],
    "maxPlaces": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("actor-forge/home-services-contractor-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 = {
    "location": "Dallas, TX",
    "categories": [
        "plumbing",
        "electrician",
        "hvac_service",
        "roofing",
    ],
    "maxPlaces": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("actor-forge/home-services-contractor-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 '{
  "location": "Dallas, TX",
  "categories": [
    "plumbing",
    "electrician",
    "hvac_service",
    "roofing"
  ],
  "maxPlaces": 50
}' |
apify call actor-forge/home-services-contractor-leads --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,actor-forge/home-services-contractor-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/lcCk6oRbMknrAP5sI/builds/mTpIEf7EomgFKQOSH/openapi.json