{
"openapi": "3.0.1",
"info": {
"title": "US Building Permits Scraper - Construction & Contractor Leads",
"description": "Scrape US building permits from official city & county open data: contractor/owner contacts, project value, description, trade (solar, roofing, HVAC, electrical, plumbing), geo & lead score. Filter by city, date, trade & value for fresh construction leads, plus monitoring. No browser.",
"version": "0.1",
"x-build-id": "B3yUavWWqTevejwgc"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/scrapesage~us-building-permits-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-scrapesage-us-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/scrapesage~us-building-permits-scraper/runs": {
"post": {
"operationId": "runs-sync-scrapesage-us-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/scrapesage~us-building-permits-scraper/run-sync": {
"post": {
"operationId": "run-sync-scrapesage-us-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 / counties",
"type": "array",
"description": "Which US city/county open-data portals to pull permits from. Leave empty (or include all) to pull from every supported source. Add more portals with Custom Socrata sources below.",
"items": {
"type": "string",
"enum": [
"all",
"chicago",
"new-york",
"los-angeles",
"san-francisco",
"austin",
"cincinnati",
"mesa",
"baton-rouge",
"montgomery-county",
"collin-county",
"marin-county",
"corona",
"howard-county"
],
"enumTitles": [
"All supported sources",
"Chicago, IL",
"New York City, NY",
"Los Angeles, CA",
"San Francisco, CA",
"Austin, TX",
"Cincinnati, OH",
"Mesa, AZ",
"Baton Rouge, LA",
"Montgomery County, MD",
"Collin County, TX",
"Marin County, CA",
"Corona, CA",
"Howard County, MD"
]
},
"default": [
"austin",
"chicago",
"los-angeles",
"new-york"
]
},
"lastNDays": {
"title": "Last N days (fresh permits)",
"minimum": 1,
"type": "integer",
"description": "Convenience filter — only permits issued in the last N days. Ignored if Issued after is set. Great for daily lead pulls (e.g. 7 or 30)."
},
"issuedAfter": {
"title": "Issued after",
"type": "string",
"description": "Only permits issued on or after this date (YYYY-MM-DD)."
},
"issuedBefore": {
"title": "Issued before",
"type": "string",
"description": "Only permits issued on or before this date (YYYY-MM-DD)."
},
"tradeCategories": {
"title": "Trade categories",
"type": "array",
"description": "Only permits matching these trades (derived from permit type + work class + description). Perfect for solar, roofing, HVAC, electrical or plumbing sales teams.",
"items": {
"type": "string",
"enum": [
"solar",
"roofing",
"hvac",
"electrical",
"plumbing",
"pool_spa",
"demolition",
"new_construction",
"addition_remodel",
"fence",
"sign",
"grading"
],
"enumTitles": [
"Solar / battery",
"Roofing",
"HVAC / mechanical",
"Electrical",
"Plumbing",
"Pool & spa",
"Demolition",
"New construction",
"Addition / remodel",
"Fence",
"Sign",
"Grading / site work"
]
}
},
"keyword": {
"title": "Keyword",
"type": "string",
"description": "Free-text search within the permit description / type (e.g. swimming pool, solar pv, kitchen remodel)."
},
"minProjectValue": {
"title": "Minimum project value (USD)",
"minimum": 0,
"type": "integer",
"description": "Only permits with a reported/estimated project value at or above this amount. Filters out small jobs and surfaces high-value leads."
},
"zipCodes": {
"title": "ZIP codes",
"type": "array",
"description": "Only permits in these ZIP codes (applied where the source publishes a ZIP field).",
"items": {
"type": "string"
}
},
"onlyWithContractorContact": {
"title": "Only permits with a contractor/applicant contact",
"type": "boolean",
"description": "Keep only permits that include a contractor, builder or applicant name — i.e. ready-to-contact construction leads.",
"default": false
},
"maxResultsPerCity": {
"title": "Max results per city",
"minimum": 1,
"type": "integer",
"description": "Cap permits returned from each source. Permits are returned newest-issued first.",
"default": 500
},
"maxResults": {
"title": "Max results (total)",
"minimum": 1,
"type": "integer",
"description": "Overall cap on permits across all selected sources.",
"default": 1000
},
"monitorMode": {
"title": "Monitor mode (only new permits)",
"type": "boolean",
"description": "Remembers every permit it has already returned (in a named key-value store) and emits only permits it has not seen before. Schedule this actor (e.g. daily) and each run delivers only fresh permits — ideal for a continuous lead feed. Works alongside Apify Schedules.",
"default": false
},
"monitorStoreName": {
"title": "Monitor store name",
"type": "string",
"description": "Name of the key-value store that holds seen-permit state (lowercase, digits and hyphens only).",
"default": "building-permits-monitor"
},
"monitorKey": {
"title": "Monitor key (saved-search namespace)",
"type": "string",
"description": "Optional. Keeps separate monitor state per saved search (e.g. solar-texas) so different scheduled runs don't share a seen-list."
},
"customSocrataSources": {
"title": "Custom Socrata sources (advanced)",
"type": "array",
"description": "Add any other government Socrata permit portal. Each item: { \"domain\": \"data.x.gov\", \"datasetId\": \"abcd-1234\", \"dateField\": \"issued_date\", \"city\": \"Springfield\", \"state\": \"IL\", \"permitNumberField\": \"permit_number\", \"descField\": \"description\", \"valueField\": \"valuation\", \"addressField\": \"address\", \"zipField\": \"zip\" }. Only domain, datasetId and dateField are required."
},
"socrataAppToken": {
"title": "Socrata app token (optional)",
"type": "string",
"description": "Optional Socrata app token for higher rate limits on very large pulls. Not required — these portals work anonymously."
},
"proxyConfiguration": {
"title": "Proxy configuration",
"type": "object",
"description": "Optional. Government open-data portals work without proxies, but proxy rotation helps avoid per-IP rate limits on very large pulls.",
"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
}
}
}
}
}
}
}
}
}
}