# Building Permits Scraper - Multi-City Open Data (`jongoose/building-permits-scraper`) Actor Scrape building & construction permits from 12 US cities' official open-data portals into one clean schema: permit number, type, status, issue date, address, work description, valuation, contractor, applicant & lat/lon. Free government APIs, no key. Filter by city, issue date & permit type. - **URL**: https://apify.com/jongoose/building-permits-scraper.md - **Developed by:** [James Scott](https://apify.com/jongoose) (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 $1.00 / 1,000 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/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 Permits Scraper - Multi-City Open Data Pull **building & construction permits from 12 US cities into one clean, normalized schema** - no API key, no account, no anti-bot. Every large US city publishes permits on its own open-data portal with its own column names; this actor translates all of them into the *same* record so you can query dozens of jurisdictions as one feed. Great for **contractors, roofers, solar & HVAC installers, remodelers, suppliers, and real-estate investors** who want fresh permit leads and market intelligence - and for analysts tracking construction activity. ### Supported cities | City | Source | Portal | |------|--------|--------| | Chicago, IL | Socrata | data.cityofchicago.org | | New York, NY | Socrata | data.cityofnewyork.us (DOB NOW) | | Los Angeles, CA | Socrata | data.lacity.org | | San Francisco, CA | Socrata | data.sfgov.org | | Austin, TX | Socrata | data.austintexas.gov | | Seattle, WA | Socrata | data.seattle.gov | | Cincinnati, OH | Socrata | data.cincinnati-oh.gov | | Mesa, AZ | Socrata | citydata.mesaaz.gov | | Montgomery County, MD | Socrata | data.montgomerycountymd.gov | | Baton Rouge, LA | Socrata | data.brla.gov | | Washington, DC | ArcGIS | maps2.dcgis.dc.gov | | West Sacramento, CA | ArcGIS | gis.cityofwestsacramento.org | All data comes from **official government open-data APIs** (Socrata and ArcGIS FeatureServer). These are free, public, key-less endpoints, so runs are fast and cheap and need only Apify's default datacenter proxy. ### Normalized schema (one row per permit) ```json { "city": "Austin, TX", "permit_number": "2026-074994 BP", "permit_type": "Building Permit - New", "status": "Active", "issue_date": "2026-07-10", "application_date": "2026-04-20", "address": "4102 CAT HOLLOW DR AUSTIN TX 78731", "work_description": "New construction in-ground pool and spa.", "valuation": 0.0, "contractor_name": "LOHR Homes", "applicant": "Gil Lohr", "latitude": 30.3623778, "longitude": -97.76570347, "source": "data.austintexas.gov", "source_type": "socrata", "source_url": "https://abc.austintexas.gov/web/permit/public-search-other?...", "scraped_at": "2026-07-10T21:56:20Z" } ```` Not every city publishes every field (e.g. Chicago has no status column, Cincinnati has no coordinates, DC publishes fees rather than construction valuation) - missing values come back as `null` rather than being faked. Coordinates are populated wherever the source provides them (8 of 12 cities). ### Input | Field | Type | Description | |-------|------|-------------| | `cities` | array | Which cities to scrape (multi-select). Leave empty to scrape **all** supported cities. | | `issuedAfter` | date | Only permits issued on/after this date (`YYYY-MM-DD`). Applied server-side per city. | | `permitType` | string | Keyword filter, matched against permit type **and** work description - e.g. `roof`, `solar`, `pool`, `electrical`, `demolition`. | | `maxItems` | integer | Max permits **per city** (so 3 cities x 500 = up to 1,500 rows). Default 1,000. | | `proxyConfiguration` | object | Defaults to Apify datacenter proxy - no residential proxy required. | #### Example input ```json { "cities": ["austin", "los_angeles", "baton_rouge"], "issuedAfter": "2025-01-01", "permitType": "roof", "maxItems": 500 } ``` This returns every roofing permit issued since Jan 2025 across Austin, LA, and Baton Rouge - a ready-made call list for a roofing company. ### Why this actor - **One schema, many cities.** Stop writing a parser per portal - each city's fields are pre-mapped to the same keys. - **Fresh + filterable.** Newest-first, with server-side date filtering and keyword type filtering. - **Complete records.** Address, geo-coordinates, valuation, contractor/applicant, and a link back to the source record where available. - **Zero anti-bot.** Public government JSON APIs - reliable and cheap. - Export as JSON, CSV, Excel, or pull via the Apify API. ### Extending it Adding a city is a single entry in `src/parser.py` -> `CITIES`: point it at the Socrata dataset or ArcGIS FeatureServer, list the `date_field`, and map that portal's column names to the canonical keys. Address and permit-type can be composed from several columns. No fetch-layer changes needed. *** This data is aggregated from public government records for market research and lead generation. It is **not a consumer report** and must not be used for any FCRA-covered purpose (credit, employment, insurance, or tenant screening). # Actor input Schema ## `cities` (type: `array`): Which cities to scrape. Leave empty (or select nothing) to scrape ALL supported cities. Each city is pulled from its official open-data portal and normalized into the same schema. ## `issuedAfter` (type: `string`): Only return permits issued on or after this date (YYYY-MM-DD). Applied server-side per city on that city's issue date. Leave empty for all dates. ## `permitType` (type: `string`): Optional keyword filter (case-insensitive), matched against each permit's type AND work description - e.g. 'roof', 'solar', 'pool', 'electrical', 'demolition'. Leave empty for all types. ## `maxItems` (type: `integer`): Stop after collecting this many permits FROM EACH selected city (so 3 cities x 500 = up to 1,500 rows). ## `proxyConfiguration` (type: `object`): These are open government APIs, so Apify's default datacenter proxy is plenty - no residential proxy needed. ## Actor input object example ```json { "cities": [ "chicago", "los_angeles", "austin" ], "maxItems": 1000, "proxyConfiguration": { "useApifyProxy": true } } ``` # 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", "los_angeles", "austin" ] }; // Run the Actor and wait for it to finish const run = await client.actor("jongoose/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 = { "cities": [ "chicago", "los_angeles", "austin", ] } # Run the Actor and wait for it to finish run = client.actor("jongoose/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 '{ "cities": [ "chicago", "los_angeles", "austin" ] }' | apify call jongoose/building-permits-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=jongoose/building-permits-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Building Permits Scraper - Multi-City Open Data", "description": "Scrape building & construction permits from 12 US cities' official open-data portals into one clean schema: permit number, type, status, issue date, address, work description, valuation, contractor, applicant & lat/lon. Free government APIs, no key. Filter by city, issue date & permit type.", "version": "0.1", "x-build-id": "arKtePjTabtbJsipK" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/jongoose~building-permits-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-jongoose-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/jongoose~building-permits-scraper/runs": { "post": { "operationId": "runs-sync-jongoose-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/jongoose~building-permits-scraper/run-sync": { "post": { "operationId": "run-sync-jongoose-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": { "cities": { "title": "Cities", "type": "array", "description": "Which cities to scrape. Leave empty (or select nothing) to scrape ALL supported cities. Each city is pulled from its official open-data portal and normalized into the same schema.", "items": { "type": "string", "enum": [ "chicago", "new_york", "los_angeles", "san_francisco", "austin", "seattle", "cincinnati", "mesa", "montgomery_county_md", "baton_rouge", "washington_dc", "west_sacramento" ], "enumTitles": [ "Chicago, IL", "New York, NY", "Los Angeles, CA", "San Francisco, CA", "Austin, TX", "Seattle, WA", "Cincinnati, OH", "Mesa, AZ", "Montgomery County, MD", "Baton Rouge, LA", "Washington, DC", "West Sacramento, CA" ] } }, "issuedAfter": { "title": "Issued after (date)", "type": "string", "description": "Only return permits issued on or after this date (YYYY-MM-DD). Applied server-side per city on that city's issue date. Leave empty for all dates." }, "permitType": { "title": "Permit type keyword", "type": "string", "description": "Optional keyword filter (case-insensitive), matched against each permit's type AND work description - e.g. 'roof', 'solar', 'pool', 'electrical', 'demolition'. Leave empty for all types." }, "maxItems": { "title": "Max permits per city", "minimum": 1, "type": "integer", "description": "Stop after collecting this many permits FROM EACH selected city (so 3 cities x 500 = up to 1,500 rows).", "default": 1000 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "These are open government APIs, so Apify's default datacenter proxy is plenty - no residential proxy needed.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } } ```