{ "openapi": "3.0.1", "info": { "title": "PermitIQ — Building Permit API", "description": "ZIP-level market trends + urgency-scored contractor leads from Chicago, Austin, NYC, LA & SF. The only permit actor with hotspot scoring and month-over-month analysis. Official Socrata APIs — no scraping. MCP-ready for AI agents.", "version": "1.0", "x-build-id": "AvxRRwENJAsBBHMPR" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/midwest_united~permitiq/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-midwest_united-permitiq", "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/midwest_united~permitiq/runs": { "post": { "operationId": "runs-sync-midwest_united-permitiq", "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/midwest_united~permitiq/run-sync": { "post": { "operationId": "run-sync-midwest_united-permitiq", "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": { "cities": { "title": "Cities", "type": "array", "description": "One or more cities to query building permits for. Supported values: 'chicago', 'austin', 'nyc', 'los_angeles', 'san_francisco'. Example: [\"chicago\"] or [\"los_angeles\", \"san_francisco\"]", "items": { "type": "string" } }, "outputMode": { "title": "Output Mode", "enum": [ "leads", "trends", "raw" ], "type": "string", "description": "How to format results. Use 'leads' to get urgency-scored contractor leads sorted by opportunity value — best for sales outreach. Use 'trends' to get ZIP-code-level market analysis with hotspot scores and month-over-month permit volume deltas — best for market research. Use 'raw' for normalized permit records with explicit nulls — best for data pipelines and AI agent consumption.", "default": "leads" }, "permitType": { "title": "Permit Type Filter", "enum": [ "all", "roofing", "hvac", "plumbing", "electrical", "new_construction", "remodel", "solar", "adu" ], "type": "string", "description": "Filter to a specific permit category. Use 'all' to return all types. Other values: 'roofing', 'hvac', 'plumbing', 'electrical', 'new_construction', 'remodel', 'solar', 'adu' (accessory dwelling unit). Defaults to 'all'.", "default": "all" }, "daysBack": { "title": "Days Back", "minimum": 1, "maximum": 365, "type": "integer", "description": "How many calendar days of permit history to retrieve, counting back from today. Use 7 for last week's permits (highest urgency leads), 30 for a monthly window, 90 for quarterly trend analysis. Min: 1, Max: 365. Default: 30.", "default": 30 }, "maxResults": { "title": "Max Results", "minimum": 1, "type": "integer", "description": "Maximum number of records to return. For 'leads' mode this is the number of scored lead records. For 'trends' mode this is the number of ZIP codes in the output. For 'raw' mode this is the raw permit count. Default: 100. Set to 0 for no limit (use with caution on large cities).", "default": 100 }, "minEstimatedCost": { "title": "Minimum Estimated Project Cost (USD)", "minimum": 0, "type": "integer", "description": "Only return permits where the estimated project value meets or exceeds this dollar amount. Useful for filtering out small repairs and focusing on high-value jobs. Example: 10000 returns only permits worth $10,000 or more. Default: 0 (no minimum).", "default": 0 }, "zipCode": { "title": "ZIP Code Filter", "type": "string", "description": "Optional. Filter results to a single ZIP code. Leave blank to return permits from all ZIP codes in the city. Example: '60614' for Lincoln Park, Chicago." }, "budgetUsd": { "title": "Budget Cap (USD)", "minimum": 0, "type": "number", "description": "Optional. Maximum spend in USD for this actor run based on pay-per-result pricing ($0.01 per record). If estimated cost would exceed this value the actor exits cleanly with the records retrieved so far. Leave blank for no cap." } } }, "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 } } } } } } } } } }