# PermitIQ — Building Permit API (`midwest_united/permitiq`) Actor ZIP-level market trends + urgency-scored contractor leads from Chicago, Austin, NYC, LA & SF. The only permit actor with hotspot scoring and month-over-month analysis. Official Socrata APIs — no scraping. MCP-ready for AI agents. - **URL**: https://apify.com/midwest\_united/permitiq.md - **Developed by:** [Jim Giganti](https://apify.com/midwest_united) (community) - **Categories:** Lead generation, Real estate, AI - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $10.00 / 1,000 permit records This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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 ## PermitIQ — US Building Permit Intelligence API PermitIQ is the only building permit actor with ZIP-level market trend analysis and month-over-month hotspot scoring. Query official government APIs across **Chicago, Austin, NYC, Los Angeles, and San Francisco** — get urgency-scored contractor leads, market trend data by ZIP code, or raw permit records for AI pipelines. No scraping, no browser automation, no proxies. Direct Socrata API access. MCP-ready for Claude, Cursor, and any AI agent. --- ### What it does PermitIQ returns structured building permit data in three output modes tuned for different buyers: | Mode | Use case | Output | |---|---|---| | `leads` | Contractor outreach, sales prospecting | Urgency-scored permits sorted by opportunity value | | `trends` | Market research, territory planning | ZIP-level hotspot scores + month-over-month volume delta | | `raw` | Data pipelines, AI agents, custom analysis | Normalized records with explicit nulls, MCP-ready | --- ### Quick start #### Input | Parameter | Required | Description | |---|---|---| | `cities` | ✅ | `chicago`, `austin`, `nyc`, `los_angeles`, `san_francisco` | | `outputMode` | — | `leads` (default), `trends`, or `raw` | | `permitType` | — | `all` (default), `roofing`, `hvac`, `plumbing`, `electrical`, `new_construction`, `remodel`, `solar`, `adu` | | `daysBack` | — | Days of history to retrieve (default: 30, max: 365) | | `maxResults` | — | Record cap (default: 100) | | `minEstimatedCost` | — | Filter by minimum project value in USD | | `zipCode` | — | Restrict to a single ZIP code | | `budgetUsd` | — | Spend cap based on $0.01/record PPE pricing | #### Example: roofing leads in Chicago, last 7 days ```json { "cities": ["chicago"], "outputMode": "leads", "permitType": "roofing", "daysBack": 7, "maxResults": 50 } ```` #### Example: ADU permits in Los Angeles and San Francisco ```json { "cities": ["los_angeles", "san_francisco"], "outputMode": "leads", "permitType": "adu", "daysBack": 30 } ``` #### Example: market trend analysis across California cities ```json { "cities": ["los_angeles", "san_francisco"], "outputMode": "trends", "daysBack": 90 } ``` #### Example: all 5 cities, raw mode for AI pipeline ```json { "cities": ["chicago", "austin", "nyc", "los_angeles", "san_francisco"], "outputMode": "raw", "daysBack": 7, "maxResults": 500 } ``` *** ### Output fields #### Leads mode - `permitId`, `cityId`, `issueDate`, `address`, `zip`, `lat`, `lng` - `normalizedType` — normalized category (roofing, hvac, solar, adu, etc.) - `description` — original permit work description - `permitStatus` — issued | pending | approved | expired | void - `estimatedCost` — project value in USD (see `costType`) - `contractor`, `contractorConfidence` - `urgencyScore` (1–100) — recency + value + type demand - `urgencyLabel` — hot | warm | cool | low #### Trends mode - `zipCode`, `city`, `permitCount`, `totalEstimatedValue` - `hotspotScore` (0–100) — volume + value + growth composite - `momDelta` — month-over-month % change in permit volume #### Raw mode All fields above plus `rawPermitType`, `applicationDate`, `expirationDate`, `costType`, `propertyType`. Explicit `null` on missing fields (no undefined). *** ### ADU opportunity — California 2026 Los Angeles and San Francisco are the highest-volume ADU markets in the US. New 2026 California laws (SB 79, AB 462, SB 543) mandate faster ADU approvals statewide. San Francisco's dataset includes a native `adu` boolean field — the most reliable ADU signal available anywhere. Target buyers: ADU contractors and builders, solar installers, permit expediting firms, real estate investors tracking density. *** ### Pricing Pay-per-result: **$0.01 per record**. Set `budgetUsd` to cap spend. No monthly subscription. *** ### Use with AI agents (MCP) PermitIQ is available as a tool through the **Apify MCP server** at `https://mcp.apify.com`. Any MCP-compatible AI agent (Claude, Cursor, VS Code Copilot, custom LangGraph agents) can call PermitIQ directly without writing API code. #### Dedicated tool URL (recommended) ``` https://mcp.apify.com?tools=actors,Midwest_United/permitiq ``` #### Connect from Claude Desktop Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "apify": { "url": "https://mcp.apify.com", "headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" } } } } ``` Then ask Claude: > "Use PermitIQ to find hot roofing leads in Chicago from the last 7 days" > "Show me ZIP-level permit trends in Los Angeles for the last 90 days" > "Find ADU permits in San Francisco and Los Angeles from the last 30 days" > "Get raw permit records for NYC electrical permits this month" #### Connect from Cursor or VS Code Add to `.cursor/mcp.json` or your VS Code MCP settings: ```json { "mcpServers": { "apify": { "url": "https://mcp.apify.com", "headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" } } } } ``` #### Call via Apify API ```javascript const response = await fetch( 'https://api.apify.com/v2/acts/Midwest_United~permitiq/run-sync-get-dataset-items', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_APIFY_TOKEN' }, body: JSON.stringify({ cities: ['los_angeles', 'san_francisco'], outputMode: 'leads', permitType: 'adu', daysBack: 30 }) } ); const leads = await response.json(); ``` #### Use in an AI pipeline The `raw` output mode is designed for AI pipeline ingestion: - All fields present with explicit `null` — no undefined surprises - Consistent schema across all five cities - `normalizedType` is always a normalized enum, never free text - `issueDate` is always ISO 8601 or null — no date parsing needed *** ### Technical notes **Data sources.** All data comes from official city Socrata open data portals: - Chicago: `data.cityofchicago.org` (dataset `ydr8-5enu`) — daily - Austin: `data.austintexas.gov` (dataset `3syk-w9eu`) — daily - NYC: `data.cityofnewyork.us` — merged from DOB NOW + historical datasets, daily - Los Angeles: `data.lacity.org` (dataset `pi9x-tg5x`) — daily - San Francisco: `data.sfgov.org` (dataset `i98e-djp9`) — weekly **NYC dataset merge.** NYC building permits are split across two Socrata datasets. PermitIQ fetches both and merges by permit number so you get complete records. **SF update frequency.** San Francisco's DBI uploads permit data weekly. Use `daysBack: 30` or greater for SF to ensure records are returned. **SF native ADU field.** San Francisco's dataset includes a dedicated `adu` boolean field. PermitIQ uses this as a high-confidence override — SF ADU permits are the most reliably identified of any city. **Date validation.** All dates are validated with UTC round-trip checking. Invalid dates are rejected rather than silently rolled forward. **SoQL query building.** Query strings are built manually (no `URLSearchParams`) to preserve Socrata's `$` prefixed operators (`$where`, `$limit`, etc.). **Budget cap.** If `budgetUsd` is set, the actor estimates spend before pushing records and exits cleanly if the cap would be exceeded. *** ### Supported cities | City | Dataset | Update frequency | Coordinates | Contractor | |---|---|---|---|---| | Chicago, IL | Socrata `ydr8-5enu` | Daily | ❌ | Via contact scan | | Austin, TX | Socrata `3syk-w9eu` | Daily | ✅ | Direct field | | New York City, NY | Socrata (2 datasets merged) | Daily | Partial | Low confidence | | Los Angeles, CA | Socrata `pi9x-tg5x` | Daily | ✅ | ❌ Not in dataset | | San Francisco, CA | Socrata `i98e-djp9` | Weekly | ✅ | ❌ Separate dataset | Want your city added? Open an issue — any city publishing permits on a Socrata open data portal can be added. # Actor input Schema ## `cities` (type: `array`): One or more cities to query building permits for. Supported values: 'chicago', 'austin', 'nyc', 'los\_angeles', 'san\_francisco'. Example: \["chicago"] or \["los\_angeles", "san\_francisco"] ## `outputMode` (type: `string`): How to format results. Use 'leads' to get urgency-scored contractor leads sorted by opportunity value — best for sales outreach. Use 'trends' to get ZIP-code-level market analysis with hotspot scores and month-over-month permit volume deltas — best for market research. Use 'raw' for normalized permit records with explicit nulls — best for data pipelines and AI agent consumption. ## `permitType` (type: `string`): Filter to a specific permit category. Use 'all' to return all types. Other values: 'roofing', 'hvac', 'plumbing', 'electrical', 'new\_construction', 'remodel', 'solar', 'adu' (accessory dwelling unit). Defaults to 'all'. ## `daysBack` (type: `integer`): How many calendar days of permit history to retrieve, counting back from today. Use 7 for last week's permits (highest urgency leads), 30 for a monthly window, 90 for quarterly trend analysis. Min: 1, Max: 365. Default: 30. ## `maxResults` (type: `integer`): Maximum number of records to return. For 'leads' mode this is the number of scored lead records. For 'trends' mode this is the number of ZIP codes in the output. For 'raw' mode this is the raw permit count. Default: 100. Set to 0 for no limit (use with caution on large cities). ## `minEstimatedCost` (type: `integer`): Only return permits where the estimated project value meets or exceeds this dollar amount. Useful for filtering out small repairs and focusing on high-value jobs. Example: 10000 returns only permits worth $10,000 or more. Default: 0 (no minimum). ## `zipCode` (type: `string`): Optional. Filter results to a single ZIP code. Leave blank to return permits from all ZIP codes in the city. Example: '60614' for Lincoln Park, Chicago. ## `budgetUsd` (type: `number`): Optional. Maximum spend in USD for this actor run based on pay-per-result pricing ($0.01 per record). If estimated cost would exceed this value the actor exits cleanly with the records retrieved so far. Leave blank for no cap. ## Actor input object example ```json { "outputMode": "leads", "permitType": "all", "daysBack": 30, "maxResults": 100, "minEstimatedCost": 0 } ``` # 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("midwest_united/permitiq").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("midwest_united/permitiq").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 midwest_united/permitiq --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=midwest_united/permitiq", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "PermitIQ — Building Permit API", "description": "ZIP-level market trends + urgency-scored contractor leads from Chicago, Austin, NYC, LA & SF. The only permit actor with hotspot scoring and month-over-month analysis. Official Socrata APIs — no scraping. MCP-ready for AI agents.", "version": "1.0", "x-build-id": "AvxRRwENJAsBBHMPR" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/midwest_united~permitiq/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-midwest_united-permitiq", "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/midwest_united~permitiq/runs": { "post": { "operationId": "runs-sync-midwest_united-permitiq", "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/midwest_united~permitiq/run-sync": { "post": { "operationId": "run-sync-midwest_united-permitiq", "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": "One or more cities to query building permits for. Supported values: 'chicago', 'austin', 'nyc', 'los_angeles', 'san_francisco'. Example: [\"chicago\"] or [\"los_angeles\", \"san_francisco\"]", "items": { "type": "string" } }, "outputMode": { "title": "Output Mode", "enum": [ "leads", "trends", "raw" ], "type": "string", "description": "How to format results. Use 'leads' to get urgency-scored contractor leads sorted by opportunity value — best for sales outreach. Use 'trends' to get ZIP-code-level market analysis with hotspot scores and month-over-month permit volume deltas — best for market research. Use 'raw' for normalized permit records with explicit nulls — best for data pipelines and AI agent consumption.", "default": "leads" }, "permitType": { "title": "Permit Type Filter", "enum": [ "all", "roofing", "hvac", "plumbing", "electrical", "new_construction", "remodel", "solar", "adu" ], "type": "string", "description": "Filter to a specific permit category. Use 'all' to return all types. Other values: 'roofing', 'hvac', 'plumbing', 'electrical', 'new_construction', 'remodel', 'solar', 'adu' (accessory dwelling unit). Defaults to 'all'.", "default": "all" }, "daysBack": { "title": "Days Back", "minimum": 1, "maximum": 365, "type": "integer", "description": "How many calendar days of permit history to retrieve, counting back from today. Use 7 for last week's permits (highest urgency leads), 30 for a monthly window, 90 for quarterly trend analysis. Min: 1, Max: 365. Default: 30.", "default": 30 }, "maxResults": { "title": "Max Results", "minimum": 1, "type": "integer", "description": "Maximum number of records to return. For 'leads' mode this is the number of scored lead records. For 'trends' mode this is the number of ZIP codes in the output. For 'raw' mode this is the raw permit count. Default: 100. Set to 0 for no limit (use with caution on large cities).", "default": 100 }, "minEstimatedCost": { "title": "Minimum Estimated Project Cost (USD)", "minimum": 0, "type": "integer", "description": "Only return permits where the estimated project value meets or exceeds this dollar amount. Useful for filtering out small repairs and focusing on high-value jobs. Example: 10000 returns only permits worth $10,000 or more. Default: 0 (no minimum).", "default": 0 }, "zipCode": { "title": "ZIP Code Filter", "type": "string", "description": "Optional. Filter results to a single ZIP code. Leave blank to return permits from all ZIP codes in the city. Example: '60614' for Lincoln Park, Chicago." }, "budgetUsd": { "title": "Budget Cap (USD)", "minimum": 0, "type": "number", "description": "Optional. Maximum spend in USD for this actor run based on pay-per-result pricing ($0.01 per record). If estimated cost would exceed this value the actor exits cleanly with the records retrieved so far. Leave blank for no cap." } } }, "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 } } } } } } } } } } ```