Construction Permit Intelligence

Turn official US permit feeds into ranked construction signals your team can actually use.

This actor pulls live permit records from official US open-data sources, normalizes them, and scores each construction signal for outreach or market monitoring. Instead of dumping raw rows, it prioritizes the records most likely to matter based on recency, estimated project value, trade relevance, property type, available contact data, and optional built-in AI review.

Why this actor

Permit data is valuable, but raw permit feeds are noisy:

• Contractors need to know which jobs look worth calling on.
• Suppliers need to spot active markets and higher-value work fast.
• Investors and service businesses need a leading indicator for neighborhood-level construction activity.
• Existing permit tools often stop at retrieval, with little ranking or qualification.

This actor is built around that gap: official permit data + practical prioritization + AI-assisted lead review.

Coverage

This is a US-only actor and it does not claim nationwide coverage yet. Coverage is explicit and metro-based.

Source	Jurisdiction	Coverage type	Key strengths
los_angeles	Los Angeles, CA	Building permits	Good descriptions, valuation, permit metadata
chicago	Chicago, IL	Building permits	Strong contact fields, reported cost, rich work descriptions
new_york_city	New York City, NY	DOB NOW approved permits	Issued dates, applicant/owner info, estimated job costs
san_francisco	San Francisco, CA	Building permits	Clean issued-date stream, estimated cost, use and reroof signals
austin	Austin, TX	Permit applications issued	Trade-specific contractor fields, permit class, active issued permits
miami	Miami, FL	Building permits	Official issued-date feed, total cost, scope-of-work, contractor company
seattle	Seattle, WA	Issued building permits	Clean issued stream, estimated cost, strong new-build and residential signals

The source architecture is modular, so more US cities can be added without changing the output contract.

What it returns

Each run produces:

• A summary record with high-priority counts, average signal score, dominant trade, top ZIP codes, and total estimated value
• An AI market insight summary when OPENAI_API_KEY is available
• A ranked permit dataset with normalized addresses, permit type, trade tags, valuation, score, reason, and optional AI lead notes
• OUTPUT JSON in the key-value store
• permits.csv for spreadsheet workflows
• REPORT.md for quick review or sharing

Inputs

Core filters

• sources: ["los_angeles", "chicago", "new_york_city", "san_francisco", "austin", "miami", "seattle"]
• tradeFocus: optional list of trade priorities like solar, roofing, electrical, fire_suppression, renovation
• buyerPersona: general, contractor, supplier, or investor
• searchQuery: free-text query across descriptions, permit types, addresses, and available party names
• focusKeywords: extra include keywords to strengthen relevance
• excludeKeywords: keywords to drop
• zipCodes: optional 5-digit ZIP filter
• propertyTypes: residential, commercial, mixed_or_other
• issuedFrom / issuedTo: date range in YYYY-MM-DD (defaults to last 30 days through today)
• minReportedCost / maxReportedCost: valuation filter where available
• minSignalScore: drop weak matches
• aiMode: auto or off. auto uses built-in OpenAI review if OPENAI_API_KEY is present in the runtime
• aiMaxItems: maximum number of top permits to review with AI
• aiMinRuleScore: minimum rule-based score before AI review is attempted

Output controls

• maxItemsPerSource: raw permits fetched before ranking
• maxItems: final permits returned
• sortBy: signal_desc, issue_date_desc, valuation_desc
• outputFormat: full, summary_only, permits_only

AI intelligence

The actor now has a built-in AI layer:

• It reads OPENAI_API_KEY from the environment, not from actor input.
• In auto mode, it sends only the strongest rule-ranked permits to OpenAI for structured review.
• AI can refine trade classification, adjust score modestly, add outreach guidance, and generate a short market insight.
• If no OPENAI_API_KEY is available, the actor still works in rule-based mode.

The default built-in model is gpt-5-mini, chosen as a balance of cost and structured-inference quality for short JSON permit reviews.

Buyer personas change the ranking logic:

• contractor: favors fresh, contactable work with clear execution scope
• supplier: leans harder on valuation, commercial property, and likely materials demand
• investor: favors larger commercial / mixed permits and lower-noise market signals

Example inputs

Roofing and renovation leads in Los Angeles

{
  "sources": ["los_angeles"],
  "tradeFocus": ["roofing", "renovation"],
  "zipCodes": ["90011", "90012", "90015"],
  "issuedFrom": "2026-02-01",
  "minReportedCost": 25000,
  "minSignalScore": 45,
  "maxItems": 100
}

Chicago electrical and signage permits

{
  "sources": ["chicago"],
  "tradeFocus": ["electrical", "signage"],
  "searchQuery": "panel upgrade",
  "issuedFrom": "2026-01-15",
  "focusKeywords": ["generator", "service upgrade"],
  "maxItemsPerSource": 200,
  "maxItems": 75
}

NYC fire suppression and tenant-space work

{
  "sources": ["new_york_city"],
  "tradeFocus": ["fire_suppression", "renovation"],
  "searchQuery": "tenant space",
  "propertyTypes": ["commercial"],
  "issuedFrom": "2026-02-06",
  "maxItems": 50
}

Multi-city commercial renovation watchlist

{
  "sources": ["los_angeles", "chicago", "miami"],
  "buyerPersona": "supplier",
  "tradeFocus": ["renovation", "general_construction"],
  "searchQuery": "tenant improvement",
  "propertyTypes": ["commercial"],
  "minReportedCost": 100000,
  "aiMode": "auto",
  "sortBy": "valuation_desc",
  "maxItems": 150
}

Austin residential mechanical and plumbing work

{
  "sources": ["austin"],
  "tradeFocus": ["hvac", "plumbing"],
  "searchQuery": "replacement",
  "issuedFrom": "2026-03-01",
  "zipCodes": ["78759", "78757"],
  "maxItems": 50
}

San Francisco roofing watchlist

{
  "sources": ["san_francisco"],
  "tradeFocus": ["roofing", "solar"],
  "issuedFrom": "2026-03-01",
  "minReportedCost": 5000,
  "maxItems": 50
}

Seattle and Miami new-construction watchlist

{
  "sources": ["seattle", "miami"],
  "tradeFocus": ["new_construction", "electrical", "plumbing"],
  "issuedFrom": "2026-03-01",
  "minReportedCost": 10000,
  "sortBy": "issue_date_desc",
  "maxItems": 100
}

Output shape

Summary record

{
  "type": "summary",
  "summary": {
    "quickTake": "12 high-priority permits surfaced across 2 source(s), led by renovation activity.",
    "aiMarketInsight": "Fresh higher-value renovation permits are clustering around commercial interiors, which is useful for specialty subs and supplier outreach.",
    "averageOpportunityScore": 68.4,
    "highPriorityPermits": 12,
    "dominantTrade": "renovation",
    "totalEstimatedValue": {
      "amount": 4825000,
      "currency": "USD",
      "display": "$4,825,000"
    },
    "topSignals": [
      { "label": "renovation", "count": 34 }
    ],
    "topZipCodes": [
      { "zipCode": "90012", "count": 11 }
    ]
  },
  "meta": {
    "sourcesAttempted": 2,
    "sourcesWithResults": 2,
    "permitsAnalyzed": 287,
    "permitsReturned": 150,
    "issuedFrom": "2026-02-06",
    "issuedTo": "2026-03-07",
    "processingMs": 1823,
    "buyerPersona": "supplier",
    "aiMode": "auto",
    "aiModelUsed": "gpt-5-mini",
    "aiEnhancedPermits": 15
  }
}

Permit record

{
  "type": "permit",
  "source": "chicago",
  "permitId": "101072844",
  "issueDate": "2025-10-14",
  "status": "ACTIVE",
  "address": {
    "full": "2219 S OAKLEY AVE Chicago, IL",
    "city": "Chicago",
    "state": "IL",
    "zipCode": "60608"
  },
  "valuation": {
    "amount": 20000,
    "currency": "USD",
    "display": "$20,000"
  },
  "permitType": "PERMIT - RENOVATION/ALTERATION",
  "permitSubType": "SELF CERT",
  "propertyType": "residential",
  "primaryTrade": "renovation",
  "tradeTags": ["renovation", "general_construction"],
  "description": "BUILD A DORMER ON THE SOUTH SIDE OF THE EXISTING 8-UNIT RESIDENTIAL BUILDING ROOF...",
  "contacts": [
    {
      "type": "CONTRACTOR-GENERAL CONTRACTOR",
      "name": "ALL TECH BUILDERS & RESTORATION INC",
      "city": "WHEELING",
      "state": "IL",
      "zipCode": "60090"
    }
  ],
  "opportunityScore": 71,
  "priority": "medium",
  "recommendedAction": "qualify",
  "reason": "renovation match, $20,000 valuation, contactable parties available",
  "aiIntelligence": {
    "model": "gpt-5-mini",
    "reviewedAt": "2026-03-07T14:22:01.000Z",
    "scoreDelta": 4,
    "confidence": "high",
    "commercialIntent": "medium",
    "refinedTrade": "renovation",
    "refinedPropertyType": "residential",
    "summary": "Fresh interior alteration with a named contractor and a clear renovation scope.",
    "outreachAngle": "Lead with renovation support and close-in execution capacity.",
    "buyerSignals": ["named contractor", "clear scope", "recent issue date"],
    "risks": ["mid-sized valuation"]
  },
  "sourceUrl": "https://data.cityofchicago.org/resource/ydr8-5enu.json?$where=permit_='101072844'"
}

How scoring works

Each permit gets a 0-100 opportunity score based on:

• Recency: newer permits rank higher
• Value: higher reported cost / valuation increases priority
• Trade fit: matches against requested tradeFocus, searchQuery, and focusKeywords
• Property fit: rewards the requested property type
• Contactability: Chicago records with contractor / owner details score higher

When AI is enabled, the actor keeps the rule-based score as the baseline and applies a bounded AI review only to top permits. That review can:

• refine trade and property classification
• adjust the score modestly
• add permit-level commercial notes and outreach guidance
• generate a short market insight for the report summary

Each permit also gets a deterministic recommendedAction:

• call_now
• qualify
• monitor
• skip

Development

npm install
npm run build
npm start

Local runs can use a .env file or shell environment variable. Apify runs should set OPENAI_API_KEY in Actor Settings > Environment Variables.

Notes

• This actor uses official public datasets, not scraped private systems.
• Coverage is major US markets first, not “all states”.
• Valuation and descriptive richness vary by source, so score composition is normalized but not identical across cities.
• Miami does not publish a site ZIP in the official open dataset, so ZIP filtering is strongest on the other supported metros.
• AI review is built in and uses the actor runtime environment, so users do not pass API keys in actor input.