{ "openapi": "3.0.1", "info": { "title": "US Building Permits – 93 Cities, Contractor/Construction Leads", "description": "Building permit data from 93 US cities & counties in one clean table: new construction, roofing, solar, HVAC & remodel permits with contractor, valuation, ZIP & coordinates. Construction leads from official open data, no logins.", "version": "1.6", "x-build-id": "rJh2YptwwbsLEEhJS" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/exuberantly_inventiveness~us-building-permits/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-exuberantly_inventiveness-us-building-permits", "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/exuberantly_inventiveness~us-building-permits/runs": { "post": { "operationId": "runs-sync-exuberantly_inventiveness-us-building-permits", "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/exuberantly_inventiveness~us-building-permits/run-sync": { "post": { "operationId": "run-sync-exuberantly_inventiveness-us-building-permits", "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": { "mode": { "title": "Mode", "enum": [ "human", "agent" ], "type": "string", "description": "Human mode: pick a place, work type and dates. AI/Agent mode (\"mode\": \"agent\") accepts every field below and also writes a coverage record (jurisdictions queried, result count per jurisdiction, skipped ones and why, status completed / no_match / failed) to the key-value store as COVERAGE and as the last dataset item (not charged). All filters work in both modes; existing inputs without this field run unchanged.", "default": "human" }, "cities": { "title": "City / county", "type": "array", "description": "Which official permit feeds to query. Pick \"All supported cities\" together with a state to get every source in that state.", "items": { "type": "string", "enum": [ "all", "eloy", "maricopa_county", "mesa", "scottsdale", "tempe", "tucson", "atascadero", "campbell", "citrus_heights", "corona", "los_angeles", "los_angeles_county_rebuild", "marin_county", "placentia", "sacramento_county", "san_diego_county", "san_francisco", "san_jose", "boulder", "denver", "douglas_county_co", "washington_dc", "alachua_county", "broward_county", "miami", "miami_dade_county", "orlando", "port_st_lucie", "weston", "atlanta", "boise", "chicago", "cook_county_demolition", "rockford_il", "st_charles_il", "wheaton", "overland_park", "louisville", "baton_rouge", "new_orleans", "boston", "cambridge_ma", "somerville", "worcester", "baltimore", "baltimore_county_md", "montgomery_county_md", "detroit", "minneapolis", "kansas_city_mo", "raymore", "brunswick_county_nc", "cary", "charlotte", "greensboro", "raleigh", "wake_county", "new_jersey", "henderson", "new_york_city", "cincinnati", "cleveland", "columbus", "bend", "jackson_county_or", "portland_or", "salem", "philadelphia", "pittsburgh", "bluffton_sc", "charleston_sc", "memphis", "nashville", "austin", "college_station", "collin_county", "dallas", "fort_worth", "harris_county_tx", "san_antonio", "san_marcos", "tyler_tx", "arlington_county_va", "charlottesville", "norfolk", "virginia_beach", "bellevue", "edgewood_wa", "everett", "pierce_county", "puyallup", "seattle", "tacoma" ], "enumTitles": [ "All supported cities (93)", "AZ – Eloy", "AZ – Maricopa County (unincorporated)", "AZ – Mesa", "AZ – Scottsdale", "AZ – Tempe", "AZ – Tucson", "CA – Atascadero", "CA – Campbell", "CA – Citrus Heights", "CA – Corona", "CA – Los Angeles", "CA – Los Angeles County (fire rebuild)", "CA – Marin County", "CA – Placentia", "CA – Sacramento County (unincorporated)", "CA – San Diego County (unincorporated)", "CA – San Francisco", "CA – San Jose", "CO – Boulder", "CO – Denver", "CO – Douglas County", "DC – Washington", "FL – Alachua County (unincorporated)", "FL – Broward County (unincorporated)", "FL – Miami", "FL – Miami-Dade County", "FL – Orlando", "FL – Port St. Lucie", "FL – Weston", "GA – Atlanta", "ID – Boise (high-impact, new housing & demolition permits)", "IL – Chicago", "IL – Cook County (suburban asbestos & demolition permits)", "IL – Rockford", "IL – St. Charles", "IL – Wheaton", "KS – Overland Park", "KY – Louisville (Metro)", "LA – Baton Rouge (East Baton Rouge Parish)", "LA – New Orleans", "MA – Boston", "MA – Cambridge", "MA – Somerville", "MA – Worcester", "MD – Baltimore", "MD – Baltimore County", "MD – Montgomery County", "MI – Detroit", "MN – Minneapolis", "MO – Kansas City", "MO – Raymore", "NC – Brunswick County", "NC – Cary", "NC – Charlotte / Mecklenburg County", "NC – Greensboro", "NC – Raleigh", "NC – Wake County (unincorporated & contract towns)", "NJ – New Jersey (statewide, municipality level)", "NV – Henderson", "NY – New York City", "OH – Cincinnati", "OH – Cleveland", "OH – Columbus", "OR – Bend", "OR – Jackson County", "OR – Portland", "OR – Salem", "PA – Philadelphia", "PA – Pittsburgh", "SC – Bluffton", "SC – Charleston (new construction only)", "TN – Memphis / Shelby County", "TN – Nashville (Metro Davidson County)", "TX – Austin", "TX – College Station", "TX – Collin County (Collin CAD, all cities)", "TX – Dallas", "TX – Fort Worth", "TX – Harris County (unincorporated)", "TX – San Antonio", "TX – San Marcos", "TX – Tyler", "VA – Arlington County", "VA – Charlottesville", "VA – Norfolk", "VA – Virginia Beach", "WA – Bellevue", "WA – Edgewood", "WA – Everett", "WA – Pierce County (unincorporated)", "WA – Puyallup", "WA – Seattle", "WA – Tacoma" ] }, "default": [ "chicago" ] }, "states": { "title": "Or: state", "type": "array", "description": "Limit the run to sources in these states (combine with \"All supported cities\" to get every source in a state).", "items": { "type": "string", "enum": [ "AZ", "CA", "CO", "DC", "FL", "GA", "ID", "IL", "KS", "KY", "LA", "MA", "MD", "MI", "MN", "MO", "NC", "NJ", "NV", "NY", "OH", "OR", "PA", "SC", "TN", "TX", "VA", "WA" ] }, "default": [] }, "categories": { "title": "Permit type", "type": "array", "description": "Kind of work, e.g. new construction, roofing, solar. Empty = all types.", "items": { "type": "string", "enum": [ "new_construction", "addition", "alteration", "roofing", "windows_doors", "siding", "hvac", "electrical", "plumbing", "solar", "demolition", "pool", "fence", "sign", "other" ] }, "default": [] }, "trades": { "title": "Trade", "type": "array", "description": "Keep permits that involve any of these trades (a permit can have several). Empty = all.", "items": { "type": "string", "enum": [ "general", "roofing", "windows_doors", "siding", "hvac", "electrical", "plumbing", "solar", "demolition", "pool", "fence", "sign", "fire_protection", "concrete_masonry", "deck_patio", "mobile_home" ] }, "default": [] }, "lastNDays": { "title": "Or: last N days", "minimum": 0, "type": "integer", "description": "Last N days up to today (overrides the dates below). Leave at 0 and empty dates for the last 7 days.", "default": 0 }, "dateFrom": { "title": "Issued from (YYYY-MM-DD)", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "First permit issue date to include. Defaults to 7 days ago." }, "dateTo": { "title": "Issued to (YYYY-MM-DD)", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Last permit issue date to include (inclusive). Defaults to today." }, "maxItems": { "title": "Max results", "minimum": 0, "type": "integer", "description": "Stop after this many permits across all cities (you are charged per permit, so this also caps your cost). 0 = no limit. With several cities, results are taken round-robin so each city gets a share.", "default": 100 }, "permitTypeKeywords": { "title": "Keywords (permit type / work class / description)", "type": "array", "description": "Keep only permits whose type, work class or description contains any of these words (case-insensitive), e.g. roof, window, addition, solar, new construction. Leave empty for all.", "default": [], "items": { "type": "string" } }, "statusStd": { "title": "Status", "type": "array", "description": "Standardized status. Empty = all.", "items": { "type": "string", "enum": [ "applied", "in_review", "approved", "issued", "finaled", "expired", "cancelled", "on_hold", "other" ] }, "default": [] }, "propertyClass": { "title": "Property class", "enum": [ "any", "residential", "commercial" ], "type": "string", "description": "Residential / commercial (derived; permits whose class cannot be determined are dropped when set).", "default": "any" }, "newConstructionOnly": { "title": "New construction only", "type": "boolean", "description": "Shortcut for category = new_construction.", "default": false }, "onlyWithContractor": { "title": "Only permits with a contractor name", "type": "boolean", "description": "Drop permits that have no contractor/business name.", "default": false }, "minValuation": { "title": "Minimum declared valuation (USD)", "minimum": 0, "type": "integer", "description": "Skip permits below this job value. Permits with no valuation are dropped when this is > 0. Some sources (Philadelphia, Maricopa County, most new Dallas records) publish no valuation.", "default": 0 }, "maxValuation": { "title": "Maximum declared valuation (USD)", "minimum": 0, "type": "integer", "description": "Skip permits above this job value (0 = no maximum). Permits with no valuation are kept unless a minimum is set.", "default": 0 }, "zipCodes": { "title": "ZIP codes", "type": "array", "description": "Keep only these ZIPs. 3-digit prefixes work too (e.g. 531). ZIPs missing from the source are filled from the address, the coordinates (Census ZCTA) or the geocoder first.", "default": [], "items": { "type": "string" } }, "centerLat": { "title": "Radius search: center latitude", "type": "string", "description": "e.g. 42.5847. Use with longitude and radius." }, "centerLon": { "title": "Radius search: center longitude", "type": "string", "description": "e.g. -87.8212" }, "radiusMiles": { "title": "Radius (miles)", "minimum": 0, "type": "integer", "description": "Keep permits within this distance of the center. Permits without coordinates (after geocoding) are dropped. Sources far outside the circle are skipped entirely.", "default": 0 }, "geocodeMissing": { "title": "Geocode missing coordinates", "type": "boolean", "description": "Fill lat/lon for permits that have an address but no coordinates using the free US Census Bureau geocoder (exact matches only).", "default": true }, "maxGeocode": { "title": "Max addresses to geocode", "minimum": 0, "type": "integer", "description": "Upper bound on geocoder lookups per run.", "default": 10000 }, "maxItemsPerCity": { "title": "Max results per city", "minimum": 0, "type": "integer", "description": "Cap per city so one large city does not use up the whole run. 0 = no cap.", "default": 0 }, "flatOutput": { "title": "CSV-friendly flat output", "type": "boolean", "description": "Write \"trades\" as a semicolon-separated string (and raw as JSON text) so CSV/Excel exports have one column per field.", "default": false }, "pushSummaryRecords": { "title": "Add per-city summary rows to the dataset", "type": "boolean", "description": "Append one record_type=\"summary\" row per city (counts by category/status, total valuation, top contractors). Summary rows are not charged. A summary is always saved as SUMMARY / SUMMARY.csv in the key-value store.", "default": false }, "includeRaw": { "title": "Include raw source record", "type": "boolean", "description": "Add the original source row under \"raw\". Owner/applicant names, phones and emails are always removed.", "default": false }, "incremental": { "title": "Only new permits (incremental mode)", "type": "boolean", "description": "Remember permits already returned (in the named key-value store \"us-building-permits-state\") and output only new ones on later runs. Ideal for a daily/weekly schedule with \"last N days\". Turned on automatically when \"Incremental output\" is a changes mode.", "default": false }, "incrementalMode": { "title": "Incremental output", "enum": [ "new", "changes", "new_and_changes" ], "type": "string", "description": "What a monitoring run outputs. The Actor stores each permit's last status; a later run outputs permits whose status changed with `change_type: \"status_changed\"`, `previous_status` and `changed_at`. New permits get `change_type: \"new\"`. The first run of a state only records (outputs and charges nothing). Changes modes default to a 60-day look-back so older permits can be re-checked. \"Only new permits\" takes effect only when the switch above is on; the two changes modes turn monitoring on by themselves.", "default": "new" }, "incrementalFirstRun": { "title": "First incremental run", "enum": [ "seed", "push" ], "type": "string", "description": "What the very first incremental run per source does. \"seed\" records the current permits without outputting (or charging) them, so the next run returns only new ones.", "default": "seed" }, "incrementalStateKey": { "title": "State name", "type": "string", "description": "Use different names to keep separate \"already seen\" lists for different schedules/filters.", "default": "default" }, "sourceTimeoutSecs": { "title": "Per-source timeout (seconds)", "minimum": 10, "type": "integer", "description": "Skip a source that returns no data for this long, so one slow portal cannot stall the run.", "default": 120 }, "socrataAppToken": { "title": "Socrata app token (optional)", "type": "string", "description": "Free token from any Socrata portal; raises rate limits for large runs." } } }, "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 } } } } } } } } } }