{ "openapi": "3.0.1", "info": { "title": "Building Permit API - Permits, Contractors, Property Data", "description": "US building permit data by address, city, county, ZIP or jurisdiction: permit type, status, job value, fees, approval and construction duration, inspection pass rate and work tags, the licensed contractors behind them, properties with permit history, zoning decisions and monthly market metrics.", "version": "0.1", "x-build-id": "25dJ0SoUZoRPtlfpR" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nabeelbaghoor~building-permits-contractors-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nabeelbaghoor-building-permits-contractors-api", "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/nabeelbaghoor~building-permits-contractors-api/runs": { "post": { "operationId": "runs-sync-nabeelbaghoor-building-permits-contractors-api", "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/nabeelbaghoor~building-permits-contractors-api/run-sync": { "post": { "operationId": "run-sync-nabeelbaghoor-building-permits-contractors-api", "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": { "service": { "title": "What to read", "enum": [ "permitSearch", "permitsById", "contractorSearch", "contractorsById", "contractorPermits", "contractorMetrics", "propertySearch", "propertiesById", "decisionSearch", "decisionsById", "geoSearch", "geoDetails", "geoMetricsCurrent", "geoMetricsMonthly", "coverage", "tagList", "zipList", "release", "usage" ], "type": "string", "description": "Permit search returns individual permits. Contractor search returns the firms pulling them in an area. Property search returns properties with their permit history summarised on one record, including properties with no permit of a given type. Decisions returns zoning and land use rulings. The metrics services return permit counts, job values and durations by month. Geography lookup turns a place name into the geo_id every other search needs.", "default": "permitSearch" }, "geoId": { "title": "Geography id", "type": "string", "description": "This API identifies a place by its own geo_id, not by name, and almost every search requires one. Run the Geography lookup service with a city, county, ZIP or address first and copy the geo_id it returns." }, "geoType": { "title": "Geography type", "enum": [ "address", "city", "county", "jurisdiction", "zipcode", "state" ], "type": "string", "description": "Which level of geography the lookup, details and metrics services work at. Details exist for cities, counties and jurisdictions only. Metrics exist for addresses, cities, counties and jurisdictions.", "default": "city" }, "searchTerms": { "title": "Place names to look up", "type": "array", "description": "One place name per line for the Geography lookup service, such as a city, county, jurisdiction, ZIP code or street address. Each becomes its own search.", "items": { "type": "string" } }, "permitFrom": { "title": "Permit date from", "type": "string", "description": "Start of the permit date range, as YYYY-MM-DD. Required by permit search, contractor search and the coverage service, because the provider scopes those by date rather than returning everything." }, "permitTo": { "title": "Permit date to", "type": "string", "description": "End of the permit date range, as YYYY-MM-DD." }, "permitTags": { "title": "Permit tags", "type": "array", "description": "Filter by work type, such as solar, roofing or hvac. Prefix a tag with a minus to exclude it, so solar and -roofing means has solar but not roofing. Run the Permit tag list service to see every tag this API publishes.", "items": { "type": "string" } }, "permitStatus": { "title": "Permit status", "type": "array", "description": "Filter by permit status. Leave empty for all statuses.", "items": { "type": "string", "enum": [ "final", "in_review", "inactive", "active" ], "enumTitles": [ "Final - work finished and signed off", "In review - filed, not yet approved", "Inactive", "Active - approved, work under way" ] } }, "permitQuery": { "title": "Permit text search", "type": "string", "description": "Free text matched against the permit description, for work the tags do not capture." }, "permitHasContractor": { "title": "Only permits with a named contractor", "type": "boolean", "description": "Restrict to permits that name a contractor. Useful when the point of the run is the firm rather than the job.", "default": false }, "permitMinJobValue": { "title": "Minimum job value (USD)", "minimum": 0, "type": "integer", "description": "Only permits whose declared job value is at least this, in whole US dollars as the provider publishes it." }, "permitMinFees": { "title": "Minimum permit fees (USD)", "minimum": 0, "type": "integer", "description": "Only permits whose fees are at least this, in whole US dollars." }, "permitMinApprovalDuration": { "title": "Minimum approval duration (days)", "minimum": 0, "type": "integer", "description": "Only permits that took at least this many days from filing to approval." }, "permitMinConstructionDuration": { "title": "Minimum construction duration (days)", "minimum": 0, "type": "integer", "description": "Only permits whose construction ran at least this many days." }, "permitMinInspectionPassRate": { "title": "Minimum permit inspection pass rate", "minimum": 0, "maximum": 100, "type": "integer", "description": "Only permits whose inspections passed at least this percentage of the time." }, "propertyType": { "title": "Property type", "type": "array", "description": "Filter by the type of property the work was done on. Choose several to match any of them.", "items": { "type": "string", "enum": [ "residential", "commercial", "industrial", "agricultural", "vacant land", "exempt", "miscellaneous", "office", "recreational" ], "enumTitles": [ "Residential", "Commercial", "Industrial", "Agricultural", "Vacant land", "Exempt", "Miscellaneous", "Office", "Recreational" ] } }, "propertyMinMarketValue": { "title": "Minimum assessed market value (USD)", "minimum": 0, "type": "integer", "description": "Only properties assessed at or above this value." }, "propertyMaxMarketValue": { "title": "Maximum assessed market value (USD)", "minimum": 0, "type": "integer", "description": "Only properties assessed at or below this value. Accepted by property search." }, "propertyMinBuildingArea": { "title": "Minimum building area", "minimum": 0, "type": "integer", "description": "Only properties whose building area is at least this, in the unit the provider publishes." }, "propertyMaxBuildingArea": { "title": "Maximum building area", "minimum": 0, "type": "integer", "description": "Only properties whose building area is at most this. Accepted by property search." }, "propertyMinLotSize": { "title": "Minimum lot size", "minimum": 0, "type": "integer", "description": "Only properties whose lot is at least this size." }, "propertyMaxLotSize": { "title": "Maximum lot size", "minimum": 0, "type": "integer", "description": "Only properties whose lot is at most this size. Accepted by property search." }, "propertyMinStoryCount": { "title": "Minimum storeys", "minimum": 0, "type": "integer", "description": "Only properties with at least this many storeys." }, "propertyMinUnitCount": { "title": "Minimum units", "minimum": 0, "type": "integer", "description": "Only properties with at least this many units, for finding multifamily stock." }, "propertyMaxUnitCount": { "title": "Maximum units", "minimum": 0, "type": "integer", "description": "Only properties with at most this many units. Accepted by property search." }, "propertyMinYearBuilt": { "title": "Built no earlier than", "minimum": 1600, "type": "integer", "description": "Only properties built in or after this year. Accepted by property search." }, "propertyMaxYearBuilt": { "title": "Built no later than", "minimum": 1600, "type": "integer", "description": "Only properties built in or before this year, for finding ageing stock. Accepted by property search." }, "legalOwner": { "title": "Legal owner names", "type": "array", "description": "One owner name per line, for property search. Matches properties held by those named owners.", "items": { "type": "string" } }, "permitTagsUnfinaled": { "title": "Unfinaled permit tags", "type": "array", "description": "On property search, restrict to properties with an open, not-yet-final permit carrying these tags.", "items": { "type": "string" } }, "contractorClassification": { "title": "Contractor trade", "type": "array", "description": "Filter by the trade classification this API derives from a firm's work. Several values mean a firm must have all of them. Prefix with a minus to exclude.", "items": { "type": "string", "enum": [ "electrical", "plumbing", "hvac", "roofing", "framing_and_carpentry", "concrete_and_paving", "demolition_and_excavation", "fencing_and_glazing", "landscaping_and_outdoor_work", "general_building_contractor", "general_engineering_contractor", "specialty_trades", "other" ], "enumTitles": [ "Electrical", "Plumbing", "HVAC", "Roofing", "Framing and carpentry", "Concrete and paving", "Demolition and excavation", "Fencing and glazing", "Landscaping and outdoor work", "General building contractor", "General engineering contractor", "Specialty trades", "Other" ] } }, "contractorName": { "title": "Contractor name", "type": "string", "description": "Match contractors by name." }, "contractorWebsite": { "title": "Contractor website", "type": "string", "description": "Match contractors by website domain." }, "contractorLicense": { "title": "Contractor licence number", "type": "string", "description": "Match a contractor by its licence number." }, "contractorMinTotalJobValue": { "title": "Minimum contractor total job value (USD)", "minimum": 0, "type": "integer", "description": "Only contractors whose permits total at least this much work, for separating real operators from one-permit firms." }, "contractorMinPermitCount": { "title": "Minimum contractor permit count", "minimum": 0, "type": "integer", "description": "Only contractors who have pulled at least this many permits." }, "contractorMinInspectionPassRate": { "title": "Minimum contractor inspection pass rate", "minimum": 0, "maximum": 100, "type": "integer", "description": "Only contractors whose inspections pass at least this percentage of the time." }, "includeTallies": { "title": "Include contractor tallies", "type": "boolean", "description": "Ask contractor search for the per-status and per-tag counts behind each firm's totals.", "default": false }, "contractorIds": { "title": "Contractor ids", "type": "array", "description": "One contractor id per line, for the contractor lookup, permits-by-contractor and contractor metrics services.", "items": { "type": "string" } }, "permitIds": { "title": "Permit ids", "type": "array", "description": "One permit id per line, for the permit lookup service.", "items": { "type": "string" } }, "addressIds": { "title": "Address ids", "type": "array", "description": "One address geo_id per line, for the property lookup service.", "items": { "type": "string" } }, "decisionIds": { "title": "Decision ids", "type": "array", "description": "One decision id per line, for the decision lookup service.", "items": { "type": "string" } }, "decisionFrom": { "title": "Decision date from", "type": "string", "description": "Start of the decision date range, as YYYY-MM-DD. Required by decision search." }, "decisionTo": { "title": "Decision date to", "type": "string", "description": "End of the decision date range, as YYYY-MM-DD." }, "decisionQuery": { "title": "Decision text search", "type": "string", "description": "Free text matched against the decision title and description." }, "assetClass": { "title": "Decision asset class", "type": "array", "description": "Filter zoning and land use decisions by asset class, as the provider labels them.", "items": { "type": "string" } }, "decisionCategory": { "title": "Decision category", "type": "array", "description": "Filter decisions by category, as the provider labels them.", "items": { "type": "string" } }, "decisionSubcategory": { "title": "Decision subcategory", "type": "array", "description": "Filter decisions by subcategory, as the provider labels them.", "items": { "type": "string" } }, "decisionMinProjectValue": { "title": "Minimum decision project value (USD)", "minimum": 0, "type": "integer", "description": "Only decisions on projects worth at least this much." }, "decisionMaxProjectValue": { "title": "Maximum decision project value (USD)", "minimum": 0, "type": "integer", "description": "Only decisions on projects worth at most this much." }, "metricFrom": { "title": "Metric date from", "type": "string", "description": "Start of the metric date range, as YYYY-MM-DD. Required by the monthly metrics services." }, "metricTo": { "title": "Metric date to", "type": "string", "description": "End of the metric date range, as YYYY-MM-DD." }, "metricTag": { "title": "Metric tag", "type": "string", "description": "Which work type the metrics are reported for. The metrics services report per tag rather than in aggregate, so the provider requires one." }, "metricPropertyType": { "title": "Metric property type", "enum": [ "residential", "commercial", "industrial", "agricultural", "vacant land", "exempt", "miscellaneous", "office", "recreational" ], "type": "string", "description": "Which property type the metrics are reported for. Required by the city, county, jurisdiction and contractor metrics services." }, "maxResults": { "title": "Maximum results", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Stop after this many rows. Billing here is per record on the provider's side as well as this actor's, so this cap is what keeps a wide search from spending more than you meant.", "default": 1000 }, "pageSize": { "title": "Results per request", "minimum": 1, "maximum": 100, "type": "integer", "description": "How many records to ask for per call. The provider allows up to 100 and defaults to 10.", "default": 100 }, "requestsPerMinute": { "title": "Requests per minute", "minimum": 1, "maximum": 600, "type": "integer", "description": "Pacing ceiling. The provider rate limits individually rather than by a published number, so lower this if a run starts being throttled.", "default": 60 }, "apiKey": { "title": "API key", "type": "string", "description": "Your own API key for the building permit data provider, from your account's API key page. This actor is bring-your-own-key and never ships a key of its own. Leave blank to use the DATA_API_KEY environment secret instead." }, "baseUrl": { "title": "API base URL", "type": "string", "description": "Override the API host. Only needed if your account is served from somewhere other than the public endpoint." } } }, "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 } } } } } } } } } }