Skip to main content
Rather than relying on self-reported service areas, you can use a contractor’s actual permit history to map their complete service footprint across cities and zip codes.

​
Overview

By analyzing permit data, you can determine:
  • All cities where a contractor has worked
  • All zip codes in their service area
  • Geographic coverage patterns over time

​
Step-by-Step Process

​
Step 1: Get Permits for a Contractor

Use the /v2/contractors/{id}/permits endpoint to retrieve all permits associated with a specific contractor:
You need the contractor’s id first. Get it from the contractor search endpoint. Note that /permits/search has no contractor_id filter—this dedicated endpoint is the way to pull a single contractor’s permits.

​
Step 2: Extract Geographic Data

From each permit record, extract:
  • City/jurisdiction names
  • Zip codes
  • Any additional geographic identifiers

​
Step 3: Create Unique Lists

Process the permit data to create deduplicated lists of:
  • All cities where the contractor has worked
  • All zip codes in their service area
  • Geographic coverage patterns over time

​
Best Practices

  1. Filter by Recency - The endpoint returns the contractor’s full permit history; filter client-side on permit dates (e.g. last 2-3 years) for active service areas
  2. Handle Pagination - Make sure to handle paginated responses to get complete permit histories
  3. Filter by Property Type - Use each permit’s property_type field to understand different service area patterns (residential vs commercial)

​
Geographic Filtering Capabilities

The geo_id system enables precise searching by:
  • Address
  • Zip code
  • Jurisdiction
  • City
  • County
This makes location-based queries powerful for understanding contractor coverage.

​
Alternative: Shovels Online

In Shovels Online, we show recent permits for each contractor. You can:
  • Search at the county, city, or address level
  • Download permit and contractor data to CSV
  • View contractor profiles with permit history