Permit Lead Finder: Turning Public Permit Data Into Ranked Sales Leads

Every building permit issued by a county is a public record and provides valuable insights into a property. For home-service businesses, these signals can be potential leads, but they typically arrive in a flat CSV export with no ranking. Permit Lead Finder is a tool that transforms this export into a ranked list of properties, each scored based on specific criteria.

Developed using Claude as a pair programmer, the program works entirely with public permit data, without scraping any private information. The tool solves a narrow and real problem for Palm Beach County in Florida, where there's no free public permit API. Instead, county permits are located behind a paywall, and individual cities use diverse systems, making it difficult to query permits live.

The solution involves exporting the permits to CSV or Excel, then using Permit Lead Finder to score and rank the leads based on certain criteria, such as failed inspections, water heater permits, remodeling projects, and aging systems. The program reads the CSV export, scores each property, and outputs the results in a ranked CSV file and color-scaled Excel sheet, with a web view for easy browsing.

It only uses public permit data, including property type, description, status, dates, valuation, and owner name. The scoring system assigns different weights to each category of lead, with failed inspections and water heater permits carrying the most weight. Additional bonuses are given based on the property's valuation and recency, making larger and more recent projects more appealing opportunities.

The tool was built in a modular way, with separate components for data ingestion, scoring, and output generation. The scoring rules, such as weights and thresholds, are stored in YAML files, allowing for easy customization for different jurisdictions without modifying the code. The process involved defining the requirements, creating a spec, planning the tasks, and then using test-driven development to build the product.

The project faced some challenges, including handling dirty data in the public permits exports, normalizing varying valuation formats, and standardizing date formats. The solution was to implement robust parsing logic that gracefully handles missing or malformed data, ensuring the program continues running smoothly without losing data or crashing.