Definitions of key terms used in Shovels building permit and contractor data: geo_id, AHJ, jurisdiction, permit status, contractor ID, address ID, and more.
A comprehensive glossary of terms used throughout Shovels documentation, API, and data products.
A unique identifier assigned by Shovels to each distinct address in our database. The address ID remains consistent even if the address formatting varies across different permits, enabling you to link all permits at a single property.
The governmental body responsible for issuing building permits in a specific geographic area. An AHJ is typically a city or county government that establishes building codes, conducts inspections, and maintains permit records. The United States has approximately 20,000 AHJs.
A unique authentication token required to access the Shovels API. Include it in the X-API-Key header of every request. Access your key at app.shovels.ai/profile-settings.
A unique identifier assigned by Shovels to each contractor. Contractor IDs are deduplicated within each state, meaning the same contractor operating in multiple states will have separate IDs per state.
An identifier linking multiple contractors that operate under the same parent organization. For example, regional branches of a national company share the same group ID.
The process of identifying and consolidating duplicate records. Shovels deduplicates permits (maintaining one record per permit even with status updates) and contractors (linking related business entities).
Shovels’ bulk data product for enterprise customers. EDL delivers complete datasets to data warehouses like Snowflake, BigQuery, or Databricks, with more fields than the API and monthly refresh cycles.
A unified geographic identifier used by Shovels to link addresses to permit data. A geo_id can represent different geographic levels: a state (CA), zip code (94103), city, county, or specific address. Use the Address Search API to obtain a geo_id for any location.
The process of converting addresses into geographic coordinates (latitude and longitude). Shovels performs geocoding in-house using multiple reference sources including the National Address Dataset, Open Address, Simple Maps, and ESRI.
A permit status indicating the permit process has stalled. Reasons include failed inspections, permit expiration, or inactivity for more than 180 days.
A boolean field in EDL data indicating whether a contractor record is the primary representative of a contractor group. When TRUE, this record contains the canonical information for the entire group.
NAICS (North American Industry Classification System)
A modern industry classification system used to categorize businesses. More specific than SIC codes but less widely adopted. Available in Shovels contractor data.
A permit approved immediately without requiring follow-up inspections. Common for simple projects like solar installations or minor plumbing work. These permits may have a “final” status without a final date.
A unique identifier generated by Shovels for each permit. Unlike permit numbers (which may duplicate across jurisdictions), Shovels permit IDs are globally unique and persistent throughout the permit lifecycle.
The permit number assigned by the issuing jurisdiction. Not globally unique—different jurisdictions may assign the same number to different permits. Use Shovels’ permit ID for unique identification.
The most frequently used email address across all permits for a given contractor. Determined by analyzing frequency across the contractor’s permit history.
The maximum number of records you can retrieve via the API. Free trials include 250 credits. Each record returned counts against your credits. Paid plans have custom limits—contact sales for details. See API rate limits for full information.
Shovels-assigned categories that classify permits by work type (e.g., solar, HVAC, electrical, roofing). Use the /list/tags endpoint to get valid tag values.
A permit status indicating insufficient data to determine the current state. May result from incomplete jurisdiction records or missing date information.
