# US Building Permits Scraper (`heenalr/us-building-permits`) Actor Normalized building-permit records from US cities' official open-data portals. Multi-city, fresh daily, no API key required. - **URL**: https://apify.com/heenalr/us-building-permits.md - **Developed by:** [Heenal Rajani](https://apify.com/heenalr) (community) - **Categories:** Agents, Developer tools, Real estate - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $4.00 / 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 ## US Building Permits Scraper 🏗️ Get clean, normalized **building-permit records from major US cities** — Chicago, New York City, Austin, and San Francisco — in one consistent format, updated daily, with **no API key and no setup**. A drop-in **building-permit data API** and **construction-permits scraper** for lead generation, real-estate market research, and AI agents. This actor pulls directly from each city's **official government open-data portal** (Socrata), so the data is public, legitimate, and fresh — typically including permits issued the same day. It normalizes every city's different column names into a single schema, so you can pull permits from four cities and get identical fields back every time. ### Who uses this - **Contractors & trades** finding new jobs — pull every electrical, roofing, HVAC, or demolition permit issued this week in your city. - **Sales teams** at suppliers, insurers, and service businesses building lead lists from fresh construction activity. - **Proptech & real-estate analysts** tracking development and renovation trends by neighborhood. - **AI agents & data pipelines** that need a reliable, structured permits feed (this actor returns clean JSON and runs as an MCP tool). ### What you get Every permit is returned in this normalized schema: | Field | Description | |---|---| | `city` | City the permit is from | | `permit_id` | Official permit / job number | | `permit_type` | Type of permit | | `permit_status` | Current status | | `work_description` | Description of the work | | `issue_date` | Date the permit was issued/approved | | `applied_date` | Date the application was filed (where available) | | `address` | Street address | | `zip` | ZIP code | | `estimated_cost` | Estimated job cost (where the city publishes it) | | `contractor` | Contractor / applicant / owner business (where available) | | `latitude`, `longitude` | Coordinates (where available) | | `source_url` | Link to the source dataset | ### Input | Field | Required | Description | |---|---|---| | `city` | ✅ | `chicago`, `nyc`, `austin`, or `sf` | | `maxResults` | | Max permits to return, newest first (default 1000) | | `issuedSince` | | Only permits issued on/after this date (`YYYY-MM-DD`) | | `issuedUntil` | | Only permits issued on/before this date (`YYYY-MM-DD`) | | `zip` | | Filter by ZIP code | | `permitTypeContains` | | Substring filter on type/description, e.g. `electrical`, `solar`, `demolition` | #### Example ```json { "city": "chicago", "issuedSince": "2026-06-01", "permitTypeContains": "electrical", "maxResults": 5000 } ```` Returns every Chicago electrical permit issued since June 1, 2026, newest first. ### Pricing **Pay per result** — you are charged only for permits actually returned. A run that returns 0 permits costs nothing. ### How it works The actor queries each city's Socrata SODA API with server-side date filtering and pagination, only returns permits that have a real issue date (newest first), and maps each city's columns onto the normalized schema above. Because it uses official public endpoints, there is no scraping of protected pages, no login, and no anti-bot fragility. ### FAQ **Is this legal?** Yes. All data comes from cities' official open-data portals, published for public use. **How fresh is the data?** As fresh as the city publishes — typically daily. At the time of writing, all four cities return permits issued the same day. **Why these four cities?** They expose complete, dated permit data through stable open-data APIs. More cities are being added — request one in the Issues tab. **Can an AI agent call this?** Yes. The actor returns structured JSON and is available as an MCP tool, billed per result. ### Roadmap - More cities (Los Angeles, Seattle, Boston, Denver, Dallas, Philadelphia) - Contractor-name normalization across cities - Webhook/Standby mode for low-latency single-address lookups # Actor input Schema ## `city` (type: `string`): Which city's building-permit portal to query. ## `maxResults` (type: `integer`): Maximum number of permits to return (newest first). ## `issuedSince` (type: `string`): Only return permits issued on or after this date. ## `issuedUntil` (type: `string`): Only return permits issued on or before this date. ## `zip` (type: `string`): Only return permits whose ZIP code contains this value. ## `permitTypeContains` (type: `string`): Case-insensitive substring filter on permit type or work description (e.g. "electrical", "demolition", "solar"). ## `socrataAppToken` (type: `string`): Optional Socrata app token to raise rate limits on large pulls. Not required for normal use. ## Actor input object example ```json { "maxResults": 1000, "issuedSince": "2026-01-01" } ``` # 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 = {}; // Run the Actor and wait for it to finish const run = await client.actor("heenalr/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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("heenalr/us-building-permits").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 '{}' | apify call heenalr/us-building-permits --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=heenalr/us-building-permits", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "US Building Permits Scraper", "description": "Normalized building-permit records from US cities' official open-data portals. Multi-city, fresh daily, no API key required.", "version": "0.1", "x-build-id": "pywbYoFECbm1496Wc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/heenalr~us-building-permits/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-heenalr-us-building-permits", "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/heenalr~us-building-permits/runs": { "post": { "operationId": "runs-sync-heenalr-us-building-permits", "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/heenalr~us-building-permits/run-sync": { "post": { "operationId": "run-sync-heenalr-us-building-permits", "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": [ "city" ], "properties": { "city": { "title": "City", "enum": [ "chicago", "nyc", "austin", "sf" ], "type": "string", "description": "Which city's building-permit portal to query." }, "maxResults": { "title": "Max results", "minimum": 1, "maximum": 200000, "type": "integer", "description": "Maximum number of permits to return (newest first).", "default": 1000 }, "issuedSince": { "title": "Issued since (YYYY-MM-DD)", "type": "string", "description": "Only return permits issued on or after this date." }, "issuedUntil": { "title": "Issued until (YYYY-MM-DD)", "type": "string", "description": "Only return permits issued on or before this date." }, "zip": { "title": "ZIP code filter", "type": "string", "description": "Only return permits whose ZIP code contains this value." }, "permitTypeContains": { "title": "Permit type / description contains", "type": "string", "description": "Case-insensitive substring filter on permit type or work description (e.g. \"electrical\", \"demolition\", \"solar\")." }, "socrataAppToken": { "title": "Socrata app token (optional)", "type": "string", "description": "Optional Socrata app token to raise rate limits on large pulls. Not required for normal use." } } }, "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 } } } } } } } } } } ```