Release Notes

V2.1.7

2026-04-02

Online
API
EDL (Enterprise Data License)

Introduction

This release marks a major milestone: Shovels is now powered entirely by our own data pipeline. We’ve transitioned away from our third-party permit data provider, giving us full end-to-end ownership over permit and contractor data quality, enrichment, and refresh cycles. While the total permit count is lower, the data is significantly richer — with improved field coverage across the board, a powerful new description_derived field on 81M permits, and better contractor intelligence. This is a one-time transition and a stronger foundation for everything going forward.

✨ New

🔄 Fully Shovels-Owned Pipeline100% Shovels-Owned Data — faster iteration, better enrichment, consistent data provenance.All third-party provider data has been removed. This gives us full control over data quality and allows us to iterate faster on enrichments without vendor dependencies. Each future release will continue as a full snapshot, growing as we expand our coverage.

🏗️ Permits Dataset

Net-New Permits Added

+11.6M Permits — expanded coverage across new jurisdictions: NY (+4.0M), TX (+3.5M), FL (+1.9M)
Total permits in this release: 129.9M
Permits retained with original IDs: 118.3M
Permits filed in March 2026: 352K

New Field: description_derived

81M Permits — 62.4% coverage
A clean, plain-English summary of each permit’s raw description (e.g., “Tear off and replace the roof on an existing single-family home”)

📊 Permit Data QualityField coverage improved significantly in this release:

Subtype coverage: 75.7% (+18%)
Final date coverage: 70.5% (+16%)
Fees coverage: 65.0% (+11%)
Job value coverage: 62.6% (+10%)
Issue date coverage: 80.5% (+9%)
File date coverage: 90.5% (+4%)

👷 Contractor Intelligence

Contractor License Coverage

63.5% (+20%) — up from 43%, significantly richer licensing data on 2.5M contractors
Phone number coverage: 57.7% (+7%)
Email address coverage: 30.2% (+6%)

3 New State Licensing Boards AddedMassachusetts plumbing (~120K plumbers), North Carolina plumbing & electrical, and Iowa plumbing. CSL dataset grew to 3.14M records (+4%).

⚠️ Important Changes

This release includes breaking changes. Please review carefully.Contractor IDs have been regenerated — if you’ve stored contractor IDs, they will need to be updated. We’ve prepared a contractor ID changelog mapping old IDs to new ones — 81.8% of new contractors are mapped. Download below:

API customers: CSV · Parquet
EDL customers: CSV · Parquet

For background on how contractor IDs work, see Why Contractor IDs Can Change.Permit count decreased — from 216M to 130M. 98M older permits sourced from a third-party provider were removed. The 118.3M permits that remain kept their original IDs — no action needed for those records.Contractor count decreased — from 3.9M to 2.5M. This reflects the removal of duplicates and low-quality records. The remaining 2.5M contractors are cleaner and more richly attributed.Some jurisdictions have reduced coverage — DC was dropped entirely. VT, RI, MA, CT, DE, WI, and NM lost >80% of permits due to the removal of third-party data. Coverage will grow as we expand our own data collection.first_seen_date has been reset — all values now fall between 2025-05-19 and 2026-03-28. Going forward, this field will accumulate normally with each biweekly release.Employee and resident records reduced — Employees: 38.1M → 12.8M. Residents: 45.9M → 27.6M.

Introduction

This release transitions Shovels to a fully owned data pipeline, with richer field coverage, a new description_derived field on 81M permits, and better contractor intelligence.

⚠️ This release includes breaking changes. Contractor IDs have been regenerated and permit/contractor counts have changed significantly. See the Important Changes section below.

✨ New

🔄 Fully Shovels-Owned Pipeline100% Shovels-Owned Data — faster iteration, better enrichment, consistent data provenance. All third-party provider data has been removed, giving us full control over data quality and enrichment without vendor dependencies.

🏗️ Permits Dataset

Net-New Permits Added

+11.6M Permits — expanded coverage: NY (+4.0M), TX (+3.5M), FL (+1.9M)
Total permits in this release: 129.9M
Permits retained with original IDs: 118.3M
Permits filed in March 2026: 352K

New Field: description_derived

Available on 81M permits — 62.4% coverage
Plain-English summary of each permit’s raw description

📊 Permit Data Quality

Subtype coverage: 75.7% (+18%)
Final date coverage: 70.5% (+16%)
Fees coverage: 65.0% (+11%)
Job value coverage: 62.6% (+10%)
Issue date coverage: 80.5% (+9%)
File date coverage: 90.5% (+4%)

👷 Contractor Intelligence

Contractor license coverage: 63.5% (+20%)
Phone number coverage: 57.7% (+7%)
Email address coverage: 30.2% (+6%)
3 new state licensing boards: Massachusetts plumbing, North Carolina plumbing & electrical, Iowa plumbing
CSL dataset: 3.14M records (+4%)

⚠️ Important Changes

Contractor IDs have been regenerated — if you’ve stored contractor IDs, they will need to be updated. We’ve prepared a contractor ID changelog mapping old IDs to new ones — 81.8% of new contractors are mapped. Download below:

API customers: CSV · Parquet
EDL customers: CSV · Parquet

For background on how contractor IDs work, see Why Contractor IDs Can Change.Permit count decreased — from 216M to 130M. 98M older third-party permits removed. The 118.3M permits that remain kept their original IDs.Contractor count decreased — from 3.9M to 2.5M, reflecting removal of duplicates and low-quality third-party records.Some jurisdictions have reduced coverage — DC dropped entirely. VT, RI, MA, CT, DE, WI, and NM lost >80% of permits.Field coverage changes — geocoding: 72% → 67%, inspection data: 15% → 3%, address ID: 78% → 74% (improving in upcoming releases).first_seen_date has been reset — all values now fall between 2025-05-19 and 2026-03-28.

Introduction

This release transitions Shovels to a fully owned data pipeline, with richer field coverage, a new description_derived field on 81M permits, and improved contractor intelligence. Please review the Important Changes section for breaking changes.

🏗️ Permits Dataset

Net-New Permits Added

+11.6M Permits — NY (+4.0M), TX (+3.5M), FL (+1.9M)
Total permits in this release: 129.9M
Permits retained with original IDs: 118.3M
Permits filed in March 2026: 352K

New Field: description_derived

81M Permits — 62.4% coverage
Plain-English summaries of permit raw descriptions

📊 Permit Data Quality

Subtype coverage: 75.7% (+18%)
Final date coverage: 70.5% (+16%)
Fees coverage: 65.0% (+11%)
Job value coverage: 62.6% (+10%)
Issue date coverage: 80.5% (+9%)
File date coverage: 90.5% (+4%)

👷 Contractor Intelligence

Contractor license coverage: 63.5% (+20%)
Phone number coverage: 57.7% (+7%)
Email address coverage: 30.2% (+6%)
3 new state licensing boards added
CSL dataset: 3.14M records (+4%)

⚠️ Important Changes

Contractor IDs have been regenerated — if you’ve stored contractor IDs, they will need to be updated. We’ve prepared a contractor ID changelog mapping old IDs to new ones — 81.8% of new contractors are mapped. Download below:

API customers: CSV · Parquet
EDL customers: CSV · Parquet

For background on how contractor IDs work, see Why Contractor IDs Can Change.Permit count decreased — from 216M to 130M. 98M older third-party permits removed. The 118.3M permits that remain kept their original IDs.Contractor count decreased — from 3.9M to 2.5M, reflecting removal of duplicates and low-quality records.Some jurisdictions have reduced coverage — DC dropped entirely. VT, RI, MA, CT, DE, WI, and NM lost >80% of permits.Field coverage changes — geocoding: 72% → 67%, inspection data: 15% → 3%, address ID: 78% → 74% (improving in upcoming releases).first_seen_date has been reset — all values now fall between 2025-05-19 and 2026-03-28.Employee and resident records reduced — Employees: 38.1M → 12.8M. Residents: 45.9M → 27.6M.

V2.1.6

2026-03-02

Online
API
EDL (Enterprise Data License)

Introduction

Big month. We’re launching Shovels CLI — a new way to query permits, contractors, and addresses from the command line (or let your AI agent do it). On the data side, we added 1.8M new permits and geocoded another 1.4M records. Let’s get into it.

✨ New

>_ Introducing Shovels CLIYour AI agent’s gateway to U.S. construction dataOne binary. Zero config. Pure JSON.Search permits, query contractors, resolve addresses — all from your terminalInstall in seconds

curl -LsSf https://shovels.ai/install.sh | sh

Built for automation

JSON-only output to stdout, errors to stderr
Auto-pagination with --limit all
Auto-retry with backoff on rate limits
Help text optimized for LLM comprehension

Works on macOS, Linux, and Windows. Learn more at shovels.ai/cli

🏗️ Permits Dataset

New Permits Discovered

1.8M Records
Expanding historical and current coverage across all jurisdictions
Permits filed in February 2026: 156K
Permits filed year-to-date (2026): 462K

🧱 Permit Activity by Category

Electrical Permits: +388K - Largest category growth this release
New construction permits: +203K
HVAC permits: +136K
Remodel permits: +136K
Roofing permits: +91K
Plumbing permits: +71K
Solar permits: +23K
Demolition permits: +19K
ADU permits: +12K
EV charger permits: +2.2K

📍 Geocoding Improvements

Additional Permits Geocoded

+1.4M Records
Now with latitude and longitude coordinates for spatial analysis

Introduction

Big month. We’re launching Shovels CLI — a new way to query permits, contractors, and addresses from the command line (or let your AI agent do it). The API gained result counts on every paginated endpoint, an improved usage dashboard, and more accurate contractor metrics. On the data side, we added 1.8M new permits and geocoded another 1.4M records.

✨ New

>_ Introducing Shovels CLIYour AI agent’s gateway to U.S. construction dataOne binary. Zero config. Pure JSON.Search permits, query contractors, resolve addresses — all from your terminalInstall in seconds

curl -LsSf https://shovels.ai/install.sh | sh

Built for automation

JSON-only output to stdout, errors to stderr
Auto-pagination with --limit all
Auto-retry with backoff on rate limits
Help text optimized for LLM comprehension

Works on macOS, Linux, and Windows. Learn more at shovels.ai/cli

⚡ API Enhancements

Result Counts on All Paginated Endpoints

7 Endpoints · include_count=true
Get total result counts before paginating
Returns {value, relation} shape — exact count or “10,000+” for large sets

Supported on:

/v2/permits/search
/v2/contractors/search
/v2/contractors/{id}/permits
All 4 geo_permits endpoints

Enhanced Usage DashboardGET /v2/usage now includes:

Daily breakdown
is_over_limit flag
available_at projection so you always know your credit status
Over-limit users can still access usage data

Improved Contractor Metrics AccuracyFixed permit_count and total_job_value inflation for tag=all queries. Average metrics now use permit-count-weighted calculations for mathematical precision.

🏗️ Permits Dataset

New Permits Discovered

1.8M Records
Expanding historical and current coverage across all jurisdictions
Permits filed in February 2026: 156K
Permits filed year-to-date (2026): 462K

🧱 Permit Activity by Category

Electrical Permits: +388K - Largest category growth this release
New construction permits: +203K
HVAC permits: +136K
Remodel permits: +136K
Roofing permits: +91K
Plumbing permits: +71K
Solar permits: +23K
Demolition permits: +19K
ADU permits: +12K
EV charger permits: +2.2K

📍 Geocoding Improvements

Additional Permits Geocoded

+1.4M Records
Now with latitude and longitude coordinates for spatial analysis

✅ No breaking changes. All existing integrations continue to work unchanged.

V2.1.5

2026-02-01

Online
API
EDL (Enterprise Data License)

Introduction

We’re kicking off February with 6.1M new permits, 142K new contractors, and 5.2M additional geocoded records. Here’s the full breakdown.

🚀 What’s New

🏗️ Permits Dataset

New Permits Scraped

6.1M records
Expanding historical and current coverage across all jurisdictions
Permits filed in January 2026: 197K

🧱 Permit Activity by Category

Electrical Permits: +911K - Largest category growth this release
New construction permits: +803K
HVAC permits: +620K
Remodel permits: +549K
Plumbing permits: +447K
Roofing permits: +268K
Solar permits: +234K
Demolition permits: +120K
ADU permits: +100K
EV charger permits: +9K

📍 Geocoding Improvements

Additional Permits Geocoded

+5.2M records
Now with latitude and longitude coordinates

👷 Contractor Intelligence

New Contractors Added

+142K records
Expanding the contractor database

⚠️ ID Updates

5M IDs UpdatedIDs were updated to correct issues arising from data collected across multiple platforms, as well as changes in administrative jurisdictions.

Most affected areas: Oregon, Douglas County, Omaha

For any missing IDs, you can still match using permit number or address fields. Or reach out for assistance.

🤖 Charlie - Your AI Research Agent

What is Charlie?Charlie is your AI research agent for building permits and contractors. Ask questions in plain English—no SQL, no filters—and get answers instantly.January 2026 Updates:

Automatic error recovery – Charlie now automatically reconnects when the backend restarts. No more persistent errors requiring page refreshes.
Clickable profile links – When Charlie returns contractor or permit results, you now get direct links to their profile pages.
Improved county queries – Fixed an issue where county-based queries were failing due to formatting mismatches.

Try it out – Visit charlie.shovels.ai to start asking questions.

V2.1.4

2026-01-01

Online
API
EDL (Enterprise Data License)

Introduction

Happy New Year! We’re starting 2026 with 5.5M new permits, 4.7M additional geocoded records, and 171K new contractors. On the API side, we’ve added negative query filters and dynamic tallies, plus performance improvements for contractor and text search. Here’s everything new this month.

🚀 What’s New

🏗️ Permits Dataset

New Permits Added

5.5M Records
Expanding historical and current coverage across all jurisdictions
Permits filed in December 2025: 295K

🧱 Permit Activity by Category

Electrical Permits: +1.3M - Largest category growth this release
Plumbing permits: +803K
HVAC permits: +569K
New construction permits: +460K
Remodel permits: +351K
Roofing permits: +267K
Solar permits: +131K
ADU permits: +82K
Demolition permits: +65K
EV charger permits: +18K

📍 Geocoding Improvements

Additional Permits Geocoded

+4.7M Records
Now with latitude and longitude coordinates
Total geocoded permits: 143.9M

This release significantly improves spatial completeness for downstream mapping and location-based analysis.

👷 Contractor Intelligence

New Contractors Added

+171K Records
Total now: 3.6M contractors in our database
Additional contractor licenses captured: +256K
Additional primary phone numbers available: +69K
Additional primary email addresses available: +40K

Introduction

Happy New Year! We’re starting 2026 with 5.5M new permits, 4.7M additional geocoded records, and 171K new contractors. On the API side, we’ve added negative query filters and dynamic tallies, plus performance improvements for contractor and text search. Here’s everything new this month.

🚀 What’s New

⚡ API: New Features

Negative Query FiltersExclude specific tags and classifications using a dash prefix:

# Exclude HVAC permits
permit_tags=-hvac

# Mixed: solar permits excluding roofing
permit_tags=solar&permit_tags=-roofing

Note: Pure negative queries at state-level are limited to 365 days. Add a positive filter or use a more specific geo_id to expand the range.

Dynamic Tallies in Contractor SearchUse include_tallies=true to get tag_tally and status_tally per contractor. Tallies are scoped to your search filters (date range, geo, tags).Clarified Contractor Search SemanticsFilters work independently: permit_tags for capability/expertise, permit_from/to for activity period, and tag_tally for work breakdown within that period.

🔧 API: Performance & Bug Fixes

Performance improvements

Contractor search and full-text search (permit_q) are now significantly faster, especially for broad geo queries
Text search also supports English stemming, so “installing” matches “install”

Invalid date range handling

Now returns 422 with a clear message instead of 500 Internal Server Error

Contractor search pagination

Fixed an issue where pagination could prematurely signal end of results

✅ No breaking changes. All existing integrations continue to work unchanged.

🏗️ Permits Dataset

New Permits Added

5.5M Records
Expanding historical and current coverage across all jurisdictions
Permits filed in December 2025: 295K

🧱 Permit Activity by Category

Electrical Permits: +1.3M - Largest category growth this release
Plumbing permits: +803K
HVAC permits: +569K
New construction permits: +460K
Remodel permits: +351K
Roofing permits: +267K
Solar permits: +131K
ADU permits: +82K
Demolition permits: +65K
EV charger permits: +18K

📍 Geocoding Improvements

Additional Permits Geocoded

+4.7M Records
Now with latitude and longitude coordinates
Total geocoded permits: 143.9M

This release significantly improves spatial completeness for downstream mapping and location-based analysis.

👷 Contractor Intelligence

New Contractors Added

+171K Records
Total now: 3.6M contractors in our database
Additional contractor licenses captured: +256K
Additional primary phone numbers available: +69K
Additional primary email addresses available: +40K

V2.1.3

2025-12-01

Online
API
EDL (Enterprise Data License)

Introduction

This month brings substantial improvements across data quality, coverage, and enrichment. We’ve significantly expanded our permits dataset with better field coverage, added 160 new jurisdictions, and continued strengthening our contractor intelligence with enhanced parsing and enrichment.

🚀 What’s New

🏗️ Permits Dataset

Historical Permits Added

6.6M records
Expanding historical coverage across all jurisdictions
Permits filed in November 2025: 222K

✨ Data Quality EnhancementsFee Information Expanded

14M more records
Better financial insights for market analysis
Additional permits with job values: 10M
Additional records with issue dates: 13M
Improved description, type, and subtype coverage
Enhanced permit classification and categorization across the dataset

📍 Coverage Expansion

New Jurisdictions Added

160 jurisdictions
Expanding our nationwide coverage footprint
APN (Assessor’s Parcel Number) field added to 40M permits
Enabling better property linkage and parcel-level analysis

👷 Contractor Intelligence

Dataset Expansion

63K new contractors - expanding your universe of potential partners
Additional addresses parsed: 50K
Additional phone numbers available: 40K
Additional license issue dates captured: 7K
Enhanced geographic coverage
Expanded city, street, and ZIP code coverage across all states

V2.1.2

2025-11-01

Online
API
EDL (Enterprise Data License)

Introduction

This month’s release brings significant intelligence improvements across our platform. We’ve enhanced our data classification capabilities, expanded geographic coverage, and continued growing both our permits and contractor datasets with better enrichment quality.

🚀 What’s New

🧠 Data Intelligence BreakthroughProperty Type Classification Enhanced

20M+ Permits Reclassified
4M additional addresses now correctly labeled as commercial or residential

Our enhanced data pipeline now analyzes permit descriptions—the most reliable source of regulatory context—to automatically infer property types. This means more accurate market segmentation and better targeting capabilities for your use cases.

🏗️ Permits Dataset

Permits filed in October 2025: 180K
Historical permits added to the database: 3.4M

🗺️ Geographic Intelligence

Enhanced FIPS code coverage across all permits
Simplifying geographic analysis and enabling more accurate county-level aggregation for your research and targeting needs

👷 Contractor Intelligence

Dataset Expansion

66K New Contractors - Expanding your universe of potential partners with cleaner, better-deduplicated data
Phone number coverage increased: +3.6%
Email address coverage increased: +4.5%
License field coverage increased: +10.6%

Introduction

This month’s release brings significant intelligence improvements across our platform. We’ve enhanced our data classification capabilities, expanded geographic coverage, and continued growing both our permits and contractor datasets with better enrichment quality.

🚀 What’s New

🔌 API ImprovementsNew Contractor Classification Parameter

contractor_classification_derived - Human-readable categories with nationwide coverage

We’ve introduced a new query parameter that replaces state-specific license codes with standardized, human-readable categories like “electrical”, “hvac”, and “plumbing”. This works consistently across all states, making it easier to filter and discover contractors without domain expertise.

⚠️ Deprecation Notice

Legacy contractor_classifications parameter status: DeprecatedThe old parameter continues to work for backward compatibility, but we recommend migrating to the new standardized taxonomy for better user experience and broader coverage.

🏗️ Permits Dataset

Permits filed in October 2025: 180K
Historical permits added to the database: 3.4M

👷 Contractor Intelligence

Dataset Expansion

66K New Contractors - Expanding your universe of potential partners with cleaner, better-deduplicated data
Phone number coverage increased: +3.6%
Email address coverage increased: +4.5%
License field coverage increased: +10.6%

V2.1.1

2025-10-01

Online
API
EDL (Enterprise Data License)

Introduction

This month marks a pivotal moment in our mission: we’ve begun bridging the gap between online and offline permit data. For the first time, we’re bringing dark data into the light, accessing jurisdictions that have never made their records digitally available. Combined with significant growth across our platform, October’s release represents our most comprehensive coverage to date.

🚀 What’s New

Bridging the Digital Divide: Offline Jurisdictions Brought Online

500K+ Records
First-ever offline permit acquisition from Cook County, IL and Oak Ridge North, TX

Many jurisdictions still operate without public-facing digital portals. We’re now bringing this offline data online, giving you comprehensive coverage without the manual work. This is just the beginning of connecting America’s fragmented permit landscape into one unified, accessible platform.

📊 Data Growth

Total Records

185M (+10M new permit records added - historical and newly filed)
Permits filed in September: 80K
Permits filed in 2025 year-to-date: 4.5M

👷 Contractor Intelligence

New contractors added to our database

190K contractors - Expanding your universe of potential partners and competitors
New license records: 70K
New contractor phone numbers: 200K+
New contractor email addresses: 100K+

V2.1.0

2025-09-14

Online
API
EDL (Enterprise Data License)

✨ New

Total Records: 174 million (+700K from last month)
New Permits from August: 162,281 - Our biggest monthly addition to date!
Permits Transitioned to Finalized Status: 560K
New Address Points: 450K with precise geo-coordinate mapping
New Jurisdictions in Coverage: 119

🚀 Upgrades

Enhanced Data Collection Methods: Improved fill rates across all data points
Job Value Entries: 2.3M+ new entries added across permits for better cost estimation
New Construction Permits: 55,000
New HVAC Permits: 124,000

👷 Contractor Data Enhancements

New Contractors Added: 13,000
New License Records: 70,000
New Phone Numbers: 8,000
New Email Addresses: 30,000

✨ New Permit Records

Total Records: 174 million (+700K from last month)
New Permits from August: 162,281 - Our biggest monthly addition to date!
Permits Transitioned to Finalized Status: 560K
New Address Points: 450K with precise geo-coordinate mapping

🚀 Expanded Jurisdiction Coverage

New Jurisdictions Added: 119 new jurisdictions in our coverage

🛠 Data Quality Improvements

Enhanced Data Collection Methods: Improved fill rates across all data points
Job Value Entries: 2.3M+ new entries added across permits for better cost estimation
New Construction Permits: 55,000
New HVAC Permits: 124,000

👷 Contractor Data Enhancements

New Contractors Added: 13,000
New License Records: 70,000
New Phone Numbers: 8,000 added to contractors.phone_primary
New Email Addresses: 30,000

V2.0.9

2025-07-15

Online
API
EDL (Enterprise Data License)

✨ New

Total new permits added: Over 3 million across all U.S. states.
- California: 2 million of these permits were added, making it our largest single-state update.
2025 permit count-to-date: 2.9 million (through July 15, 2025).
Permits filed since June 1: Over 250,000, with 22,000 filed in July so far.
- Construction: 130,000
- Solar: 125,000
- EV chargers: 10,000
New contractor phone numbers: Over 35,000 new primary phone numbers have been added.

🚀 Upgrades

Continued improving contractor classification standardization. As a result, more contractors now have a Shovels-standard classification assigned to the license_class field.

✨ New

Total new permits added: Over 3 million across all U.S. states.
- California: 2 million of these permits were added, making it our largest single-state update.
2025 permit count-to-date: 2.9 million (through July 15, 2025).
Permits filed since June 1: Over 250,000, with 22,000 filed in July so far.
- Construction: 130,000
- Solar: 125,000
- EV chargers: 10,000
New contractor phone numbers: Over 35,000 new primary phone numbers have been added.

🚀 Upgrades

Continued improving contractor classification standardization. As a result, more contractors now have a Shovels-standard classification assigned to the license_class field.

‼️ Action Required

Token-based pagination is fully live. Page-based pagination will be removed on August 1, 2025. Update any calls that still rely on the deprecated page parameter.

✨ New

Total new permits added: Over 3 million across all U.S. states.
- California: 2 million of these permits were added, making it our largest single-state update.
2025 permit count-to-date: 2.9 million (through July 15, 2025).
Permits filed since June 1: Over 250,000, with 22,000 filed in July so far.
- Construction: 130,000
- Solar: 125,000
- EV chargers: 10,000
New contractor phone numbers: Over 35,000 new primary phone numbers have been added to contractors.phone_primary.

🚀 Upgrades

Continued improving contractor classification standardization. As a result, more contractors now have a Shovels-standard classification assigned to the license_class field.

V2.0.8

2025-07-02

Online
API
EDL (Enterprise Data License)

🚀 Upgrades:

Minor improvements to the UX and ongoing speed enhancements.

🐞 Bug Fixes:

Bug fixes

V2.0.7

2025-06-10

Online
API
EDL (Enterprise Data License)

🚀 Upgrades:

Faster pagination, especially for deeper pages.
More jurisdiction coverage.

✨ Reminder:

Added cursor-based pagination for all endpoints, which substantially improves deep search pagination.

This replaces the former page parameter for pagination. This old method will be supported for an additional three months, at which point it will be deprecated.

✨ New:

Added 1.2 million permits, including 248,000 from May alone, significantly boosted by our new infrastructure.
300 new jurisdictions are now online, increasing our nationwide coverage.
70,000 new contractors added, bringing the total to 2.96 million.
Enhanced deduplication logic eliminated duplicate contractor records, improving data quality.
40,000 additional contact details (phone numbers, emails, addresses) were linked, thanks to infrastructure enhancements.

⚠️ Breaking Changes & Compatibility Notes

‼️ Permit ID Updates:

Approximately 2 million duplicate permits from legacy system migrations were removed. The most affected states are Florida and Texas.
~6% of permits now have new IDs. Attributes such as permit_number and address remain unchanged.

If you query by cached id and encounter missing results (404), use permit_number, address, or other metadata to re-fetch the permit. If you still encounter issues, reach out—we’ll help map old IDs to new ones.

‼️ Contractor ID Updates

~170,000 contractors have new IDs that have been regenerated based on improved data quality.
All contractors remain searchable by:
- Areas of work
- Permit projects
- Business names

If you cache contractor IDs on your end and you encounter not-found responses, use other record attributes to update IDs on your end. If ID changes affect your workflow in a more substantial way, contact us directly and we’ll assist.

V2.0.6

2025-05-06

Online
API
EDL (Enterprise Data License)

🚀 Upgrades:

Improved the Permit Search logic to always order resulting permits by newest first.

✨ New:

Added cursor-based pagination for all endpoints, which substantially improves deep search pagination.

This replaces the former page parameter for pagination. This old method will be supported for an additional three months, at which point it will be deprecated.

🚀 Upgrades:

Improved the response ordering logic to always order results in chronological order, descending.

✨ New:

Added a new apn column to the addresses table
Added two new columns status and status_detailed to the csl and contractors tables
- Status codes for all states are mapped against the following schema:
  - active: License is active and in good standing with no restrictions.
  - active_conditional: License is active but subject to specific conditions, limitations, or temporary provisions.
  - expired: License has lapsed due to non-renewal; typically eligible for renewal.
  - retired: License has been voluntarily placed in an inactive state, often due to the holder retiring or the business closing.
  - suspended: License is temporarily invalid, usually due to disciplinary actions or unresolved administrative issues.
  - revoked: License has been permanently terminated, typically due to serious violations or disciplinary reasons.
  - pending: License application, renewal, or reinstatement is currently under review or being processed.
  - inactive: License is currently not valid, often due to administrative issues or other undefined reasons not captured by the categories above.

🚀 Upgrades:

Expanded csl table coverage by adding 11 new states: CT, GA, IL, MD, MO, OK, NY, OR, SC, TN, UT.

🐞 Bugfix:

Fixed an address parsing issue that was affecting csl table contractors in NV.

V2.0.5

2025-04-03

Online
API
EDL (Enterprise Data License)

✨ New:

General speed improvements
New and improved onboarding flow

🪲 Bug Fixes:

Fixed bug that didn’t change the geo on the download list button
Fixed bug preventing some filters from being “sticky” in between searches
Fixed bug preventing geography profile filters from updating charts

🏗️ Permits:

Total permits: The dataset now contains 171M permits — an increase of 2M compared to the previous batch. With 8 new jurisdictions.
first_seen_date coverage: ~150M permits have a first_seen_date

🧑🏼‍🔧 Contractors:

We now have over 3 million contractors in the dataset, with ~50K new records added this month
License linkage: An additional 80K contractors have been linked to state license files.

📇 Classification coverage:

All contractors with a license now have the classification_derived field as well. This field maps state-specific classifications into standardized categories.
If a contractor has multiple license classifications, they are concatenated using the pipe (”|”) character.

🗂️ License Files:

A new table, CSL, is added to our production database. It contains data from 26 states files, and has a total of 1.8 M contractors.
Around 200K contractors are linked to our Contractors table while the others are new. As part of this new dataset, we have around 700K new contractors phone numbers and 200K new emails.

There were in total almost 3000 different classifications categories across different state files. We standardized this to the following categories: concrete_and_paving, demolition_and_excavation, electrical, fencing_and_glazing, framing_and_carpentry, general_building_contractor, general_engineering_contractor, hvac, landscaping_and_outdoor_work, plumbing, roofing, specialty_trades

V2.0.4

2025-03-14

Online
API
EDL (Enterprise Data License)

✨ New:

Added Website Search filter options to Contractor Filters
Added tooltips to the UI to better explain functionality

🚀 Upgrades:

Added Search filter auto-caching to improve UX between page reloads and sessions
Added new New User onboarding experience
Adjusted datepicker widget for date range selection to monthly, which will improve usability

✨ New:

Added new fields to the /contractors/ endpoint group:
New `/contractors/` fields
- first_seen_date: Date when the contractor was first recorded in the Shovels platform and given an id.
- license_act_date: Date when the contractor’s license became active.
- license_inact_date: Date when the contractor’s license became inactive.
- review_count: Number of reviews the contractor has received.
- rating: Rating of the contractor based on reviews.
- dba: “Doing Business As” name for the contractor.
- sic: Standard Industrial Classification (SIC) code of the contractor.
- naics: North American Industry Classification System (NAICS) code of the contractor.
- linkedin_url: LinkedIn URL of the contractor.
- revenue: Annual revenue of the contractor’s business.
- employee_count: Number of employees working for the contractor.
- primary_industry: Primary industry in which the contractor operates.
Implemented new API rate limits: 1M requests/month, or ~33k requests/day.

✨ New:

Added first_seen_date to the permits table
- this represents the date when the the permit itself was first retrieved for the Shovels platform

This is different than the first_seen_date column in the contractors table, which by contrast represents the date the contractor was first seen in our platform and assigned an id.

V2.0.3

2025-02-06

FINAL WARNING: As previously announced, the V1 of the Shovels API is now deprecated.

Online
API
EDL (Enterprise Data License)

✨ New:

Added Address Profiles
Added Free Forever plan in place of a Free Trial.

🐞 Bugfix:

Fixed issue where Geography Profiles (City, Jurisdiction, County, etc) filters for Property Type and Permit Category weren’t updating counts correctly.

✨ New:

Added new /v2/{geography}/{geo_id}/metrics/monthly endpoint.
Added new /v2/{geography}/{geo_id}/metrics/current endpoint.

💥 Breaking:

Removed /v2/{geography}/{geo_id}/metrics endpoint.
Changed monetary value data types from decimal integer (eg, dollars cents). This will affect the following parameters:
/permits
- property_assess_market_value
- job_value
- fees
/contractors
- avg_job_value
- total_job_value
/contractors/{id}/metrics
- avg_job_value
- total_job_value
/{geography}/{geo_id}/metrics/{interval}
- total_job_value
Changed percentage data types from decimal integer (eg, 0.75 75). This will affect the following parameters:
/permits
- inspection_pass_rate
/contractors
- avg_inspection_pass_rate
/contractors/{id}/metrics
- avg_inspection_pass_rate
/{geography}/{geo_id}/metrics/{interval}
- avg_inspection_pass_rate

🐞 Bugfix:

Fixed issue where address object’s latitude and longitude coordinates were occasionally reversed, and built in anomaly detection and correction for future processing.
- This fix continues downstream to API and Online records.

Breaking Changes Policies

In order to ensure smooth transitions between updates, we’ve settled on a few short term policies.

We will do our best to give as much advance warning on breaking changes as possible.
- Some recent breaking changes are delayed updates to the schema that should have been part of the V2 launch. We do not plan on making breaking changes this often.
Where sensible and possible, we will provide backward compatibility for new endpoints, parameters, and schemas.

Address Coordinate Errors

As described under EDL changes above, we found that there were rare cases where the latitude and longitude coordinates were reversed. Affected records have been corrected.We’ve also beefed up our address-geospatial processing to find and fix these errors going forward.

Effective Dates

Online: Monday, February 03, 2025.
API: Monday, February 10, 2025.
EDL: Wednesday, February 6, 2025.

V2.0.2

2025-01-09

Online
API
EDL (Enterprise Data License)

✨ New:

Added employees to Contractor Profiles.
Added links to Jurisdiction Profiles for all permits.
Added links to City Profiles and County Profiles for all geo-related profiles.

🐞 Bugfixes:

Fixed password reset bug.

✨ New:

Added new /v2/contractors/{id}/employees endpoint.
Added new /v2/addresses/{id}/metrics endpoint.

⚠️ End of Life:

We will DEPRECATE the API V1 by the end of January 2025.

Please update all endpoints using the old schema before January 31, 2025 to ensure continued usage.

🐞 Bugfixes:

Fixed metrics calculation algorithm on all endpoints.

💥 Breaking:

contractors table:
- first_seen_at renamed first_seen_date.
  - Data type changed DATE.
- reviews renamed review_count.
residents table:
- Foreign key changed from permit_id address_id.
  - Please note: The address_id field is also the foreign key for the permits table, allowing easier joins between residents and permits tables.

Please ensure that any existing queries or automation using first_seen_at, reviews, or permit_id are updated accordingly.

Coverage Expansion

These new permits will be available across the entire platform.

✨ New:

+6M permits nationwide.
+9 permit jurisdictions.

V2.0.1

2024-12-04

Online
API
EDL (Enterprise Data License)

✨ New:

Added +2M permits in Texas.
Added metric visualizations to Contractor Profiles.

🐞 Bugfixes:

Corrected issue where Contractor Profiles wouldn’t load properly.

✨ New:

residents endpoint.

🚀 Upgrades:

Improved address validation for all geography-related fields, in line with US Census data.

💥 Breaking:

Casing standardizations (please update accordingly if your logic is case-sensitive):
- property_type values are now lower case, eg residential.

✨ New:

first_seen_at column in the contractor table.
employees table, linked to contractors table:
- Includes a wide range of firmographic data for individual employees.
- See “Schema Updates” below for the full list of columns.

🚀 Upgrades:

additional columns in the residents table. See “Schema Updates” below for the full list.

💥 Breaking:

Casing standardizations (in addition to the changes outlined in the API Section previously).
- property_owner_type values are now snake_case, eg individual or company_owned.
- owner_name, owner_street, owner_city values are now upper case, eg JANE DOE, MAIN ST, or AGAWAM.
- applicant_name, applicant_street, applicant_city values are now upper case, just like owner_$ above.
(PLANNED) Replacement of permits_ids with address_id in the residents table (please update your pipelines that use this foreign key value.)
- This change will go into effect January 2025.

Schema Updates

We made a number of additions to our datasets, including new columns. For breaking changes to casing, see “API” above.

New columns in the 'residents' table:

personal_emails_validation_status (string): The validation status of the associated personal email. ‘Valid’ indicates a validated email; null means unknown.
personal_emails_last_seen (date): The date of the last validation or verification attempt for the personal email. Null if unknown.
business_email (string): The primary business email observed for this person.
business_email_validation_status (string): Validation status of the business email. ‘Valid’ means the email was validated; null means unknown. May contain values like ‘Valid-ESP’ (validated by email service provider) or ‘Valid-Digital’ (validated by cookie/digital tag).
business_email_last_seen (date): The date of the last known validation or verification attempt of the business email. Null if unknown.
linkedin_url (string): URL of the person’s LinkedIn profile.
homeowner (string): Reports if the person in this record is a homeowner. Y and N are observed values, P represents that they are likely a homeowner, based on probabilistic modeling, and null values represent ‘unknown’.
gender (string): The person’s gender.
age_range (string): The person’s age mapped to standard demographic ranges.
is_married (boolean): Indicates if the person is married.
has_children (boolean): Indicates if the person has children.
income_range (string): The person’s income range.
net_worth (string): The person’s net worth, mapped to standard demographic ranges. Null if unknown.
job_title (string): The person’s job title.
seniority_level (string): The seniority level of the person’s role.
department (string): The department in which the person works.
job_title_last_updated (date): The last date the person’s job title was updated.
last_updated (date): The last date any value in this record was updated.
work_history (string, JSON): A JSON-formatted history of the person’s work experiences (e.g., company name, * position, duration, start/end time, job description, location, social_url).
education_history (string): The person’s education background.
social_connections (string): The number of social media connections the person has, provided in ranges (e.g., 1-9, 10-49, etc.).
company_name (string): The name of the company where the person works.
company_domain (string): The company’s domain.
company_phone (string): The company’s contact phone number.
company_sic (string): The Standard Industrial Classification (SIC) code(s) of the company, separated by semicolons if multiple.
company_street_no (string): The street number of the company’s address.
company_street (string): The street name of the company’s address.
company_city (string): The city in which the company is located.
company_zip (string): The company’s 5-digit ZIP code.
company_state (string): The uppercase state abbreviation for the company’s address.
company_linkedin_url (string): The URL of the company’s LinkedIn profile.
company_revenue (string): The company’s revenue, expressed in standard ranges.
company_employee_count (string): The number of observed US enterprise employees at the company, provided in * standard firmographic ranges.
company_primary_industry (string): The primary industry in which the company operates.
company_description (string): A description of the company’s business activities.
company_naics (string): The company’s North American Industry Classification System (NAICS) code(s).

New 'employees' table (connected to 'contractors'):

contractor_id (string)
person_id (string)
name (string)
street_no (string)
street (string)
city (string)
zipcode (string)
zipcode_ext (string)
state (string)
phone (string)
email (string)
email_validation_status (string)
email_last_seen (date)
business_email (string)
business_email_validation_status (string)
business_email_last_seen (date)
linkedin_url (string)
homeowner (string)
gender (string)
age_range (string)
is_married (boolean)
has_children (boolean)
income_range (string)
net_worth (string)
job_title (string)
seniority_level (string)
department (string)
job_title_last_updated (date)
work_history (string, JSON formatted)
education_history (string)

​Introduction

​✨ New

​🏗️ Permits Dataset

​👷 Contractor Intelligence

​⚠️ Important Changes

​Introduction

​✨ New

​🏗️ Permits Dataset

​👷 Contractor Intelligence

​⚠️ Important Changes

​Introduction

​🏗️ Permits Dataset

​👷 Contractor Intelligence

​⚠️ Important Changes

​Introduction

​✨ New

​🏗️ Permits Dataset

​📍 Geocoding Improvements

​Introduction

​✨ New

​⚡ API Enhancements

​🏗️ Permits Dataset

​📍 Geocoding Improvements

​Introduction

​🏗️ Permits Dataset

​📍 Geocoding Improvements

​Introduction

​🚀 What’s New

​🏗️ Permits Dataset

​📍 Geocoding Improvements

​👷 Contractor Intelligence

​⚠️ ID Updates

​🤖 Charlie - Your AI Research Agent

​Introduction

​🚀 What’s New

​🏗️ Permits Dataset

​📍 Geocoding Improvements

​👷 Contractor Intelligence

​⚠️ ID Updates

​Introduction

​🚀 What’s New

​🏗️ Permits Dataset

​📍 Geocoding Improvements

​👷 Contractor Intelligence

​⚠️ ID Updates

​Introduction

​🚀 What’s New

​🏗️ Permits Dataset

​📍 Geocoding Improvements

​👷 Contractor Intelligence

​Introduction

​🚀 What’s New

​⚡ API: New Features

​🔧 API: Performance & Bug Fixes

​🏗️ Permits Dataset

​📍 Geocoding Improvements

​👷 Contractor Intelligence

​Introduction

​🚀 What’s New

​🏗️ Permits Dataset

​📍 Geocoding Improvements

​👷 Contractor Intelligence

​Introduction

​🚀 What’s New

​🏗️ Permits Dataset

​📍 Coverage Expansion

​👷 Contractor Intelligence

​Introduction

​🚀 What’s New

​🏗️ Permits Dataset

​📍 Coverage Expansion

​👷 Contractor Intelligence

​Introduction

​🚀 What’s New

​🏗️ Permits Dataset

​📍 Coverage Expansion

​👷 Contractor Intelligence

​Introduction

​🚀 What’s New

Introduction

✨ New

🏗️ Permits Dataset

👷 Contractor Intelligence

⚠️ Important Changes

Introduction

✨ New

🏗️ Permits Dataset

👷 Contractor Intelligence

⚠️ Important Changes

Introduction

🏗️ Permits Dataset

👷 Contractor Intelligence

⚠️ Important Changes

Introduction

✨ New

🏗️ Permits Dataset

📍 Geocoding Improvements

Introduction

✨ New

⚡ API Enhancements

🏗️ Permits Dataset

📍 Geocoding Improvements

Introduction

🏗️ Permits Dataset

📍 Geocoding Improvements

Introduction

🚀 What’s New

🏗️ Permits Dataset

📍 Geocoding Improvements

👷 Contractor Intelligence

⚠️ ID Updates

🤖 Charlie - Your AI Research Agent

Introduction

🚀 What’s New

🏗️ Permits Dataset

📍 Geocoding Improvements

👷 Contractor Intelligence

⚠️ ID Updates

Introduction

🚀 What’s New

🏗️ Permits Dataset

📍 Geocoding Improvements

👷 Contractor Intelligence

⚠️ ID Updates

Introduction

🚀 What’s New

🏗️ Permits Dataset

📍 Geocoding Improvements

👷 Contractor Intelligence

Introduction

🚀 What’s New

⚡ API: New Features

🔧 API: Performance & Bug Fixes

🏗️ Permits Dataset

📍 Geocoding Improvements

👷 Contractor Intelligence

Introduction

🚀 What’s New

🏗️ Permits Dataset

📍 Geocoding Improvements

👷 Contractor Intelligence

Introduction

🚀 What’s New

🏗️ Permits Dataset

📍 Coverage Expansion

👷 Contractor Intelligence

Introduction

🚀 What’s New

🏗️ Permits Dataset

📍 Coverage Expansion

👷 Contractor Intelligence

Introduction

🚀 What’s New

🏗️ Permits Dataset

📍 Coverage Expansion

👷 Contractor Intelligence

Introduction

🚀 What’s New

🏗️ Permits Dataset