# US Building Permits Leads — 71 Jurisdictions, 28 States (`yuvalstudios/us-building-permits`) Actor

Fresh building permits from 92 official city, county & state open-data feeds (71 jurisdictions, 700+ towns, 28 states). Trade tags (roofing, solar, HVAC, pool, ADU, new construction), project value, address, contractor name/license/phone. Filter by city, town, ZIP, trade, value.

- **URL**: https://apify.com/yuvalstudios/us-building-permits.md
- **Developed by:** [Yuval Gabay](https://apify.com/yuvalstudios) (community)
- **Categories:** Lead generation, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.50 / 1,000 permit 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

## US Building Permits Leads — 71 Jurisdictions, 700+ Towns, 28 States

**Fresh building permits from 92 official US city, county and state open-data feeds (71 permit-issuing jurisdictions, 310+ towns with fresh data plus 415 New Jersey municipalities) in one clean schema.** Every permit comes with issue date, project value, address, ZIP, coordinates, the contractor (and license or phone where the city publishes them), and **normalized trade tags** — roofing, solar, HVAC, pool, ADU, new construction and 11 more — so you can pull "every roofing permit over $10,000 in Texas and California this week" in one run.

No API key, no login, no proxies, no scraping of fragile web pages: every row comes straight from a government open-data API and links back to its official source.

### Who it's for

| You are… | Use it to… |
|---|---|
| **Roofers, solar installers, HVAC, pool & remodeling contractors** | See who just pulled a permit in your territory — homeowners and GCs about to spend money — and spot which competitors are winning jobs. |
| **Lead-gen & marketing agencies** | Build a daily, trade-filtered permit feed per client (one memory key per client, new permits only). |
| **Building-material suppliers & distributors** | Find contractors with active jobs and big projects (new construction ≥ $500k) before they buy materials. |
| **Real-estate investors, lenders & insurers** | Track new construction, ADUs and renovations by ZIP; spot neighbourhoods that are heating up. |
| **Analysts, journalists, proptech builders** | One normalized schema across 71 jurisdictions instead of 92 different portal formats. |

### What you get (real rows from 2026-10-20)

| Issued | City | Trades | Value (USD) | Address | Contractor |
|---|---|---|---|---|---|
| 2026-10-20 | New York City | roofing, solar | 51,250 | 9521 150 ROAD, Queens | MOMENTUM SOLAR |
| 2026-10-20 | New York City | roofing, hvac, electrical | 114,997 | 1775 GRAND CONCOURSE, Bronx | OCS BUILDERS GROUP LLC |
| 2026-10-20 | Chicago | solar, remodel | 1,007,979 | 5220 S PULASKI RD | CODY LUDWIG |
| 2026-10-20 | Chicago | newConstruction | 94,000,000 | 1331 S WELLS ST | PEPPER CONSTRUCTION COMPANY |
| 2026-10-19 | Mesa | roofing, hvac, electrical | 171,826 | 50 W 7TH ST | ZONA RESTORATION LLC |
| 2026-10-19 | Cambridge | newConstruction | 640,000 | 44 Russell St, Cambridge, MA 02140 | (licensed CS-119631) |

Full record (JSON):

```json
{
  "permitId": "NYC-B01471149-I1-GC",
  "permitNumber": "B01471149-I1-GC",
  "city": "New York City", "state": "NY", "cityCode": "NYC",
  "issuedDate": "2026-10-20", "appliedDate": null,
  "permitType": "Initial Permit", "workType": "General Construction",
  "description": "APPLICATION FILED HEREWITH A FOR FACADE RENOVATION AND ROOF REPLACEMENT TO THE REFERENCED2 1/2 STORY BUILDING, TWO (2) FAMILY BUILDING ...",
  "tradeTags": ["roofing", "remodel"], "isNewConstruction": false,
  "estimatedValue": 17945, "status": "Permit Issued",
  "address": "1183 EAST 12 STREET, Brooklyn", "zip": "11230",
  "latitude": 40.620727, "longitude": -73.963377,
  "contractorName": "M. INT'L ENGINEERING PLLC", "contractorLicense": "GC 602538",
  "contractorPhone": null, "contractorAddress": "85-18 212TH STREET",
  "ownerName": null, "propertyUse": null, "housingUnits": null,
  "sourceName": "NYC Department of Buildings — DOB NOW: Build Approved Permits",
  "sourceDataset": "https://data.cityofnewyork.us/d/rbx6-tga4",
  "sourceUrl": "https://a810-bisweb.nyc.gov/bisweb/PropertyProfileOverviewServlet?bin=3180263",
  "scrapedAt": "2026-10-22T07:22:30.210Z"
}
```

The dataset has three ready-made table views: **Permits overview**, **Contractor leads** (contractor, license, phone, trades, value) and **Locations** (for maps / territory routing). Export to CSV, Excel, JSON, or pull it through the API, webhooks, Zapier/Make or the Apify MCP server.

### Coverage (measured 2026-10-22)

**71 jurisdictions · 92 datasets · 28 states · 727 distinct places** (312 with fresh data in 27 states + 415 New Jersey municipalities from the lagged statewide feed).

Every source below was validated on 2026-10-22: newest permit within 60 days, stable public API (Socrata SODA, ArcGIS REST, CKAN or CARTO), and field mapping checked on up to 1,000 permits issued 2026-09-22 … 2026-10-22. Percentages are **measured fill rates** in that sample — the share of permits where the field is present. "Places in feed" counts the distinct towns appearing in county/state feeds over the last 60 days.

| State | Code | Jurisdiction | Platform | Datasets | Places in feed | Value | Contractor | Address | Lat/lng | Newest permit |
|---|---|---|---|---|---|---|---|---|---|---|
| AZ | MCPA | Maricopa | ArcGIS | 1 | 1 | 0% | 0% | 99% | 100% | 2026-09-14 |
| AZ | MESA | Mesa | Socrata | 1 | 1 | 81% | 47% | 99% | 100% | 2026-10-19 |
| AZ | SCOT | Scottsdale | ArcGIS | 1 | 1 | 75% | 80% | 100% | 40% | 2026-10-16 |
| AZ | TUC | Tucson | ArcGIS | 2 | 1 | 57% | 0% | 100% | 100% | 2026-10-21 |
| CA | ANA | Anaheim | ArcGIS | 1 | 1 | 42% | 82% | 100% | 100% | 2026-10-21 |
| CA | ATAS | Atascadero | ArcGIS | 1 | 1 | 0% | 0% | 100% | 100% | 2026-10-21 |
| CA | CAMP | Campbell | ArcGIS | 1 | 1 | 0% | 0% | 100% | 100% | 2026-10-16 |
| CA | COR | Corona | Socrata | 1 | 1 | 58% | 0% | 100% | 100% | 2026-10-15 |
| CA | LA | Los Angeles | Socrata | 3 | 1 | 33% | 0% | 100% | 100% | 2026-10-17 |
| CA | MARIN | Marin County | Socrata | 1 | 1 | 99% | 98% | 100% | 99% | 2026-10-21 |
| CA | ROSE | Roseville | Socrata | 1 | 1 | 100% | 0% | 0% | 0% | 2026-09-30 |
| CA | SDCO | San Diego County (unincorporated) | Socrata | 1 | 38 | 20% | 88% | 100% | 0% | 2026-10-21 |
| CA | SF | San Francisco | Socrata | 1 | 1 | 100% | 0% | 100% | 100% | 2026-10-20 |
| CA | SJ | San Jose | CKAN | 1 | 1 | 34% | 85% | 100% | 0% | 2026-10-19 |
| CO | DEN | Denver | ArcGIS | 2 | 1 | 88% | 99% | 100% | 100% | 2026-10-20 |
| CT | HFD | Hartford | ArcGIS | 1 | 1 | 98% | 0% | 100% | 0% | 2026-10-21 |
| DC | DC | Washington | ArcGIS | 1 | 1 | 0% | 48% | 100% | 100% | 2026-10-16 |
| FL | MIA | Miami | ArcGIS | 1 | 1 | 93% | 94% | 100% | 100% | 2026-10-20 |
| FL | ORL | Orlando | Socrata | 1 | 1 | 93% | 96% | 100% | 0% | 2026-10-21 |
| FL | PSL | Port St. Lucie | ArcGIS | 1 | 1 | 0% | 0% | 100% | 100% | 2026-10-16 |
| FL | TLH | Tallahassee | ArcGIS | 1 | 1 | 100% | 99% | 100% | 100% | 2026-10-19 |
| FL | TPA | Tampa | ArcGIS | 1 | 1 | 0% | 0% | 100% | 100% | 2026-10-16 |
| IL | CHI | Chicago | Socrata | 1 | 1 | 87% | 97% | 100% | 99% | 2026-10-20 |
| IL | COOK | Cook County (suburban municipalities) | Socrata | 1 | 68 | 66% | 67% | 0% | 0% | 2026-10-14 |
| IL | NRML | Normal | ArcGIS | 1 | 1 | 100% | 96% | 100% | 100% | 2026-09-30 |
| KS | OPKS | Overland Park | ArcGIS | 1 | 1 | 100% | 0% | 100% | 89% | 2026-10-13 |
| KY | LOU | Louisville | ArcGIS | 1 | 52 | 98% | 13% | 100% | 100% | 2026-10-21 |
| LA | BTR | Baton Rouge (East Baton Rouge Parish) | Socrata | 1 | 1 | 66% | 61% | 100% | 99% | 2026-10-20 |
| LA | NOLA | New Orleans | Socrata | 1 | 1 | 57% | 74% | 100% | 0% | 2026-10-22 |
| MA | BOS | Boston | CKAN | 1 | 1 | 99% | 1% | 100% | 98% | 2026-10-20 |
| MA | CAM | Cambridge | Socrata | 4 | 1 | 66% | 98% | 100% | 100% | 2026-10-20 |
| MD | BAL | Baltimore | ArcGIS | 1 | 1 | 87% | 0% | 100% | 100% | 2026-10-21 |
| MD | BACO | Baltimore County | ArcGIS | 3 | 1 | 38% | 1% | 100% | 100% | 2026-10-21 |
| MD | MOCO | Montgomery County | Socrata | 4 | 30 | 28% | 0% | 99% | 97% | 2026-10-22 |
| MI | DET | Detroit | ArcGIS | 2 | 1 | 37% | 57% | 100% | 100% | 2026-10-20 |
| MN | MPLS | Minneapolis | ArcGIS | 1 | 1 | 54% | 100% | 100% | 100% | 2026-10-20 |
| MO | KC | Kansas City | Socrata | 1 | 1 | 1% | 0% | 100% | 96% | 2026-10-16 |
| NC | DUR | Durham (City & County) | ArcGIS | 1 | 1 | 100% | 0% | 0% | 99% | 2026-10-16 |
| NC | MECK | Mecklenburg County (Charlotte & towns) | ArcGIS | 1 | 8 | 100% | 0% | 100% | 100% | 2026-10-20 |
| NC | RAL | Raleigh | ArcGIS | 2 | 1 | 27% | 95% | 100% | 100% | 2026-10-19 |
| NC | WAKE | Wake County (unincorporated & towns) | ArcGIS | 1 | 15 | 99% | 0% | 100% | 100% | 2026-10-20 |
| NJ | NJ | New Jersey (statewide) ⏳ | Socrata | 1 | 415 | 96% | 0% | 0% | 0% | 2026-08-07 |
| NV | HEN | Henderson | ArcGIS | 2 | 1 | 0% | 0% | 96% | 0% | 2026-10-20 |
| NY | NYC | New York City | Socrata | 1 | 1 | 100% | 100% | 100% | 100% | 2026-10-20 |
| OH | CIN | Cincinnati | Socrata | 1 | 1 | 94% | 99% | 100% | 41% | 2026-10-19 |
| OH | CLE | Cleveland | ArcGIS | 1 | 1 | 89% | 91% | 100% | 100% | 2026-10-17 |
| OH | COL | Columbus | ArcGIS | 1 | 1 | 41% | 93% | 100% | 100% | 2026-10-19 |
| OR | MED | Medford | ArcGIS | 1 | 1 | 93% | 99% | 100% | 100% | 2026-10-20 |
| OR | JACO | Phoenix & Talent | ArcGIS | 1 | 1 | 77% | 0% | 100% | 100% | 2026-10-13 |
| OR | PDX | Portland | ArcGIS | 1 | 1 | 100% | 0% | 100% | 100% | 2026-10-01 |
| OR | SLM | Salem | ArcGIS | 1 | 1 | 0% | 0% | 100% | 100% | 2026-10-20 |
| PA | PHL | Philadelphia | CARTO | 1 | 1 | 0% | 88% | 100% | 100% | 2026-10-21 |
| PA | PGH | Pittsburgh | CKAN | 1 | 1 | 96% | 50% | 100% | 100% | 2026-10-20 |
| SC | CHS | Charleston | ArcGIS | 1 | 1 | 100% | 0% | 15% | 75% | 2026-10-14 |
| SC | SUM | Sumter | ArcGIS | 1 | 3 | 0% | 0% | 100% | 100% | 2026-10-16 |
| SD | SXF | Sioux Falls | ArcGIS | 1 | 1 | 100% | 0% | 100% | 100% | 2026-10-17 |
| TN | NASH | Nashville | ArcGIS | 2 | 15 | 99% | 100% | 81% | 99% | 2026-10-20 |
| TX | ARL | Arlington | ArcGIS | 1 | 1 | 66% | 0% | 100% | 100% | 2026-10-21 |
| TX | AUS | Austin | Socrata+ArcGIS | 4 | 1 | 17% | 24% | 100% | 90% | 2026-10-20 |
| TX | CSTX | College Station | Socrata | 1 | 1 | 45% | 0% | 100% | 100% | 2026-10-14 |
| TX | COLLIN | Collin County | Socrata | 1 | 24 | 37% | 98% | 100% | 0% | 2026-10-21 |
| TX | FTW | Fort Worth | ArcGIS | 1 | 1 | 23% | 0% | 100% | 98% | 2026-10-21 |
| TX | SA | San Antonio | ArcGIS | 1 | 1 | 0% | 99% | 100% | 100% | 2026-10-16 |
| TX | SMTX | San Marcos | ArcGIS | 1 | 1 | 0% | 0% | 100% | 100% | 2026-10-21 |
| TX | TYLR | Tyler | ArcGIS | 1 | 1 | 33% | 95% | 100% | 100% | 2026-10-09 |
| VA | NOR | Norfolk | Socrata | 1 | 1 | 90% | 0% | 100% | 94% | 2026-10-20 |
| WA | BELL | Bellevue | ArcGIS | 1 | 1 | 0% | 97% | 100% | 100% | 2026-10-20 |
| WA | EVE | Everett | Socrata | 1 | 1 | 95% | 94% | 100% | 95% | 2026-10-20 |
| WA | PIERCE | Pierce County (unincorporated) | ArcGIS | 1 | 1 | 0% | 0% | 100% | 100% | 2026-10-15 |
| WA | SEA | Seattle | Socrata | 3 | 1 | 59% | 69% | 100% | 100% | 2026-10-20 |
| WA | TAC | Tacoma | ArcGIS | 1 | 1 | 76% | 0% | 99% | 100% | 2026-10-20 |
⏳ = lagged feed (New Jersey DCA publishes ~2–3 months behind; included only when you pick NJ or tick *Include lagged statewide feeds*; measured on 150 days). Maricopa (AZ) refreshes about monthly.

**County & multi-town feeds:** Cook County IL (68 suburban towns via the Assessor), Collin County TX (24 cities via the appraisal district), San Diego County CA (38 communities, unincorporated), Montgomery County MD (30), Louisville Metro KY (52 incl. small cities), Nashville-Davidson TN (15), Wake County NC (15), Mecklenburg County NC (8), Sumter SC (3), New Jersey statewide (415). Use the **Municipalities** input to filter them to a town. Note: a county feed contains only the permits that the county (or its assessor) records — cities that run their own permit office may be partly missing from it.

Feeds are refreshed by the jurisdictions themselves, mostly daily (a few lag 1–3 days).

### Input

| Field | What it does |
|---|---|
| `cities` | Jurisdiction codes from the table. API also accepts names: `"Boston"`, `"Detroit"`. |
| `municipalities` | Town names inside county/state feeds, e.g. `["Plano","Bethesda","Hoboken"]` (also matches single-city datasets of that name). |
| `allJurisdictions` | With no city/state/municipality chosen the actor queries a **fast sample of 20 big datasets**; tick this to query all 92. |
| `includeLaggedSources` | Add the New Jersey statewide feed (≈2–3 months behind). |
| `states` | 2-letter states, e.g. `["CA","TX"]`. |
| `zipCodes` | 5-digit ZIPs. |
| `daysBack` / `issuedFrom` / `issuedTo` | Issue-date window (default: last 7 days). |
| `trades` | Any of: roofing, solar, hvac, electrical, plumbing, pool, adu, newConstruction, demolition, remodel, windowsDoors, siding, signage, fence, masonry, fireProtection, deck. |
| `minValue` | Minimum declared project value (USD). |
| `newConstructionOnly` | New buildings / dwellings only. |
| `keyword` | Text match on description/type (server-side, fast). |
| `maxResults` | Cap (default 100). Shared fairly across datasets; unused share goes to datasets with more. |
| `newSinceLastRun` + `stateKey` | Daily feed: skip permits already delivered under this memory key. |
| `sourceTimeoutSecs` | Time budget; a slow city portal is cut off and the run still succeeds. |

Example — roofing & solar jobs over $10k in California and Texas, last 14 days:

```json
{ "states": ["CA", "TX"], "trades": ["roofing", "solar"], "minValue": 10000, "daysBack": 14, "maxResults": 500 }
```

Example — daily new-construction feed for a supplier in Boston/Cambridge:

```json
{ "cities": ["BOS", "CAM"], "newConstructionOnly": true, "daysBack": 3, "newSinceLastRun": true, "stateKey": "boston-supplier" }
```

### Output fields

| Field | Type | Description |
|---|---|---|
| permitId | string | Unique, stable ID (`CITY-permitNumber`) — use it to dedupe in your CRM |
| permitNumber | string | Permit number as published |
| city, state | string | Municipality of the permit (for county/state feeds: the town on the record) |
| cityCode, jurisdiction | string | Permit-issuing jurisdiction code and name (e.g. `COOK`, "Cook County (suburban municipalities)") |
| issuedDate, appliedDate | date | YYYY-MM-DD |
| permitType, workType | string | As published by the city |
| description | string | Work description |
| tradeTags | string\[] | Normalized trades (see list above) |
| isNewConstruction | boolean | New building / dwelling (city's own new-work class + text, minor items like decks and fences excluded) |
| estimatedValue | number | Declared project value, USD |
| status | string | Permit status |
| address, zip, latitude, longitude | | Site location (coordinates validated) |
| contractorName, contractorLicense, contractorPhone, contractorAddress | string | Where the city publishes them |
| ownerName | string | Property owner **only when it is an organisation** (LLC, Inc, trust, church, city…). Private individuals are never output. |
| propertyUse, housingUnits | | Use / occupancy and units added |
| sourceName, sourceDataset, sourceUrl | string | Official source; `sourceUrl` is the permit's own page where the city has one |
| scrapedAt | datetime | When this run fetched it |

The run's key-value store also holds `OUTPUT_SUMMARY`: per-city status (`ok` / `partial` / `failed`), rows scanned, results, seconds, and duplicates removed.

### Pricing

**$1.50 per 1,000 permits** (pay per result — you pay only for permits delivered; no start fee). 100 permits = $0.15. A daily feed of 200 new permits ≈ $9/month.

How that compares (prices read on 2026-10-22):

| Option | Price per 1,000 permits | Notes |
|---|---|---|
| **This actor** | **$1.50** | 71 jurisdictions / 727 places, trade tags, contractors, per-source status |
| Most-used Apify permit actors | $2.00 – $10.00 (+ start fees up to $0.05/run) | e.g. $2 (pink_comic, paxiq, civic-data-tools), $3 (owlabee, + $0.01 per jurisdiction), $5 (intelscrape), $8, $10 |
| Shovels | $599/month for 25,000 records (≈ $24 / 1,000) | National coverage, subscription |
| Gryd by BuildZoom | from $125–150/month; API only on custom Premium | Subscription |
| ConstructConnect | from $129/month per market | Commercial bid projects |

### Why this one

- **Official sources only** — government open-data APIs, every row links back. No scraping that breaks next week.
- **Trade tags that actually work** — 17 normalized trades matched on type, work class and description (85%+ of permits tagged), with a smart new-construction flag that ignores "new deck" and "new fence".
- **Contractor leads view** — contractor name, license and phone where published (NYC, Austin, Orlando, Mesa, Raleigh, Tallahassee, San Diego County, Anaheim, Nashville, Cleveland, Miami, Denver…).
- **Real breadth, honestly counted** — 71 permit-issuing jurisdictions in 28 states. Some Store actors advertise "248 cities" while most runs fail; every source here passed a freshness and field check on 2026-10-22, and the table shows the measured fill rates.
- **Never fails because one city is down** — each portal is isolated with retries and a time budget; you still get every other city, and the summary tells you exactly which one had a problem.
- **Fair results** — your `maxResults` is shared across cities, so one huge city (NYC, LA) can't crowd out the rest.
- **Built for daily feeds** — `newSinceLastRun` memory per saved search, stable `permitId`, dedup across datasets.
- **Fast** — filters (date, value, keyword) run on the city servers; a default run (fast 20-dataset sample) finishes in seconds; all 92 datasets in about a minute.

### FAQ

**How fresh is the data?** As fresh as each city publishes — most update daily; set `daysBack` to 3–7 for a daily feed.

**Why is value / contractor empty for some cities?** The city does not publish it (see the coverage table). We never guess or fill in data.

**Does it include homeowner names or phone numbers?** No. Only organisation owner names (companies, trusts, institutions) and contractor contact details exactly as the city publishes them.

**Can I get history?** Yes — set `issuedFrom` / `issuedTo` (most feeds go back years) and raise `maxResults`.

**A city I need is missing.** Open an issue on the Issues tab with the city name; cities with an official open-data permit feed are added first (each source is one config entry).

**Why not every US city?** There are ~19,000 US municipalities, but only a few hundred publish permit-level records through a public API, and only New Jersey publishes a statewide permit-level file. We searched the Socrata catalog, ArcGIS Online/Hub, CKAN and OpenDataSoft portals exhaustively (2026-10-22) and include every fresh, stable, US building-permit feed we found. Examples of big-city feeds we checked and had to reject: Phoenix (open-data file last updated 2023), Dallas (stale since 2020), Las Vegas (only 3 permits in the last 30 days), Honolulu (ends June 2025), Gainesville and Somerville (stale). Nationwide coverage beyond this needs paid aggregators or scraping login-protected permit portals, which this actor deliberately does not do.

**Is this legal to use?** The data is published by the governments as open data. You are responsible for complying with marketing laws (e.g. TCPA, CAN-SPAM, do-not-call) when you contact anyone.

### Changelog

See [CHANGELOG.md](./CHANGELOG.md). v1.1 (2026-10-22): 17 → 71 jurisdictions (92 datasets, 28 states), generic ArcGIS/Socrata/CKAN adapters, municipality filter, county & statewide feeds. v1.0: 6 → 17 jurisdictions, new schema, filters, per-source isolation.

***

*Data source: official open-data portals of the jurisdictions listed above. This actor is not affiliated with any government agency. Data is provided as published; check the official record (`sourceUrl`) before relying on it.*

# Changelog

This Actor's version history is a separate document: https://apify.com/yuvalstudios/us-building-permits/changelog.md

# Actor input Schema

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

Permit-issuing jurisdictions to search (cities, counties and one statewide feed). County/statewide feeds contain many municipalities — use Municipalities to narrow them. You can also type a city name (e.g. "Detroit").

## `states` (type: `array`):

Two-letter state codes, e.g. CA, TX, MA. Only jurisdictions in these states are searched.

## `municipalities` (type: `array`):

Exact place names, e.g. "Plano", "Bethesda", "Hoboken". Searches single-city datasets for that city plus every county/statewide dataset (Cook County IL, Collin County TX, San Diego County, Montgomery County MD, Louisville Metro, Nashville, Wake, Mecklenburg, New Jersey…). Note: county feeds only include permits that the county itself or its assessor records.

## `allJurisdictions` (type: `boolean`):

When no city/state/municipality is chosen, the actor queries a fast sample of 20 large datasets. Turn this on to query all 92 datasets (about a minute).

## `includeLaggedSources` (type: `boolean`):

Adds the New Jersey DCA statewide construction-permit file (~415 municipalities). The state publishes it ~2–3 months behind, so use a date range of 90+ days. No street address or contractor in this feed.

## `zipCodes` (type: `array`):

Only permits in these 5-digit ZIP codes, e.g. 78704. Note: Chicago, Norfolk and Mesa feeds publish no ZIP, so a ZIP filter excludes them.

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

Used when no dates are set below. 0 = issued today only.

## `issuedFrom` (type: `string`):

Start of the issue-date range (inclusive). Overrides 'last N days'.

## `issuedTo` (type: `string`):

End of the issue-date range (inclusive). Default: today.

## `trades` (type: `array`):

Only permits tagged with at least one of these trades. Empty = all permits.

## `minValue` (type: `integer`):

Only permits whose declared project value is at least this amount. Permits with no published value are excluded when this is set (Philadelphia publishes no values).

## `newConstructionOnly` (type: `boolean`):

Only new buildings / new dwellings (from the source's own new-work class where available, otherwise from the permit text).

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

Case-insensitive text match on the description / type, e.g. "restaurant", "tesla", "tenant improvement". Runs on the city's server, so it is fast.

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

Maximum permits to output. Shared fairly between the selected jurisdictions; unused share goes to cities that have more. Each permit is billed as one result.

## `newSinceLastRun` (type: `boolean`):

Remembers the permit IDs already delivered and skips them next time. Schedule daily for a fresh lead feed.

## `stateKey` (type: `string`):

Name of the memory used by 'only new permits'. Use a different key per saved search / per client.

## `sourceTimeoutSecs` (type: `integer`):

Overall time budget for querying the city portals. A slow portal is cut off at this point and the run finishes with everything collected so far.

## Actor input object example

```json
{
  "cities": [],
  "states": [],
  "municipalities": [],
  "allJurisdictions": false,
  "includeLaggedSources": false,
  "zipCodes": [],
  "daysBack": 7,
  "trades": [],
  "minValue": 0,
  "newConstructionOnly": false,
  "maxResults": 100,
  "newSinceLastRun": false,
  "stateKey": "default",
  "sourceTimeoutSecs": 120
}
```

# Actor output Schema

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

No description

## `overview` (type: `string`):

No description

## `contractorLeads` (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 = {
    "maxResults": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("yuvalstudios/us-building-permits").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 = { "maxResults": 100 }

# Run the Actor and wait for it to finish
run = client.actor("yuvalstudios/us-building-permits").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 '{
  "maxResults": 100
}' |
apify call yuvalstudios/us-building-permits --silent --output-dataset

```

## MCP server setup

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

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/CMawvnEgRVSpGWgO9/builds/eJqMoAgQqZArkbsYy/openapi.json