# Building Permits Scraper - Socrata Open Data (Multi-City) (`bujhmml/building-permits-scraper`) Actor Scrape building and construction permits from any Socrata open-data portal (NYC, SF, Chicago, LA, and hundreds more). Pull issue date, permit and work type, status, address, contractor, owner, coordinates and every column the dataset exposes. HTTP-first, multi-city in one run. - **URL**: https://apify.com/bujhmml/building-permits-scraper.md - **Developed by:** [Ihor Bielievskiy](https://apify.com/bujhmml) (community) - **Categories:** Real estate, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.40 / 1,000 permits 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/platform/actors/running/actors-in-store#pay-per-event ## 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 ## Building Permit Leads Scraper — Contractor Phone, Email & Project Data **A fresh permit is a fresh lead.** When someone pulls a building permit, they are about to spend money — on roofing, solar, HVAC, a remodel, a pool, a demolition. This actor turns any US city's official permit feed into a clean, deduplicated list of **contractor and owner leads** — name, **phone**, **email** and **license** where the city publishes them, plus address, job cost, permit type and dates — ready to drop into your CRM. It calls each city's **official government open-data API** (Socrata) directly, so the data is public, accurate, and there is no anti-bot to fight. **From $0.40 per 1,000 results** — typically several times cheaper than other permit-lead actors. ### Who uses it - **Roofers, solar & HVAC installers** — reach owners the day their permit is issued. - **General contractors & remodelers** — find active projects by type, cost and area. - **Suppliers & subcontractors** — track new construction starts in your market. - **Real-estate & proptech** — renovation and new-build signals, geocoded. - **Sales teams** — a steady, filterable lead list instead of cold lists. ### What you get per lead `permit_number`, `issue_date`, `permit_type`, `work_type`, `status`, `address`, `city`, `state`, `zip_code`, `applicant` (contractor), `owner`, **`applicant_phone`**, **`applicant_email`**, **`contractor_license`**, `cost`, `latitude`, `longitude` — **plus every original column** the city publishes, passed through untouched. Phone, email and license are filled in whenever the source dataset includes them; name, address, permit type and cost are there for essentially every city. Export as **JSON, CSV or Excel**, or pull straight from the API. ### Quick start Every solar permit issued in NYC this year, newest first: ```json { "domain": "data.cityofnewyork.us", "datasetId": "ipu4-2q9a", "searchQuery": "solar", "dateField": "issuance_date", "dateFrom": "2024-01-01", "order": "issuance_date DESC", "maxItems": 1000 } ```` Several cities in one run: ```json { "datasets": [ { "domain": "data.cityofnewyork.us", "datasetId": "ipu4-2q9a" }, { "domain": "data.cityofchicago.org", "datasetId": "ydr8-5enu" }, { "domain": "data.sfgov.org", "datasetId": "i98e-djp9" } ], "searchQuery": "roofing", "maxItems": 5000 } ``` ### Coverage Hundreds of US cities and counties publish permits on Socrata — New York, San Francisco, Chicago, Los Angeles, Austin, Seattle, Dallas, and many more. Point the actor at a city's dataset and you get its full permit history with the same stable field names everywhere, so a workflow built for one city keeps working when you add the next. ### Sample output ```json { "record_id": "row-c5f6_ycr6.syte", "permit_number": "340733647", "issue_date": "06/17/2024", "permit_type": "EW", "work_type": "OT", "status": "ISSUED", "address": "BAY 34 ST", "city": "BROOKLYN", "state": "NY", "applicant": "HENRYSMITH PROPERTY MGMT", "applicant_phone": "7188020246", "contractor_license": "0123456", "cost": 48000, "latitude": 40.599043, "longitude": -73.992006 } ``` ### Inputs | Field | Description | |-------|-------------| | `domain` | City open-data host, e.g. `data.cityofnewyork.us`, `data.sfgov.org`, `data.cityofchicago.org`. | | `datasetId` | The dataset's 4x4 id from its URL, e.g. `ipu4-2q9a` (NYC DOB Permit Issuance). | | `searchQuery` | Keyword across all text columns — `solar`, `roofing`, `HVAC`, `demolition`, `pool`. The fastest way to a niche lead list. | | `dateField` | Date column to filter on, e.g. `issuance_date`. Required for the date range. | | `dateFrom` / `dateTo` | Date range as `YYYY-MM-DD`. Composed into the filter for you. | | `whereClause` | Optional raw SoQL filter, e.g. `borough='MANHATTAN'` or `estimated_cost > 50000`. | | `select` | Columns to keep — slims output and lowers cost. `:id` is always kept. | | `datasets` | List of `{ domain, datasetId, … }` to scrape several cities in one run. | | `maxItems` | Stop after this many records (0 = no limit). | | `order` | SoQL sort, e.g. `issuance_date DESC`. `:id` is appended automatically. | | `appToken` | Optional `X-App-Token`. Not needed for moderate volume; raises the rate limit. | | `proxyConfiguration` | Optional — the API has no anti-bot, so datacenter is plenty. | ### Finding a city's dataset Open the city's permits dataset on its open-data portal and read the URL: the `domain` is the host and the `datasetId` is the 4x4 code (four letters/digits, a dash, four more), e.g. `https://data.cityofnewyork.us/.../ipu4-2q9a`. Paste both in. ### Built for clean lead lists - **Deduplicated** — each row carries the city's internal id; duplicates within a run are dropped. - **Stable pagination** — paging always ends on `:id`, so rows are never skipped or repeated. - **No silent failures** — a bad city, missing dataset, or invalid filter produces a typed error row, so an empty result always means "nothing matched", never a hidden break. - **Billed per record delivered** — error rows and duplicates cost you nothing. ### Plugs into your stack - **Make / Zapier / n8n** — schedule a run and route new permits into a CRM, sheet or Slack. - **API** — pull from the Apify Dataset API or call the actor from your backend. - **MCP** — expose it to an LLM agent via Apify's MCP server and search permits in natural language. ### Notes This reads public open-data APIs that cities publish for exactly this kind of reuse. Follow each portal's terms and the laws that apply to you. Removal requests are honored. ### Who built this I build scrapers for my own projects and publish the ones that turn out genuinely useful. Need a custom scraper, a data pipeline, or a change to this actor? I'm available for freelance work. GitHub: [github.com/bujhmml](https://github.com/bujhmml) · Site: [bujhmml.fun](https://bujhmml.fun) # Actor input Schema ## `domain` (type: `string`): Open-data host, e.g. data.cityofnewyork.us, data.sfgov.org, data.cityofchicago.org. Leave empty if you use the Datasets list below. ## `datasetId` (type: `string`): Socrata dataset identifier, the 4x4 code from the dataset URL (e.g. ipu4-2q9a for NYC DOB Permit Issuance). ## `searchQuery` (type: `string`): Full-text search across all text columns, e.g. solar, roofing, HVAC, demolition. Matches any permit whose text mentions the keyword. Applied to every dataset in the run. ## `dateField` (type: `string`): Column to filter by date, e.g. issuance\_date, issued\_date, status\_date. Required if you set Date from / Date to. Column names differ per dataset — check the dataset's columns. ## `dateFrom` (type: `string`): Keep permits with Date column on or after this date. Format YYYY-MM-DD (e.g. 2024-01-01). Needs Date column set. ## `dateTo` (type: `string`): Keep permits with Date column on or before this date. Format YYYY-MM-DD (e.g. 2024-12-31). Needs Date column set. ## `whereClause` (type: `string`): Optional raw SoQL filter, e.g. borough='MANHATTAN' or estimated\_cost > 50000. AND-merged with the date filter above. Leave empty for everything. ## `select` (type: `string`): Comma-separated columns to return, e.g. issuance\_date, permit\_type, address. Slims output and lowers cost. Leave empty for all columns. :id is added automatically for deduplication on column projections. Raw SoQL scoped to this single public dataset; aggregates like count(*) or borough, count(*) as n with a GROUP BY are passed through as-is (no :id injection, no dedup). ## `datasets` (type: `array`): Scrape several cities/datasets in one run. Each item: { "domain": "data.sfgov.org", "datasetId": "i98e-djp9", "whereClause": "...", "dateField": "...", "dateFrom": "...", "dateTo": "..." }. Per-item filters override the global ones; if omitted, the global values apply. Runs in addition to the single domain/datasetId above. ## `maxItems` (type: `integer`): Stop after this many permit records across all datasets. 0 = no limit. ## `order` (type: `string`): Column(s) to sort by, e.g. issuance\_date DESC for newest first. :id is always appended to keep pagination stable. Defaults to :id. ## `appToken` (type: `string`): Optional X-App-Token. Not required for moderate volume; raises Socrata's per-IP rate limits if you have one. A wrong token makes every request fail with 403. ## `proxyConfiguration` (type: `object`): Apify Proxy. The Socrata API has no anti-bot, so proxies are optional; datacenter is plenty if you want one. ## Actor input object example ```json { "domain": "data.cityofnewyork.us", "datasetId": "ipu4-2q9a", "datasets": [], "maxItems": 100, "proxyConfiguration": { "useApifyProxy": false } } ``` # 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 = { "domain": "data.cityofnewyork.us", "datasetId": "ipu4-2q9a", "datasets": [], "maxItems": 100 }; // Run the Actor and wait for it to finish const run = await client.actor("bujhmml/building-permits-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 = { "domain": "data.cityofnewyork.us", "datasetId": "ipu4-2q9a", "datasets": [], "maxItems": 100, } # Run the Actor and wait for it to finish run = client.actor("bujhmml/building-permits-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 '{ "domain": "data.cityofnewyork.us", "datasetId": "ipu4-2q9a", "datasets": [], "maxItems": 100 }' | apify call bujhmml/building-permits-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=bujhmml/building-permits-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Building Permits Scraper - Socrata Open Data (Multi-City)", "description": "Scrape building and construction permits from any Socrata open-data portal (NYC, SF, Chicago, LA, and hundreds more). Pull issue date, permit and work type, status, address, contractor, owner, coordinates and every column the dataset exposes. HTTP-first, multi-city in one run.", "version": "1.2", "x-build-id": "snWgWTnXCW0zEml69" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/bujhmml~building-permits-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-bujhmml-building-permits-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/bujhmml~building-permits-scraper/runs": { "post": { "operationId": "runs-sync-bujhmml-building-permits-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/bujhmml~building-permits-scraper/run-sync": { "post": { "operationId": "run-sync-bujhmml-building-permits-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", "properties": { "domain": { "title": "Socrata domain", "type": "string", "description": "Open-data host, e.g. data.cityofnewyork.us, data.sfgov.org, data.cityofchicago.org. Leave empty if you use the Datasets list below." }, "datasetId": { "title": "Dataset id (4x4)", "pattern": "^[a-z0-9]{4}-[a-z0-9]{4}$", "type": "string", "description": "Socrata dataset identifier, the 4x4 code from the dataset URL (e.g. ipu4-2q9a for NYC DOB Permit Issuance)." }, "searchQuery": { "title": "Keyword search", "maxLength": 2000, "type": "string", "description": "Full-text search across all text columns, e.g. solar, roofing, HVAC, demolition. Matches any permit whose text mentions the keyword. Applied to every dataset in the run." }, "dateField": { "title": "Date column", "type": "string", "description": "Column to filter by date, e.g. issuance_date, issued_date, status_date. Required if you set Date from / Date to. Column names differ per dataset — check the dataset's columns." }, "dateFrom": { "title": "Date from", "type": "string", "description": "Keep permits with Date column on or after this date. Format YYYY-MM-DD (e.g. 2024-01-01). Needs Date column set." }, "dateTo": { "title": "Date to", "type": "string", "description": "Keep permits with Date column on or before this date. Format YYYY-MM-DD (e.g. 2024-12-31). Needs Date column set." }, "whereClause": { "title": "Filter (SoQL $where)", "maxLength": 2000, "type": "string", "description": "Optional raw SoQL filter, e.g. borough='MANHATTAN' or estimated_cost > 50000. AND-merged with the date filter above. Leave empty for everything." }, "select": { "title": "Columns to keep (SoQL $select)", "maxLength": 2000, "type": "string", "description": "Comma-separated columns to return, e.g. issuance_date, permit_type, address. Slims output and lowers cost. Leave empty for all columns. :id is added automatically for deduplication on column projections. Raw SoQL scoped to this single public dataset; aggregates like count(*) or borough, count(*) as n with a GROUP BY are passed through as-is (no :id injection, no dedup)." }, "datasets": { "title": "Datasets (multi-city)", "type": "array", "description": "Scrape several cities/datasets in one run. Each item: { \"domain\": \"data.sfgov.org\", \"datasetId\": \"i98e-djp9\", \"whereClause\": \"...\", \"dateField\": \"...\", \"dateFrom\": \"...\", \"dateTo\": \"...\" }. Per-item filters override the global ones; if omitted, the global values apply. Runs in addition to the single domain/datasetId above." }, "maxItems": { "title": "Max results", "minimum": 0, "maximum": 10000000, "type": "integer", "description": "Stop after this many permit records across all datasets. 0 = no limit.", "default": 100 }, "order": { "title": "Sort order (SoQL $order)", "maxLength": 2000, "type": "string", "description": "Column(s) to sort by, e.g. issuance_date DESC for newest first. :id is always appended to keep pagination stable. Defaults to :id." }, "appToken": { "title": "Socrata app token", "type": "string", "description": "Optional X-App-Token. Not required for moderate volume; raises Socrata's per-IP rate limits if you have one. A wrong token makes every request fail with 403." }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Apify Proxy. The Socrata API has no anti-bot, so proxies are optional; datacenter is plenty if you want one.", "default": { "useApifyProxy": false } } } }, "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 } } } } } } } } } } ```