{ "openapi": "3.0.1", "info": { "title": "Building Permits Scraper - Permit Data API & Contractor Leads", "description": "Building permit data from 31 US & Canada cities in one run: new construction leads with contractor name, phone and license, project value, trade and lead score. Only-new mode for daily schedules.", "version": "0.1", "x-build-id": "fVGXB3TYu4RLqctVd" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/highfiddle~building-permit-leads/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-highfiddle-building-permit-leads", "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/highfiddle~building-permit-leads/runs": { "post": { "operationId": "runs-sync-highfiddle-building-permit-leads", "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/highfiddle~building-permit-leads/run-sync": { "post": { "operationId": "run-sync-highfiddle-building-permit-leads", "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": "Pick one or more jurisdictions. Leave empty (and leave States empty) to search all of them.", "items": { "type": "string", "enum": [ "chicago", "nyc", "los-angeles", "seattle", "austin", "dallas", "san-francisco", "baton-rouge", "cincinnati", "new-orleans", "montgomery-county-md", "cambridge-ma", "mesa", "marin-county", "norfolk", "collin-county-tx", "calgary", "edmonton", "nashville", "raleigh", "columbus", "miami-dade-county", "miami", "cleveland", "detroit", "washington-dc", "baltimore", "anaheim", "boston", "san-antonio", "philadelphia" ], "enumTitles": [ "Chicago, IL", "New York City, NY", "Los Angeles, CA", "Seattle, WA", "Austin, TX", "Dallas, TX", "San Francisco, CA", "Baton Rouge (East Baton Rouge Parish), LA", "Cincinnati, OH", "New Orleans, LA", "Montgomery County, MD", "Cambridge, MA", "Mesa, AZ", "Marin County, CA", "Norfolk, VA", "Collin County (Plano, Frisco, McKinney, Allen...), TX", "Calgary, AB", "Edmonton, AB", "Nashville (Metro Davidson County), TN", "Raleigh, NC", "Columbus, OH", "Miami-Dade County (unincorporated), FL", "Miami (city), FL", "Cleveland, OH", "Detroit, MI", "Washington, DC", "Baltimore, MD", "Anaheim, CA", "Boston, MA", "San Antonio, TX", "Philadelphia, PA" ] } }, "states": { "title": "States / provinces", "type": "array", "description": "Adds every supported jurisdiction in these states, e.g. TX adds Austin, Dallas, San Antonio and Collin County.", "items": { "type": "string", "enum": [ "AB", "AZ", "CA", "DC", "FL", "IL", "LA", "MA", "MD", "MI", "NC", "NY", "OH", "PA", "TN", "TX", "VA", "WA" ] } }, "lastNDays": { "title": "Issued in the last N days", "minimum": 1, "maximum": 3650, "type": "integer", "description": "Ignored when 'Issued from' is set. Cities publish with a 1-7 day lag, so 7+ days is safest for daily schedules.", "default": 30 }, "dateFrom": { "title": "Issued from", "type": "string", "description": "First issue date to include (YYYY-MM-DD). Overrides 'last N days'." }, "dateTo": { "title": "Issued until", "type": "string", "description": "Last issue date to include (YYYY-MM-DD). Defaults to today." }, "trades": { "title": "Trades", "type": "array", "description": "Keep permits whose work matches any of these trades. Leave empty for all permits.", "items": { "type": "string", "enum": [ "solar", "roofing", "pool", "adu", "new_construction", "addition", "demolition", "hvac", "electrical", "plumbing", "fire_protection", "windows_doors", "siding", "fence_deck", "foundation", "elevator", "sign", "remodel" ], "enumTitles": [ "Solar / PV / battery", "Roofing", "Pool & spa", "ADU / accessory dwelling", "New construction", "Addition", "Demolition", "HVAC / mechanical", "Electrical", "Plumbing & gas", "Fire alarm & sprinkler", "Windows & doors", "Siding / stucco / facade", "Fence, deck, patio, porch", "Foundation & structural", "Elevator", "Signs & awnings", "Remodel / alteration / repair" ] } }, "keywords": { "title": "Keywords", "type": "array", "description": "Keep permits whose type, description or contractor contains any of these words (case-insensitive).", "items": { "type": "string" } }, "zipCodes": { "title": "ZIP / postal codes", "type": "array", "description": "Keep permits in these ZIP codes. A prefix works too: '787' matches all of 787xx.", "items": { "type": "string" } }, "minProjectValue": { "title": "Minimum project value ($)", "minimum": 0, "type": "integer", "description": "Drops permits below this value, and permits from cities that do not publish a value." }, "propertyType": { "title": "Property type", "enum": [ "any", "residential", "commercial" ], "type": "string", "description": "Keep only residential or only commercial permits. Permits whose city does not say are dropped by these two options.", "default": "any" }, "requireContact": { "title": "Require contact details", "enum": [ "none", "contractor", "phone", "phoneOrEmail" ], "type": "string", "description": "Only keep permits that name a contractor, or that have a phone number.", "default": "none" }, "excludeOwnerBuilder": { "title": "Exclude owner-builder permits", "type": "boolean", "description": "Skip permits where the owner is doing the work themselves.", "default": false }, "excludeClosed": { "title": "Exclude finaled / closed / expired permits", "type": "boolean", "description": "Skip permits whose status says the work is already finished, closed, expired or cancelled.", "default": false }, "minLeadGrade": { "title": "Minimum lead grade", "enum": [ "COLD", "WARM", "HOT" ], "type": "string", "description": "HOT = score 60+, WARM = 35+. The score weighs freshness, project value, contractor phone/email and permit status.", "default": "COLD" }, "outputMode": { "title": "Output", "enum": [ "permits", "contractors", "both" ], "type": "string", "description": "Permits: one row per permit. Contractors: one row per contractor with permit count, value and trades. Both: permits plus contractor rows.", "default": "permits" }, "onlyNew": { "title": "Only permits not delivered before", "type": "boolean", "description": "Remembers delivered permits between runs, so scheduled runs only return (and charge for) new ones.", "default": false }, "stateKey": { "title": "Memory name for 'only new'", "type": "string", "description": "Use a different name per schedule, so each schedule remembers its own permits.", "default": "default" }, "maxResultsPerCity": { "title": "Max permits per city", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Newest permits first. Also caps the permits used for the contractor summary.", "default": 500 }, "maxResults": { "title": "Max permits in total", "minimum": 0, "type": "integer", "description": "0 = no overall limit (the per-city limit still applies).", "default": 0 }, "includeRaw": { "title": "Include raw source record", "type": "boolean", "description": "Adds the original row from the city's portal under 'raw'.", "default": false }, "socrataAppToken": { "title": "Socrata app token (optional)", "type": "string", "description": "Your own free Socrata app token for higher rate limits. Not needed for normal use." }, "healthCheck": { "title": "Health check only", "type": "boolean", "description": "Checks that each selected source answers and how recent its newest permit is. Writes the HEALTH record; returns no permits.", "default": false } } }, "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 } } } } } } } } } }