Skip to main content
The Shovels CLI makes it easy to go from a broad market search to a targeted contractor list in a few commands. In this tutorial, we’ll find the top solar contractors in a California ZIP code, inspect their permit history, and export the results to CSV. This is a common workflow for sales teams, market researchers, and AI agents building lead lists.

​
Step-by-Step Recipe

0

Set Up the CLI

If you haven’t already, install the CLI and configure your API key:
curl -LsSf https://shovels.ai/install.sh | sh
shovels config set api-key YOUR_API_KEY
Verify it works:
shovels version
For detailed setup instructions, see the CLI Quickstart Guide.
1

Find Your Target Market

If you know your ZIP code, you can use it directly as a --geo-id. If you need to find a city or county geo_id, search for it:
shovels cities search -q "Encinitas"

{
  "data": [
    {
      "geo_id": "Q2l0eXxDQXxFbmNpbml0YXM",
      "name": "Encinitas, CA"
    }
  ]
}
For this tutorial, we’ll use ZIP code 92024 (Encinitas, CA).
2

Search for Contractors

Search for solar contractors active in 2024:
shovels contractors search \
  --geo-id 92024 \
  --permit-from 2024-01-01 \
  --permit-to 2024-12-31 \
  --tags solar \
  --limit 20
This returns up to 20 contractors with their names, contact info, permit counts, and ratings.
Add --include-count with --limit 1 to see the total number of matching contractors before fetching the full list.
3

Inspect a Contractor's Permits

Pick a contractor ID from the results and view their permit history:
shovels contractors permits CONTRACTOR_ID --limit 10
This returns individual permits with descriptions, dates, job values, and addresses.To see monthly performance metrics:
shovels contractors metrics CONTRACTOR_ID \
  --metric-from 2024-01-01 \
  --metric-to 2024-12-31 \
  --property-type residential \
  --tag solar
4

Export to CSV

Use jq to transform the JSON output into CSV:
shovels contractors search \
  --geo-id 92024 \
  --permit-from 2024-01-01 \
  --permit-to 2024-12-31 \
  --tags solar \
  --limit all \
  | jq -r '["Name","Phone","Email","Permits","Avg Job Value"],
           (.data[] | [.name, .primary_phone, .primary_email,
            .permit_count, .avg_job_value]) | @csv' \
  > solar_contractors_encinitas.csv
This creates a CSV with headers, ready for a spreadsheet or CRM import.
5

Expand to a Broader Area (Optional)

Scale up by searching at the state level:
shovels contractors search \
  --geo-id CA \
  --permit-from 2024-01-01 \
  --permit-to 2024-12-31 \
  --tags solar \
  --min-permits 10 \
  --limit all \
  | jq -r '["Name","Phone","Permits"],
           (.data[] | [.name, .primary_phone, .permit_count]) | @csv' \
  > solar_contractors_ca.csv
Use --min-permits to filter for contractors with a track record.
If your results are too broad or too narrow, here are some adjustments:
  • Too many results: Add --min-permits, --min-job-value, or narrow the --geo-id to a smaller area
  • Too few results: Expand the date range, use a broader geo_id (county or state), or remove tag filters
  • Wrong specialty: Use shovels tags list to see all available tags and pick the right one
  • Need specific contractors: Add --contractor-name or --contractor-license to filter by known details

​
Additional Help

If you run into issues, check the CLI error codes guide or reach out to support@shovels.ai. Happy Digging!