# US Building Permit Scraper — Construction Lead Gen (`handstands.io/us-building-permit-scraper`) Actor Pull building permits from US city open data portals. Returns permit type, address, project value, contractor name and license. Covers Chicago, NYC, LA, San Francisco. Filter by date, permit type, project value. Built for solar, roofing, HVAC, and construction lead gen. - **URL**: https://apify.com/handstands.io/us-building-permit-scraper.md - **Developed by:** [handstands io](https://apify.com/handstands.io) (community) - **Categories:** Business - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ## US Building Permit Scraper Pull building permits from US city open data portals. Built for construction lead generation - solar installers, roofing contractors, HVAC companies, and suppliers who need fresh permit data to find projects before competitors do. ### What it returns Every permit record includes: | Field | Description | |-------|-------------| | `city`, `state` | City and state | | `permitNumber` | Permit or job number | | `permitType` | Type of permit (e.g. New Construction, Renovation, Electrical) | | `address` | Full street address | | `projectValue` | Reported construction value in USD (where available) | | `contractorName` | Licensed contractor on the permit | | `contractorLicense` | Contractor license number | | `contractorLicenseType` | License type (General Contractor, Electrician, etc.) | | `issueDate` | Date permit was issued | | `status` | Permit status (where available) | | `description` | Work description (where available) | | `latitude`, `longitude` | Coordinates (where available) | ### Supported cities | City | State | Contractor data | Project value | Data freshness | |------|-------|----------------|---------------|----------------| | Chicago | IL | Name + contact type | Yes (reported_cost) | Current (daily updates) | | New York City (or NYC) | NY | License holder name + license no. | Yes (estimated_job_costs) | Current (DOB NOW dataset) | | San Francisco (or SF) | CA | None in this dataset | Yes (revised_cost) | Current | | Los Angeles (or LA) | CA | Business name + license | Yes (valuation) | Typically 12-24 months behind | **Note on Los Angeles:** The LA open data portal permit datasets are not regularly updated and currently reflect data through mid-2023. For current LA leads, the `customEndpoints` option can point to the LADBS permit portal directly if you have access to a more current source. More cities coming. You can also add any Socrata-powered open data portal via `customEndpoints`. ### Example inputs **Get all new construction permits in Chicago issued this year:** ```json { "cities": ["Chicago"], "issuedAfter": "2026-01-01", "permitTypes": ["new construction"], "maxResultsPerSource": 1000 } ```` **Multi-city lead gen sweep:** ```json { "cities": ["Chicago", "Los Angeles", "New York City"], "issuedAfter": "2026-04-01", "maxResultsPerSource": 500 } ``` **High-value projects only (Chicago):** ```json { "cities": ["Chicago"], "issuedAfter": "2026-01-01", "minProjectValue": 50000 } ``` ### Adding your own city Any city running Socrata open data can be added via `customEndpoints`: ```json { "cities": [], "customEndpoints": [ { "domain": "data.seattle.gov", "datasetId": "your-dataset-id", "cityName": "Seattle", "stateCode": "WA", "fields": { "permitNumber": "application_permit_number", "permitType": "permit_type", "issueDate": "issue_date", "streetNumber": "address", "contractorName": "applicant_name" } } ], "issuedAfter": "2026-01-01" } ``` Find your city's dataset at [data.socrata.com](https://www.socrata.com/solutions/open-data/) or by searching `[your city] open data building permits`. ### How permits become leads A permit issued this week means a project is about to start. The lead window is short - typically 2-6 weeks before contractors are already on site. Run this actor on a weekly or daily schedule to catch permits while they're still warm. Example workflow: 1. Run weekly on target cities filtered to relevant permit types 2. Export to CSV and import to your CRM 3. Call the contractor (or property owner) within 48 hours of issue date ### Pricing $1.50 per 1,000 permits (base). Results from all cities in a single run count toward the same total. ### Data sources All data is sourced from official government open data portals via the Socrata SODA API. All datasets are public domain. No scraping - direct API calls only. # Actor input Schema ## `cities` (type: `array`): US cities to pull building permits from. Supported: Chicago, New York City, San Francisco, Los Angeles. Case-insensitive. ## `issuedAfter` (type: `string`): Only return permits issued on or after this date. Format: YYYY-MM-DD. Leave blank for no start date filter. ## `issuedBefore` (type: `string`): Only return permits issued on or before this date. Format: YYYY-MM-DD. Leave blank for no end date filter. ## `permitTypes` (type: `array`): Filter to permits whose type contains one of these strings (case-insensitive). Leave blank for all types. Examples: 'new construction', 'renovation', 'electrical', 'roofing', 'solar'. ## `minProjectValue` (type: `integer`): Only return permits with a reported project value at or above this amount. Set to 0 for no minimum. Not all cities report project value — applies where available. ## `maxResultsPerSource` (type: `integer`): Maximum number of permits to return per city. Set to 0 for no limit. ## `requestDelayMs` (type: `integer`): Milliseconds to wait between paginated API requests. Increase if you encounter rate limits. ## Actor input object example ```json { "cities": [ "Chicago", "Los Angeles", "San Francisco" ], "issuedAfter": "2026-01-01", "issuedBefore": "2026-12-31", "permitTypes": [ "new construction", "renovation" ], "minProjectValue": 0, "maxResultsPerSource": 1000, "requestDelayMs": 300 } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "cities": [ "Chicago" ], "issuedAfter": "2026-01-01", "maxResultsPerSource": 1000 }; // Run the Actor and wait for it to finish const run = await client.actor("handstands.io/us-building-permit-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "cities": ["Chicago"], "issuedAfter": "2026-01-01", "maxResultsPerSource": 1000, } # Run the Actor and wait for it to finish run = client.actor("handstands.io/us-building-permit-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).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": [ "Chicago" ], "issuedAfter": "2026-01-01", "maxResultsPerSource": 1000 }' | apify call handstands.io/us-building-permit-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=handstands.io/us-building-permit-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "US Building Permit Scraper — Construction Lead Gen", "description": "Pull building permits from US city open data portals. Returns permit type, address, project value, contractor name and license. Covers Chicago, NYC, LA, San Francisco. Filter by date, permit type, project value. Built for solar, roofing, HVAC, and construction lead gen.", "version": "0.1", "x-build-id": "J2NDxvAf7Lea6Y9sH" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/handstands.io~us-building-permit-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-handstands.io-us-building-permit-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/handstands.io~us-building-permit-scraper/runs": { "post": { "operationId": "runs-sync-handstands.io-us-building-permit-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/handstands.io~us-building-permit-scraper/run-sync": { "post": { "operationId": "run-sync-handstands.io-us-building-permit-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "cities" ], "properties": { "cities": { "title": "Cities", "type": "array", "description": "US cities to pull building permits from. Supported: Chicago, New York City, San Francisco, Los Angeles. Case-insensitive.", "items": { "type": "string" } }, "issuedAfter": { "title": "Issued after (date)", "type": "string", "description": "Only return permits issued on or after this date. Format: YYYY-MM-DD. Leave blank for no start date filter." }, "issuedBefore": { "title": "Issued before (date)", "type": "string", "description": "Only return permits issued on or before this date. Format: YYYY-MM-DD. Leave blank for no end date filter." }, "permitTypes": { "title": "Permit type filter", "type": "array", "description": "Filter to permits whose type contains one of these strings (case-insensitive). Leave blank for all types. Examples: 'new construction', 'renovation', 'electrical', 'roofing', 'solar'.", "items": { "type": "string" } }, "minProjectValue": { "title": "Minimum project value ($)", "minimum": 0, "type": "integer", "description": "Only return permits with a reported project value at or above this amount. Set to 0 for no minimum. Not all cities report project value — applies where available.", "default": 0 }, "maxResultsPerSource": { "title": "Max results per city", "minimum": 0, "type": "integer", "description": "Maximum number of permits to return per city. Set to 0 for no limit.", "default": 0 }, "requestDelayMs": { "title": "Delay between requests (ms)", "minimum": 0, "maximum": 5000, "type": "integer", "description": "Milliseconds to wait between paginated API requests. Increase if you encounter rate limits.", "default": 300 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```