How do I find a contractor's service area?

Understanding where contractors operate is crucial for expanding coverage to lesser-served regions. 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

The Shovels API provides access to permit and contractor data, allowing you to programmatically access building permit and contractor information. The API offers access to two primary objects: Permits and Contractors, with permits being official documents issued by city or county authorities required before commencing construction or alterations to a building.

How It Works

To determine a contractor's service area, you'll analyze their permit history to create a unique list of cities and zip codes where they've worked. This approach provides concrete evidence of their actual operating territories rather than claimed service areas.

API Authentication

Authentication is required for any API request that you make, whether it's in the API Playground or in your own scripts. We use a simple header-based authentication method, X-API-Key: YOUR_API_KEY_HERE. This is available in your Profile Settings > API Key.

Step-by-Step Process

Step 1: Get Permits for a Contractor

Use the /v2/permits/search endpoint to retrieve permits for a specific contractor using the contractor_id parameter. In cases where the required field is a value, like a specific contractor_id or address_id, then it's mandatory to first retrieve the foundational data point before getting the insights for it.

bash

curl -X GET \
  'https://api.shovels.ai/v2/permits/search?contractor_id=YOUR_CONTRACTOR_ID&permit_from=2022-01-01&permit_to=2024-12-31' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Step 2: Extract Geographic Data

The response includes a wealth of information about each permit including jurisdiction and location details. 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

Understanding Permit Data Structure

The response includes information about each permit including description, number, jurisdiction, property_type, tags, and other relevant data. The current version of the API is v2, which is reflected in the endpoints URL structure: /v2/.

Geographic Filtering Capabilities

The new geo_id system enables precise searching by address, zip code, jurisdiction, city, and county - making location-based queries more powerful than ever. With the brand new geo_id schema, we can expand our search capabilities to a broader capacity, now including counties and jurisdictions.

Best Practices

Use Date Ranges: Generally speaking, the required fields are the start and end dates for the query, and the corresponding geo_id to point the query to the right place. Query recent permit data (last 2-3 years) for active service areas.
Handle Pagination: The API returns data in JSON format, either as pages or single objects. Make sure to handle paginated responses to get complete permit histories.
Filter by Property Type: Use property_type parameters to filter by residential or commercial work to understand different service area patterns.

Shovels Online Alternative

In Shovels Online, we show recent permits for each contractor. You can search for permits and contractors at the county, city, or even specific address level and download permit and contractor data to CSV with a single click.

Additional Resources

For more detailed information about using the API, check out the API Reference tab in the documentation hub which outlines all endpoints, parameters, requirements, and responses. You can also use the /list/* endpoints to get the latest valid values for tags and other filters.

For technical support or questions about implementing this approach, reach out to Support at support@shovels.ai.