{ "openapi": "3.0.1", "info": { "title": "US Building Permits Scraper — 45 Cities, 22 States", "description": "Issued US building permits from 45 jurisdictions in 22 states — NYC, Chicago, LA County, San Francisco, Austin, Seattle. One normalised trade vocabulary, valuation with its basis, contractor, address, dates, and a named reason for every empty field. Pick cities or states, pick a date window.", "version": "0.11", "x-build-id": "7M6KY3H3Rd3jOpqfi" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ai-lead-gen-tools~us-building-permits-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ai-lead-gen-tools-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/ai-lead-gen-tools~us-building-permits-scraper/runs": { "post": { "operationId": "runs-sync-ai-lead-gen-tools-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/ai-lead-gen-tools~us-building-permits-scraper/run-sync": { "post": { "operationId": "run-sync-ai-lead-gen-tools-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", "type": "array", "description": "Which jurisdictions to fetch. Leave empty for all 45. This is the precise control: a state can hold several unrelated permit systems, so picking a state is not the same as picking a city.", "items": { "type": "string", "enum": [ "us-fl-alachua", "us-md-baltimore-city", "us-co-boulder-county", "us-ca-san-francisco", "us-pa-allentown", "us-ca-anaheim", "us-co-aspen", "us-tx-austin", "us-wa-bellevue", "us-id-boise", "us-co-boulder", "us-il-chicago", "us-oh-cincinnati", "us-oh-cleveland", "us-oh-columbus", "us-mi-detroit", "us-fl-fort-pierce", "us-ct-hartford", "us-tx-kerrville", "us-nm-las-cruces", "us-tn-memphis", "us-fl-miami", "us-il-naperville", "us-la-new-orleans", "us-ks-overland-park", "us-oh-oxford", "us-ca-placentia", "us-nc-raleigh", "us-tx-san-antonio", "us-tx-san-marcos", "us-wa-seattle", "us-ma-somerville", "us-wa-tacoma", "us-or-talent", "us-az-tempe", "us-az-coconino", "us-co-douglas", "us-ca-la-county", "us-ky-louisville", "us-az-maricopa", "us-md-bpds", "us-tn-nashville", "us-fl-miami-dade", "us-ny-nyc", "us-ca-sacramento-county" ], "enumTitles": [ "Alachua County, FL", "Baltimore City, MD", "Boulder County (unincorporated), CO", "City and County of San Francisco, CA", "City of Allentown, PA", "City of Anaheim, CA", "City of Aspen, CO", "City of Austin, TX", "City of Bellevue, WA", "City of Boise, ID", "City of Boulder, CO", "City of Chicago, IL", "City of Cincinnati, OH", "City of Cleveland, OH", "City of Columbus, OH", "City of Detroit, MI", "City of Fort Pierce, FL", "City of Hartford, CT", "City of Kerrville, TX", "City of Las Cruces, NM", "City of Memphis / Shelby County, TN", "City of Miami, FL", "City of Naperville, IL", "City of New Orleans, LA", "City of Overland Park, KS", "City of Oxford, OH", "City of Placentia, CA", "City of Raleigh, NC", "City of San Antonio, TX", "City of San Marcos, TX", "City of Seattle, WA", "City of Somerville, MA", "City of Tacoma, WA", "City of Talent, OR", "City of Tempe, AZ", "Coconino County, AZ", "Douglas County, CO", "Los Angeles County (unincorporated and contract cities), CA", "Louisville Metro / Jefferson County, KY", "Maricopa County, AZ", "Maryland Building Permit Data System, MD", "Metro Nashville / Davidson County, TN", "Miami-Dade County, FL", "New York City, NY", "Sacramento County, CA" ] } }, "states": { "title": "States (coarse alternative to Cities)", "type": "array", "description": "Limits the run by state and expands to every city served in that state. Use Cities when you want one jurisdiction. Leave both empty to query all 45.", "items": { "type": "string", "enum": [ "AZ", "CA", "CO", "CT", "FL", "ID", "IL", "KS", "KY", "LA", "MA", "MD", "MI", "NC", "NM", "NY", "OH", "OR", "PA", "TN", "TX", "WA" ], "enumTitles": [ "Arizona — Maricopa County, Tempe, Coconino County", "California — Anaheim, Los Angeles County, Sacramento County, Placentia, San Francisco", "Colorado — Douglas County, Boulder, Boulder County, Aspen", "Connecticut — Hartford", "Florida — Miami-Dade County, Miami, Alachua County, Fort Pierce", "Idaho — Boise", "Illinois — Naperville, Chicago", "Kansas — Overland Park", "Kentucky — Louisville Metro / Jefferson County", "Louisiana — New Orleans", "Massachusetts — Somerville", "Maryland — Baltimore City, Maryland Building Permit Data System", "Michigan — Detroit", "North Carolina — Raleigh", "New Mexico — Las Cruces", "New York — New York City", "Ohio — Columbus, Cleveland, Oxford, Cincinnati", "Oregon — Talent", "Pennsylvania — Allentown", "Tennessee — Nashville / Davidson County, Memphis / Shelby County", "Texas — San Antonio, San Marcos, Kerrville, Austin", "Washington — Bellevue, Tacoma, Seattle" ] } }, "lastNDays": { "title": "Last N days", "minimum": 1, "maximum": 3650, "type": "integer", "description": "Window size when issuedAfter/issuedBefore are empty. 7 is the default because that is how fresh a permit lead has to be to be worth calling. A missed scheduled run is covered by permits already returned earlier: they are filtered out and never charged twice.", "default": 7 }, "issuedAfter": { "title": "Issued on or after", "type": "string", "description": "Exact start of the window, YYYY-MM-DD. Overrides lastNDays when set. Use this and Issued before together to fetch one specific period." }, "issuedBefore": { "title": "Issued on or before", "type": "string", "description": "Exact end of the window, YYYY-MM-DD. Empty means today. Permits dated after today exist in some layers as data-entry typos, so the ceiling is applied even when you do not set one." }, "maxResultsPerCity": { "title": "Max results per city", "minimum": 1, "maximum": 5000, "type": "integer", "description": "How many permits one city may return. This is per city, not split between them, so adding cities never shrinks the others. A city that hits the limit is marked truncated in the run summary, so a cut-off is never mistaken for a quiet city.", "default": 1000 }, "permitIds": { "title": "Permit numbers", "type": "array", "description": "Search mode only. Permit numbers exactly as the issuing city writes them, e.g. PMLSM1602159 (Columbus) or BL320942 (Anaheim). Case is normalised automatically: the layers are case-sensitive and both forms are tried.", "items": { "type": "string" } }, "contractorNames": { "title": "Contractor names", "type": "array", "description": "Search mode only. Full or partial contractor name, e.g. WATER HEATERS PLUS. Partial names are matched with LIKE, so SCHUMACHER finds SCHUMACHER ROOFING LLC. Each contractor search also returns one free portfolio row: how many permits, in which cities, how many still active, and the value of the work.", "items": { "type": "string" } }, "addresses": { "title": "Street addresses", "type": "array", "description": "Search mode only. Street address of the work site. A city and ZIP may be included but are not required; the search falls back to the street line alone when the full address does not match the way the city stores it.", "items": { "type": "string" } }, "mode": { "title": "Mode", "enum": [ "new", "search" ], "type": "string", "description": "Leave empty and the mode is inferred: lists of permits, contractors or addresses mean search, an empty input means new. Set it explicitly if you want to be sure. new: every permit in the date window, ignoring the search lists. search: answer the search lists." }, "maxRecordsPerLookup": { "title": "Max records per search term", "minimum": 1, "maximum": 100, "type": "integer", "description": "Search mode only. How many permits one permit number, contractor or address may return. A contractor name can match hundreds of permits; raise this to see the history, lower it to keep the run small.", "default": 10 }, "contractorPortfolio": { "title": "Free contractor portfolio row", "type": "boolean", "description": "For each contractor search, add one summary row with permit count, cities, active and closed counts, total valuation of the work, trades and the first and last permit date. This row is never charged and does not count towards any limit.", "default": true }, "includeRaw": { "title": "Include raw source row", "type": "boolean", "description": "Keep the untouched attributes of the source layer on every record. Useful for debugging a jurisdiction; makes each record several times larger.", "default": false }, "maxConcurrency": { "title": "Concurrency", "minimum": 1, "maximum": 8, "type": "integer", "description": "Parallel requests within one city. Higher is faster and more likely to be rate limited by the city's server.", "default": 2 }, "requestTimeoutSecs": { "title": "Request timeout (seconds)", "minimum": 5, "maximum": 180, "type": "integer", "description": "Timeout for a single request. Deep pages on a large layer can be slow.", "default": 45 }, "chargePerRecord": { "title": "Pay per record", "type": "boolean", "description": "Charge one event per permit pushed to the dataset. A search that matched nothing is never charged, and the contractor portfolio row is free.", "default": true }, "runBudgetSecs": { "title": "Run budget (seconds)", "minimum": 30, "maximum": 3600, "type": "integer", "description": "How long this run may take before it stops and returns what it has. Leave it empty (recommended) and the run uses the whole timeout you set for it, so asking for every city and every state is not cut short. Set a number only to stop earlier. Stopping early is not a failure: the summary lists the cities it did not reach under `citiesSkippedForBudget`, and you can re-run for them." } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }