# Building Permits Scraper - Contractor Leads, 23 US Cities (`scrapersdelight/building-permits-leads-scraper`) Actor

New building permits as they are issued from 23 US city and county open-data portals in one schema: permit, date, type, description, address, valuation, plus the contractor's name, phone, email and license where the city publishes them. Keyword filter, only-new monitor mode. $0.00035 per permit.

- **URL**: https://apify.com/scrapersdelight/building-permits-leads-scraper.md
- **Developed by:** [Scrapers Delight](https://apify.com/scrapersdelight) (community)
- **Categories:** Lead generation, Real estate, Business
- **Features:** Limited permissions
- **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.35 / 1,000 per building permit delivereds

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

## Building Permits Scraper - New Permits & Contractor Leads from 23 US Cities

Get **new building permits the day the city issues them**, from 23 US cities' and counties' own open-data portals, in **one clean schema**: permit number, issue date, permit type and work class, the scope of work, the job-site address with the city's own lat/lng, the job valuation, and **the contractor - company, name, phone, email and license number - wherever the city publishes them**.

A building permit is a signed statement that someone is about to spend money on construction. Roofers, solar and HVAC installers, pool builders, building-material suppliers, insurers, equipment rental and lead-gen agencies use it as a trigger event: who is building what, where, for how much, and which contractor pulled the permit.

- **23 jurisdictions, 26 official datasets, one schema** - Socrata, CKAN, Carto and ArcGIS portals all normalised to the same 40 fields.
- **Contractor phone** where the city publishes it: Austin (88-92% of permits), Raleigh (75-80%), Orlando (48-53%), Mesa (38%), NYC DOB BIS (100% of BIS permits). **Contractor email**: Raleigh (87-90%), Mesa (28%).
- **Keyword filter on the city's own server** (`solar`, `roof`, `HVAC`, `pool`, `ADU`...), minimum valuation, contractor-only filters.
- **Monitor mode** (`onlyNew`): schedule it daily and receive - and pay for - each permit exactly once.
- **Checked, not assumed**: every run floor-asserts each city against the portal's own count, fails loudly if a city renames a column, and names any city whose feed has stopped publishing (details below).
- **$0.00035 per permit** ($0.35 per 1,000). No start fee.

***

### What one row is

**One row = one building permit** as the city issued it.

- NYC DOB NOW publishes one record per *work type* on a permit (e.g. Foundation + Earth Work); they are folded into one row with `permitType: "Foundation; Earth Work"` (measured: 723 records = 613 permits over two days).
- San Francisco publishes a permit once per address it touches; the primary-address record is the permit.
- Prince George's County publishes a multi-address permit case once per address; the addresses are joined into one row.
- Cincinnati issues several sub-permits (e.g. a New Building and an Excavation/Fill) under one permit number, each with its own value; each is its own row.
- Exact duplicate records a portal publishes twice are dropped and never charged.

### Coverage and field fill

Contact and value fields per city, **measured on two frames**: **A** = the offline test fixtures (complete 1-60-day windows ending 2026-09-22, 3,737 permits) and **B** = a live run that walked **every permit issued 2026-09-15 to 2026-09-22 in all 23 cities** (9,871 permits, the full population, not a sample). One number = both frames agree within 1 point; otherwise A-B.

| City (input key) | Source | Permits / week | Contractor phone | Contractor email | Contractor company | License | Valuation | Geocode |
|---|---|---:|---:|---:|---:|---:|---:|---:|
| Austin, TX (`austin`) | City of Austin Open Data | 955 | **88-92%** | - | 89-92% | - | 0-1% | 61-65% |
| New York City (`new-york-city`) | NYC DOB NOW + DOB BIS | 2,657 | 5% (BIS permits: **100%**) | - | 100% | 100% | 81-85% | 99% |
| Los Angeles, CA (`los-angeles`) | LADBS | 1,049 | - | - | - | - | 94-95% | 100% |
| Philadelphia, PA (`philadelphia`) | L\&I (Carto) | 979 | - | - | 87-88% | - | - | 99-100% |
| Chicago, IL (`chicago`) | Chicago Data Portal | 697 | - | - | 98-99% | - | 81-88% | 98-99% |
| Orlando, FL (`orlando`) | Orlando Open Data | 634 | **48-53%** | - | 95-100% | - | 91-93% | - |
| Washington, DC (`washington-dc`) | DC Dept. of Buildings (ArcGIS) | 573 | - | - | - | - | - | 100% |
| Boston, MA (`boston`) | Analyze Boston (CKAN) | 517 | - | - | - | - | 98-99% | 98-99% |
| New Orleans, LA (`new-orleans`) | New Orleans Open Data | 389 | - | - | 81-83% | - | 78-81% | 100% |
| San Francisco, CA (`san-francisco`) | DataSF (DBI) + DBI contacts | 315 | - | - | 97% | 97% | 81-85% | 100% |
| Montgomery County, MD (`montgomery-county-md`) | DPS (residential + commercial) | 150 | - | - | - | - | 94-100% | 87-98% |
| Norfolk, VA (`norfolk`) | Norfolk Open Data | 141 | - | - | - | - | 83-84% | 89-91% |
| Baton Rouge, LA (`baton-rouge`) | East Baton Rouge Parish | 131 | - | - | 68-69% | - | 68-69% | 100% |
| Seattle, WA (`seattle`) | SDCI | 124 | - | - | 8-11% | - | 98-99% | 100% |
| Cincinnati, OH (`cincinnati`) | CAGIS | 111 | - | - | 99% | - | 94% | 73% |
| Marin County, CA (`marin-county`) | Marin CDA | 94 | - | - | 96% | 9% | 100% | 96% |
| Mesa, AZ (`mesa`) | Mesa Open Data | 86 | **38%** | **28%** | 48% | 48% | 77% | 100% |
| College Station, TX (`college-station`) | City of College Station | 84 | - | - | - | - | 39% | 100% |
| Raleigh, NC (`raleigh`) | Raleigh Open Data (ArcGIS) | 59 | **75-80%** | **87-90%** | 87-92% | - | 91-93% | 100% |
| Corona, CA (`corona`) | CorStat | 54 | - | - | - | - | 50-59% | 100% |
| Collin County, TX (`collin-county-tx`) | Collin CAD (data.texas.gov) | 47 | - | - | 96-99% (builder) | - | 9-12% | - |
| Prince George's County, MD (`prince-georges-county-md`) | DPIE | 18 | - | - | - | - | 11-14% | - |
| Cambridge, MA (`cambridge-ma`) | Inspectional Services (2 datasets) | 7 | - | - | 97-100% | 0-100%\* | 99-100% | 100% |

"-" = the city does not publish that field; it stays `null` and is never guessed. \*Cambridge publishes a license number on new-construction permits only. Across all 9,871 permits of frame B: contractor company 68.4%, contractor phone 14.4%, contractor email 0.8%, owner name 60.5%, valuation 63.8%, description 86.0%, geocode 88.6%. **1,438 permits (14.6%) carried a contractor phone or email** (`hasContractorContact: true`) - filter to exactly those with `contractorFilter: "phoneOrEmail"`.

### Output fields

| Field | What it is |
|---|---|
| `permitId` | Our stable unique key `<cityKey>:<datasetId>:<portal row key>` - de-duplication and monitor mode use it |
| `city`, `cityKey`, `state` | Jurisdiction, the input key, 2-letter state |
| `permitNumber` | The permit / job number exactly as published (NYC BIS: the DOB job number) |
| `issuedDate` | Issue date, `YYYY-MM-DD`, in **the city's own local time zone** |
| `appliedDate` | Application / filing date, where published |
| `status` | The city's own status words |
| `permitType`, `workClass`, `permitClass` | Permit type, work class / sub-type, residential-commercial class or property use |
| `description` | The published scope of work |
| `projectName` | Project / case / subdivision name where a city publishes one (Orlando publishes a project name instead of a description) |
| `address`, `locality`, `zip` | Job-site address as published |
| `latitude`, `longitude` | **The city's own geocode.** We never geocode an address ourselves |
| `valuation` | Declared / estimated job value in USD (`0`, negatives and the nominal `$1` "no estimate" placeholder become `null`) |
| `housingUnits` | Dwelling units on the permit, where published |
| `jurisdiction` | Sub-area the city publishes: Austin full-purpose vs ETJ, Collin County issuing city, LA community plan area, DC ward, SF neighborhood |
| `contractorCompany`, `contractorName` | Contractor / permittee company and named person |
| `contractorPhone`, `contractorEmail` | Contractor phone (as published, 10-15 digits) and email |
| `contractorLicense`, `contractorTrade` | License number; trade or license type (Austin trade, NYC license class, Chicago contact role) |
| `contractorAddress` | Contractor business address |
| `hasContractorContact` | `true` when the row carries a contractor phone or email |
| `applicantName`, `applicantCompany`, `applicantPhone` | Applicant / filer where published |
| `ownerName` | Property owner as the permit publishes it - **never copied into a contractor field** |
| `contacts` | Every role-typed contact the city lists: Chicago (up to 15: owner, general contractor, trade contractors, architect, expediter...) and San Francisco (DBI contacts: contractor, architect, engineer, agent...) as `{role, name, company, license, city, state, zip}` |
| `matchedKeywords` | Which of your keywords the permit matched |
| `detailUrl` | The permit's page on the city's own site, where the dataset links one (Austin, Seattle, Cincinnati) |
| `source`, `datasetId`, `datasetUrl` | Publishing agency and the exact dataset the row came from |
| `scrapedAt` | When this run read the row |

#### Real example row (Raleigh, from the verified run)

```json
{
  "permitId": "raleigh:Building_Permits:BLDR-032987-2026",
  "city": "Raleigh",
  "cityKey": "raleigh",
  "state": "NC",
  "permitNumber": "BLDR-032987-2026",
  "issuedDate": "2026-09-17",
  "appliedDate": "2026-07-08",
  "status": "Permit Issued",
  "permitType": "Building",
  "workClass": "New Residential Dwelling",
  "permitClass": "Residential",
  "description": "New Single Family Dwelling Lot 1 Bickett Blvd Sealed Crawl Rear Deck Fireplace in Living Room DEMO-0",
  "address": "404 Bickett Blvd",
  "locality": "RALEIGH",
  "zip": "27608",
  "latitude": 35.799018105381336,
  "longitude": -78.64165629825408,
  "valuation": 419795.64,
  "jurisdiction": "Inside City Limits",
  "contractorCompany": "Ravenscape Construction, LLC",
  "contractorPhone": "(919) 906-2208",
  "contractorEmail": "ravenscapeconstruction@gmail.com",
  "contractorAddress": "267 Nashville Dr, Archer Lodge, NC 27527",
  "hasContractorContact": true,
  "ownerName": "BERWICK INVESTMENTS LLC",
  "source": "City of Raleigh Open Data",
  "datasetId": "Building_Permits",
  "datasetUrl": "https://services.arcgis.com/v400IkDOw1ad7Yad/arcgis/rest/services/Building_Permits/FeatureServer/0",
  "scrapedAt": "2026-09-23T05:36:08.441Z"
}
```

(Fields that were `null` on this permit are omitted here for length; every row carries all 40 keys.)

### Input

| Input | Default | What it does |
|---|---|---|
| `cities` | Austin, NYC, Chicago, LA, Seattle | Any of the 23 keys in the table above |
| `daysBack` | `7` | Permits issued from N days ago through today, in each city's local date. Max 366 |
| `sinceDate` / `untilDate` | - | Fixed `YYYY-MM-DD` window instead of `daysBack` (backfills, a specific month) |
| `keywords` | - | Keep permits whose description / type / work class contains ANY of these words. Applied **on the city's server**, so you only read (and pay for) matches |
| `minValuation` | `0` | Only permits with a published valuation >= this. Permits with no published valuation are dropped when set |
| `contractorFilter` | `any` | `named` = only permits naming a contractor; `phoneOrEmail` = only permits carrying a contractor phone or email |
| `onlyNew` | `false` | Monitor mode: deliver and charge each permit once across runs (state is kept per filter set) |
| `maxItems` | `100` | Charge cap. Split fairly across the selected cities - a quiet city's unused share rolls to the busy ones |
| `socrataAppToken` | - | Optional Socrata app token for very large pulls; not needed normally |
| `proxyConfiguration` | off | Not needed - public APIs. A request that fails directly is retried through an Apify residential proxy automatically |

#### Examples

Solar and roofing permits with a reachable contractor, last 7 days, three contractor-phone cities:

```json
{ "cities": ["austin", "raleigh", "orlando"], "daysBack": 7, "keywords": ["solar", "roof"], "contractorFilter": "phoneOrEmail", "maxItems": 500 }
```

Daily new-permit feed over $100k in the big four (schedule it daily):

```json
{ "cities": ["new-york-city", "los-angeles", "chicago", "boston"], "daysBack": 3, "minValuation": 100000, "onlyNew": true, "maxItems": 2000 }
```

### Pricing

**$0.00035 per permit delivered** ($0.35 per 1,000). One event, `permit-record`; no start fee, no per-run fee.

Never charged: permits removed by your keyword, valuation or contractor filters; permits already delivered in `onlyNew` mode; duplicate records. A run with the empty input `{}` (5 default cities, 7 days, cap 100) costs at most **$0.035**. Measured: a full week of all 23 cities (9,871 permits) ran in 16 seconds.

### Integrity: why the numbers can be trusted

Open-data feeds fail quietly: a renamed column returns zero rows, a frozen feed returns last month's permits, offset paging can skip rows. This actor turns each of those into a **loud failure** instead of a small, plausible dataset:

- **Floor assertion** - every city walked to the end must yield the portal's own `count(*)` for the exact same filter, or the run fails. Paging uses a stable order (issue date, then the portal's unique row id), so no permit is skipped or repeated between pages.
- **Stale-feed and renamed-column detection** - each city must have issued permits within its staleness window (14 days; 21 for Prince George's County, 120 for Cambridge new construction), and a window of 7+ days must not come back empty for a city that issues permits every week. A city that fails this has stopped publishing new permits: the status message names it with the newest issue date its portal has, the permits it does have in your window are still delivered, and the other cities are unaffected. A query the portal rejects (a renamed column) fails the city by name.
- **Time zones honest** - Socrata portals publish local, zone-less timestamps (verified by hour-of-day histograms); Boston's timestamps are UTC (they peak 12:00-20:00 = 8am-4pm Eastern), Philadelphia's are timestamptz, ArcGIS dates are epoch milliseconds (DC's layer even declares America/New_York for its query literals). Every `issuedDate` is converted to the city's own calendar date, and a row dated outside your window fails the run.
- **Output is a subset of input** - placeholder values (`N/A`, `-`, `0`, a `$1` valuation, a one-digit-repeated phone) become `null`; nothing is geocoded, inferred or copied from one role into another.

When one city fails a check, the permits from every healthy city are still delivered (and charged); the run then ends as FAILED with the failing city and reason in the status message and in `RUN_SUMMARY`. A city whose feed has stopped publishing does not fail the run; it is listed under `staleFeeds`. `RUN_SUMMARY` (in the run's key-value store) also lists, per dataset: the portal's own count, records walked, permits delivered, filtered, merged and duplicate counts, placeholder valuations nulled, and the field fill of this run.

### Data limits

- **Contact data is only what each city publishes.** 18 of the 23 cities publish no contractor phone or email at all (only Austin, NYC BIS, Orlando, Mesa and Raleigh do); LA, Boston, DC, Norfolk, Montgomery County, College Station, Corona and Prince George's County publish no contractor name either. No enrichment, no skip-tracing.
- **Austin publishes a valuation on building permits only**, and many carry the `$1` placeholder - Austin's valuation is 0-1% filled. Philadelphia and DC publish no valuation.
- **Chicago publishes no job-site ZIP** (only contact ZIPs), so `zip` is null there; Mesa and DC carry the ZIP inside the address only.
- **Orlando publishes a project name, not a work description**, and no coordinates; Norfolk publishes neither description nor contractor.
- **Collin County is appraisal-district data**: `contractorCompany` is the builder the CAD records, valuation is rarely filled, and it lags issuance.
- **NYC BIS** (the legacy DOB system, ~130 permits/week) publishes no work description, so a keyword search cannot match it; DOB NOW carries the descriptions.
- **Issue dates only**: the window filters on the issue date. Applications that are not yet issued are not included.
- Coverage is the 23 jurisdictions listed; other cities are not silently included.

### FAQ

**How fresh is it?** Most portals update daily; each city's newest issue date is typically 1-3 days back (Cincinnati and Prince George's County can lag up to a week). Use `daysBack: 3` on a daily schedule with `onlyNew` so a late-published permit is still caught.

**Will monitor mode double-charge me?** No. A permit is marked delivered only after it has been pushed and charged; the next run skips it. The state is kept per filter set (keywords, valuation, contractor filter), so two different schedules do not hide permits from each other.

**Why did my run end FAILED with data in it?** One city failed an integrity check (see the status message). Everything from the healthy cities was delivered. Drop that city from `cities` for the moment and tell us - the fix is usually a one-line config change.

**The status message says a city is "not publishing new permits upstream".** That city's portal has stopped adding permits (the message shows the newest issue date it has). The run still succeeds and delivers what the portal has in your window; the city comes back by itself when the portal resumes.

**Can you add my city?** If it publishes permits on Socrata, CKAN, Carto or ArcGIS, yes - each city is a small config entry, verified against real data before it ships.

# Actor input Schema

## `cities` (type: `array`):

Which cities / counties to pull newly issued building permits from. Each is read from that city's own open-data portal. Contractor phone is published by Austin, NYC (DOB BIS), Mesa, Orlando and Raleigh; contractor email by Mesa and Raleigh; contractor name/company by most others (see the README table).

## `daysBack` (type: `integer`):

Permits issued from this many days ago through today (each city's own local date). 7 = the last week. Ignored when 'Issued on or after' is set. Max 366.

## `sinceDate` (type: `string`):

Optional fixed start date. Overrides 'Days back'.

## `untilDate` (type: `string`):

Optional end date. Leave empty for today.

## `keywords` (type: `array`):

Keep only permits whose work description / permit type / work class contains ANY of these words (case-insensitive), e.g. solar, roof, HVAC, pool, ADU, demolition. Filtered on the city's own server, so it is fast and you only pay for matches. Empty = every permit.

## `minValuation` (type: `integer`):

Keep only permits with a published job valuation of at least this many dollars. Permits whose city publishes no valuation are dropped when this is set (and never charged). 0 = no minimum.

## `contractorFilter` (type: `string`):

any = every permit. named = only permits naming a contractor. phoneOrEmail = only permits carrying a contractor phone or email (Austin, NYC BIS, Mesa, Orlando, Raleigh). Removed rows are never charged.

## `onlyNew` (type: `boolean`):

Remember every permit delivered (per filter set) and deliver - and charge for - each permit only once across runs. Pair with an Apify Schedule (e.g. daily, Days back = 3) for a new-permit feed.

## `maxItems` (type: `integer`):

Stop after this many permits (the charge cap). Split fairly across the selected cities: a quiet city's unused share goes to the others.

## `socrataAppToken` (type: `string`):

Optional app token for the Socrata portals (most cities here) to raise their rate limit on very large pulls. Not needed for normal runs.

## `proxyConfiguration` (type: `object`):

Not needed: every source is a public open-data API. Leave off for a direct connection (fastest, cheapest). A request that fails directly is retried once through an Apify residential proxy automatically.

## Actor input object example

```json
{
  "cities": [
    "austin",
    "new-york-city"
  ],
  "daysBack": 3,
  "minValuation": 0,
  "contractorFilter": "any",
  "onlyNew": false,
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `permits` (type: `string`):

The dataset of building permits (one item per permit).

## `runSummary` (type: `string`):

Per-dataset counts (the portal's own total, walked, delivered, filtered, duplicates) and field fill for this 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 = {
    "cities": [
        "austin",
        "new-york-city"
    ],
    "daysBack": 3,
    "maxItems": 20,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapersdelight/building-permits-leads-scraper").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 = {
    "cities": [
        "austin",
        "new-york-city",
    ],
    "daysBack": 3,
    "maxItems": 20,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("scrapersdelight/building-permits-leads-scraper").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 '{
  "cities": [
    "austin",
    "new-york-city"
  ],
  "daysBack": 3,
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call scrapersdelight/building-permits-leads-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,scrapersdelight/building-permits-leads-scraper"
        }
    }
}
```

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/POOit2YnckV7D4gxP/builds/UT1V7Y66maIu1d4eU/openapi.json
