# Shovels Documentation

## Docs

- [Welcome to Shovels](https://docs.shovels.ai/docs/introduction.md): Discover the Shovels.ai platform—your comprehensive resource for construction data, APIs, and developer tools. Access industry-leading insights, technical documentation, and everything you need to build, integrate, and innovate with construction intelligence.
- [Shovels Online Quickstart Guide](https://docs.shovels.ai/docs/shovels-online-quickstart-guide.md): This guide will help you get started with Shovels Online, the web-based application for exploring the Shovels dataset.
- [Introducing the Shovels API](https://docs.shovels.ai/docs/shovels-api-introduction.md): Comprehensive guide to the Shovels REST API, including authentication, pagination, error handling, and getting started information.
- [Shovels CLI Quickstart Guide](https://docs.shovels.ai/docs/shovels-cli-quickstart.md): Install the Shovels CLI, configure your API key, and run your first permit search in under a minute.
- [Building an Accurate Contractor Search](https://docs.shovels.ai/docs/tutorial-online-contractor-search.md): This tutorial will help you build an accurate search query in Shovels Online to find Contractors.
- [Building a Contractor Pipeline with the CLI](https://docs.shovels.ai/docs/tutorial-cli-contractor-pipeline.md): This tutorial walks through using the Shovels CLI to find top contractors in a market, pull their details, and export to CSV — all from your terminal.
- [Retrieving Permit History for an Address](https://docs.shovels.ai/docs/tutorial-api-address-permit-history.md): This tutorial will show you how to use the Shovels API to retrieve permit history for an address.
- [FAQ](https://docs.shovels.ai/docs/shovels-faq.md): Frequently asked questions about the Shovels platform.
- [Shovels Online Troubleshooting](https://docs.shovels.ai/docs/shovels-online-troubleshooting.md): Common issues and how to fix them when using Shovels Online.
- [Shovels API Troubleshooting](https://docs.shovels.ai/docs/shovels-api-troubleshooting.md): Common issues and how to fix them when using the Shovels API.
- [Overview](https://docs.shovels.ai/docs/data-dictionary-index.md)
- [Online](https://docs.shovels.ai/docs/data-dictionary-online.md): The complete list of fields and filters available in **Shovels Online**.
- [API](https://docs.shovels.ai/docs/data-dictionary-api.md): All fields, parameters, and objects available in the **Shovels API** schema.
- [Enterprise Data License](https://docs.shovels.ai/docs/data-dictionary-edl.md): The exhaustive list of all fields in the Shovels platform, sorted by table.
- [Building Blocks](https://docs.shovels.ai/docs/foundations-building-blocks.md): Understanding the key data components that make up the Shovels platform.
- [Data Philosophy](https://docs.shovels.ai/docs/foundations-data-philosophy.md): Gain insights into how the Shovels team approaches the data in our platform.
- [Permit Availability](https://docs.shovels.ai/docs/foundations-understanding-permits.md): Introduction to US permit availability and variation across 20k+ jurisdictions.
- [Search Permits](https://docs.shovels.ai/api-reference/permits/search-permits.md): Returns a list of matching permits records. Permits should meet ALL of the parameter filters. Multiple parameters are treated as AND queries. Use contractor_classification_derived to filter by contractor's derived classifications (ALL specified values required).
- [Get Permits By Id](https://docs.shovels.ai/api-reference/permits/get-permits-by-id.md): Returns a list of permits records for given IDs. Results are paginated using cursor-based pagination for efficient navigation.
- [Search Decisions](https://docs.shovels.ai/api-reference/decisions/search-decisions.md): Returns a list of zoning / land-use decisions matching the supplied filters. Decisions should meet ALL parameter filters (AND logic). Date range (`decision_from`/`decision_to`) and `geo_id` are required.
- [Get Decisions By Id](https://docs.shovels.ai/api-reference/decisions/get-decisions-by-id.md): Returns the requested decisions by ID. Unknown IDs are silently omitted (no per-ID 404). Up to 50 IDs per request.
- [Get Contractors By Id](https://docs.shovels.ai/api-reference/contractors/get-contractors-by-id.md): Returns contractors by their IDs. Multiple `id` query parameters can be provided in the same API call
- [Search Contractors](https://docs.shovels.ai/api-reference/contractors/search-contractors.md): Returns contractors doing work within the given location area filtered by type of work. Contractors must meet all specified parameters, with multiple parameters treated as AND queries. Use contractor_classification_derived to filter by derived classifications (ALL specified values required). The per…
- [Get Permits By Contractor Id](https://docs.shovels.ai/api-reference/contractors/get-permits-by-contractor-id.md): Retrieves all permits associated with a single contractor.
- [Get Contractor Employees](https://docs.shovels.ai/api-reference/contractors/get-contractor-employees.md): Returns a paginated list of employees for a specific contractor.
- [Get Filtered Metrics By Contractor Id](https://docs.shovels.ai/api-reference/contractors/get-filtered-metrics-by-contractor-id.md): Returns contractor monthly metrics filtered by contractor ID, property type, and tags. Metrics include permit count, average duration, and average pass rate.
- [Search Addresses](https://docs.shovels.ai/api-reference/addresses/search-addresses.md): Searches addresses by their text fields (street number, street, city, state, and ZIP code) using prefix, full-text, and fuzzy matching.
- [Get Address Metrics Monthly](https://docs.shovels.ai/api-reference/addresses/get-address-metrics-monthly.md): Returns monthly address metrics.
- [Get Address Metrics Current](https://docs.shovels.ai/api-reference/addresses/get-address-metrics-current.md): Returns current address metrics.
- [Get Residents](https://docs.shovels.ai/api-reference/addresses/get-residents.md): Return residents for a given address geo ID. Results are paginated using cursor-based pagination.
- [Search Cities](https://docs.shovels.ai/api-reference/cities/search-cities.md): Searches for cities based on the provided search term.
- [Get City Metrics Monthly](https://docs.shovels.ai/api-reference/cities/get-city-metrics-monthly.md): Returns monthly city metrics.
- [Get City Metrics Current](https://docs.shovels.ai/api-reference/cities/get-city-metrics-current.md): Returns current city metrics.
- [Get City Details](https://docs.shovels.ai/api-reference/cities/get-city-details.md): Return city details and related location hierarchy.
- [Search Counties](https://docs.shovels.ai/api-reference/counties/search-counties.md): Searches for counties based on the provided search term.
- [Get County Metrics Monthly](https://docs.shovels.ai/api-reference/counties/get-county-metrics-monthly.md): Returns monthly county metrics.
- [Get County Metrics Current](https://docs.shovels.ai/api-reference/counties/get-county-metrics-current.md): Returns current county metrics.
- [Get County Details](https://docs.shovels.ai/api-reference/counties/get-county-details.md): Return county details and related location hierarchy.
- [Search Jurisdictions](https://docs.shovels.ai/api-reference/jurisdictions/search-jurisdictions.md): Searches for jurisdictions based on the provided search term.
- [Get Jurisdiction Metrics Monthly](https://docs.shovels.ai/api-reference/jurisdictions/get-jurisdiction-metrics-monthly.md): Returns monthly jurisdiction metrics.
- [Get Jurisdiction Metrics Current](https://docs.shovels.ai/api-reference/jurisdictions/get-jurisdiction-metrics-current.md): Returns current jurisdiction metrics.
- [Get Jurisdiction Details](https://docs.shovels.ai/api-reference/jurisdictions/get-jurisdiction-details.md): Return jurisdiction details and related location hierarchy.
- [Search Zipcodes](https://docs.shovels.ai/api-reference/zipcodes/search-zipcodes.md): Searches for zipcodes based on the provided search term.
- [Search States](https://docs.shovels.ai/api-reference/states/search-states.md): Searches for US states based on the provided search term.
- [Get Data Release Date](https://docs.shovels.ai/api-reference/meta/get-data-release-date.md): Returns the release date of the current data served by the API.
- [Get Coverage](https://docs.shovels.ai/api-reference/meta/get-coverage.md): Returns per-field data coverage tiers (partial or missing) for the specified geography and date range. Fields classified as reliable (fill rate >= 80%) are omitted. Empty windows return all 10 tracked fields as missing with permits_total=0.
- [Get All Available Zip Codes](https://docs.shovels.ai/api-reference/lists/get-all-available-zip-codes.md): Returns all available ZIP codes for which we have permit and contractor data.
- [Get All Available Tags](https://docs.shovels.ai/api-reference/lists/get-all-available-tags.md): Returns all available permit tags.
- [Get Properties By Id](https://docs.shovels.ai/api-reference/properties/get-properties-by-id.md): **Beta.** Query parameters, response fields, and the absence-trust surface may still change in response to how the endpoint is used in practice. Treat the shape as unstable while it is in beta. Returns properties by their address id. Provide up to 50 `id` query parameters in one call; rows come back…
- [Search Properties](https://docs.shovels.ai/api-reference/properties/search-properties.md): **Beta.** Query parameters, response fields, and the absence-trust surface may still change in response to how the endpoint is used in practice. Treat the shape as unstable while it is in beta. Returns properties within a geo scope (state, county, city, ZIP, ZIP+4, or address) and/or owned by named…
- [Get Usage](https://docs.shovels.ai/api-reference/usage/get-usage.md): Get your current credit usage for the rolling 30-day period.
- [Release Notes](https://docs.shovels.ai/release-notes/release-notes.md): Find out what the Engineering team has been up to across our entire platform, including general announcements, updates, and bugfixes.
- [Shovels Knowledge Base](https://docs.shovels.ai/docs/knowledge-base/index.md): Find answers to common questions about Shovels building permit and contractor data, API usage, Shovels Online, and Enterprise Data License products.
- [Quick Answers](https://docs.shovels.ai/docs/knowledge-base/quick-answers.md): Fast answers to the most common Shovels questions about API limits, data coverage, pricing, permit data, contractors, and more.
- [Shovels Glossary](https://docs.shovels.ai/docs/knowledge-base/glossary.md): Definitions of key terms used in Shovels permit, contractor, and decision data: geo_id, AHJ, jurisdiction, permit status, contractor ID, zoning, rezoning, and more.
- [What's Included in the Shovels Free Trial?](https://docs.shovels.ai/docs/knowledge-base/getting-started/free-trial-guide.md): The Shovels free trial includes permit and contractor search, filters, and 250 API requests with full historical access. No credit card required.
- [How Much Does Shovels Cost?](https://docs.shovels.ai/docs/knowledge-base/getting-started/pricing-structure.md): Shovels offers free trials, paid Online/API plans (see app.shovels.ai), and custom Enterprise Data License (EDL) pricing. Contact sales for EDL quotes.
- [What Makes Shovels Different From Other Permit Data Providers?](https://docs.shovels.ai/docs/knowledge-base/getting-started/key-differentiators.md): Shovels differentiates with: 1) USPS-standardized addresses, 2) contractor grouping linking related businesses, 3) 98% AI accuracy, 4) sophisticated deduplication.
- [What Is Charlie AI?](https://docs.shovels.ai/docs/knowledge-base/getting-started/charlie-ai.md): Charlie is Shovels' AI research agent at charlie.shovels.ai. Ask permit data questions in plain English and get instant answers — no filters, downloads, or code required.
- [How to Access Your API Key](https://docs.shovels.ai/docs/knowledge-base/api/basics/api-key-access.md): Learn how to access and manage your Shovels API key from your account dashboard for authenticating API requests.
- [Understanding API Endpoints](https://docs.shovels.ai/docs/knowledge-base/api/basics/api-endpoints.md): Quick overview of Shovels API endpoints. For complete details, see the API Reference documentation.
- [Understanding Query Parameters](https://docs.shovels.ai/docs/knowledge-base/api/basics/query-parameters.md): Learn how to use query parameters in the Shovels API to filter and refine your permit and contractor searches.
- [Why is job_value Returned in Cents?](https://docs.shovels.ai/docs/knowledge-base/api/basics/job-value-cents.md): Learn why the Shovels API returns job_value in cents rather than dollars, following industry-standard practices for handling monetary values.
- [What is My API Credit Limit?](https://docs.shovels.ai/docs/knowledge-base/api/basics/credit-limits.md): Learn about Shovels API credit limits for paid plans, the free trial request system, and how to get higher limits for your needs.
- [What Are the Shovels API Rate Limits?](https://docs.shovels.ai/docs/knowledge-base/api/basics/rate-limits.md): Learn about the Shovels API rate limits that protect system stability and ensure fair access for all users.
- [How Do API Credits Work?](https://docs.shovels.ai/docs/knowledge-base/api/basics/request-counts.md): The Shovels API uses a record-based credit system. Each record returned counts against your credits—a search returning 100 permits uses 100 credits, while a single permit lookup uses 1.
- [How Many Permits Can I Retrieve Per API Call?](https://docs.shovels.ai/docs/knowledge-base/api/basics/permits-per-call.md): Learn about the maximum number of permits you can retrieve in a single Shovels API call and how to paginate through larger result sets.
- [How to Verify Your API Request Was Successful](https://docs.shovels.ai/docs/knowledge-base/api/basics/successful-requests.md): Learn how to determine if your Shovels API request succeeded by checking HTTP status codes and response data.
- [Can I Automate API Calls?](https://docs.shovels.ai/docs/knowledge-base/api/basics/automate-calls.md): Learn how to automate Shovels API calls by integrating the API into your applications using programming languages like Python.
- [Resolving Addresses to geo_id](https://docs.shovels.ai/docs/knowledge-base/api/address-resolution/resolving-addresses.md): Learn the essential first step in using the Shovels API: resolving addresses through our Address Search endpoint to get the geo_id for permit queries.
- [What is a geo_id and How Do I Get One?](https://docs.shovels.ai/docs/knowledge-base/api/address-resolution/geo-id-lookup.md): A geo_id is Shovels' unified geographic identifier for addresses, zip codes, cities, counties, jurisdictions, and states. Each geography level has its own search endpoint for resolving a geo_id.
- [State and Zip Code Validation in Address Searches](https://docs.shovels.ai/docs/knowledge-base/api/address-resolution/state-zip-validation.md): Understand how the Shovels API handles state and zip code validation in address searches and what to expect with incorrect location parameters.
- [How to Search for Permits](https://docs.shovels.ai/docs/knowledge-base/api/permits/permit-search.md): Learn how to use the Shovels API to search for building permits using geo_id, including step-by-step instructions and best practices.
- [How to Search Permits by State](https://docs.shovels.ai/docs/knowledge-base/api/permits/permits-by-state.md): Learn how to search for building permits in a specific US state using the Shovels API with 2-letter state abbreviations.
- [How to Search for Properties](https://docs.shovels.ai/docs/knowledge-base/api/properties/property-search.md): Learn how to use the Shovels API to search US properties with the /properties/search endpoint, including required parameters, filters, and pagination.
- [Get Properties by ID](https://docs.shovels.ai/docs/knowledge-base/api/properties/properties-by-id.md): Fetch full property records for up to 50 known property IDs in one call with the Shovels API /properties endpoint.
- [Finding Properties With No Permit on Record](https://docs.shovels.ai/docs/knowledge-base/api/properties/absence-queries.md): Use absence filters on the Shovels /properties/search endpoint to find properties with no permit of a given type, and read the trust fields that score every absence answer.
- [Finding Properties With Unfinaled Permits](https://docs.shovels.ai/docs/knowledge-base/api/properties/unfinaled-permits.md): Use the permit_tags_unfinaled filter on the Shovels /properties/search endpoint to find properties where a permit was pulled but never finaled.
- [Properties vs Permits: Which Endpoint?](https://docs.shovels.ai/docs/knowledge-base/api/properties/properties-vs-permits.md): When to use the Shovels /properties endpoints and when to use /permits/search, including the queries properties deliberately don't support.
- [How to Search for Decisions](https://docs.shovels.ai/docs/knowledge-base/api/decisions/searching-decisions.md): Learn how to use the Shovels API to search zoning and land use decisions with the /decisions/search endpoint, including required parameters and filters.
- [How to Get Decisions by ID](https://docs.shovels.ai/docs/knowledge-base/api/decisions/decisions-by-id.md): Retrieve specific Shovels Decision records by their decision ID using the /decisions endpoint.
- [Where Decisions Are Available](https://docs.shovels.ai/docs/knowledge-base/api/decisions/decisions-availability.md): Which Shovels plans include Decisions, how decisions coverage compares to permits, and where to learn more.
- [How to Search for Contractors](https://docs.shovels.ai/docs/knowledge-base/api/contractors/contractor-search.md): Learn the difference between permit search and contractor search in the Shovels API, and how to find contractor contact information and permit history.
- [How to Get Contractor Employee Information](https://docs.shovels.ai/docs/knowledge-base/api/contractors/employee-data.md): Learn how to use the Shovels API to retrieve contractor employee contact details including business and personal emails, job titles, and seniority levels.
- [How to Find a Contractor's Service Area](https://docs.shovels.ai/docs/knowledge-base/api/contractors/service-area-lookup.md): Use the Shovels API to identify all cities and zip codes where a contractor has worked by analyzing their permit history.
- [How to Filter Contractors by Company Size](https://docs.shovels.ai/docs/knowledge-base/api/contractors/filtering-by-size.md): Learn how to use employee count ranges in the Shovels API to filter contractors by company size for targeted outreach.
- [How to Identify Independent Contractors](https://docs.shovels.ai/docs/knowledge-base/api/contractors/independent-contractors.md): Learn reliable methods to identify sole proprietors and individual contractors in the Shovels API data.
- [API Error Handling](https://docs.shovels.ai/docs/knowledge-base/api/errors/error-handling.md): Quick guide to handling Shovels API errors. For complete details, see the API Introduction documentation.
- [What Does a 422 Error Mean in the Shovels API?](https://docs.shovels.ai/docs/knowledge-base/api/errors/422-error.md): A 422 error means a required parameter is missing. Usually, you need to resolve your address to a geo_id first using the Address Search endpoint.
- [How Do I Install the Shovels CLI?](https://docs.shovels.ai/docs/knowledge-base/cli/installation.md): Install the Shovels CLI on macOS, Linux, or Windows using the install script or by downloading binaries directly from GitHub Releases.
- [How Does CLI Authentication Work?](https://docs.shovels.ai/docs/knowledge-base/cli/authentication.md): The Shovels CLI authenticates using your API key, provided via environment variable or config file. Learn how to configure and manage your credentials.
- [What Commands Are Available in the CLI?](https://docs.shovels.ai/docs/knowledge-base/cli/commands-overview.md): A complete overview of Shovels CLI commands for searching permits, contractors, addresses, and geographic data from your terminal.
- [How Do I Query Properties from the CLI?](https://docs.shovels.ai/docs/knowledge-base/cli/properties.md): Use shovels properties search and shovels properties get to query US properties with their permit history rolled up onto each record, including owner, attribute, and absence filters.
- [How Do I Run Absence Searches in the CLI?](https://docs.shovels.ai/docs/knowledge-base/cli/absence-and-trust.md): Find properties with no permit of a given type using the Shovels CLI, and read the per-row trust object and per-page meta.trust_summaries array that score every absence answer.
- [How Does CLI Output and Pagination Work?](https://docs.shovels.ai/docs/knowledge-base/cli/output-and-pagination.md): The Shovels CLI outputs JSON to stdout with automatic pagination. Learn about response formats, the --limit flag, and credit tracking.
- [What Do CLI Exit Codes and Errors Mean?](https://docs.shovels.ai/docs/knowledge-base/cli/error-codes.md): The Shovels CLI uses structured exit codes and JSON error messages to make troubleshooting straightforward for developers, scripts, and AI agents.
- [How Do I Use the CLI in Scripts and AI Agents?](https://docs.shovels.ai/docs/knowledge-base/cli/scripting-and-agents.md): The Shovels CLI is designed for composability. Learn how to pipe output with jq, build shell scripts, automate with cron, and integrate with AI coding agents.
- [How Shovels Online Works](https://docs.shovels.ai/docs/knowledge-base/shovels-online/how-it-works.md): Learn how to use Shovels Online to search for building permits and contractors anywhere in the USA, including search functionality, permit statuses, and data export options.
- [Search Functionality in Shovels Online](https://docs.shovels.ai/docs/knowledge-base/shovels-online/search-functionality.md): Understand how permit and contractor search work in Shovels Online, including AND logic, keyword search, and the differences between search types.
- [Using Filters in Shovels Online](https://docs.shovels.ai/docs/knowledge-base/shovels-online/filters-and-sorting.md): Learn how to use filters in Shovels Online to refine your permit and contractor searches, and understand current filter behavior.
- [Permit Data Downloads](https://docs.shovels.ai/docs/knowledge-base/shovels-online/permit-downloads.md): Learn what data fields are included in Shovels permit downloads, including permit details, timelines, property characteristics, and geographic information.
- [Contractor Data Downloads](https://docs.shovels.ai/docs/knowledge-base/shovels-online/contractor-downloads.md): Learn what data fields are included in Shovels contractor downloads, including business details, contact information, performance metrics, and licensing status.
- [How Do I Cancel My Shovels Subscription?](https://docs.shovels.ai/docs/knowledge-base/shovels-online/cancel-subscription.md): Cancel your Shovels subscription anytime from Account Settings → Manage Subscription in the Stripe billing portal. Access continues until the end of the billing period; the account then reverts to the free tier.
- [Tracking Multiple Permits at a Property](https://docs.shovels.ai/docs/knowledge-base/data/permits/permit-tracking.md): Learn how Shovels uses a system of unique IDs to track and link multiple permits at the same location, enabling comprehensive property analysis.
- [How Permits Are Tracked Through Their Lifecycle](https://docs.shovels.ai/docs/knowledge-base/data/permits/permit-lifecycle.md): Understand how Shovels tracks individual permits from filing to completion using unique IDs and status updates without creating duplicates.
- [What Do Permit Statuses Mean in Shovels?](https://docs.shovels.ai/docs/knowledge-base/data/permits/permit-statuses.md): Shovels has 4 permit statuses: in_review (filed, awaiting approval), active (approved), final (completed), and inactive (stalled/expired). Learn what each means.
- [Why Some Permits Don't Have Addresses](https://docs.shovels.ai/docs/knowledge-base/data/permits/permits-without-addresses.md): Understand why some permits in Shovels data lack addresses, particularly for new construction on undeveloped land or newly subdivided parcels.
- [Understanding Permit Unique Identifiers](https://docs.shovels.ai/docs/knowledge-base/data/permits/unique-identifiers.md): Learn the difference between Shovels' unique permit ID and the jurisdiction-assigned permit number, and why using the correct identifier matters.
- [Understanding Start and End Dates](https://docs.shovels.ai/docs/knowledge-base/data/permits/start-end-dates.md): Learn how Shovels defines start_date and end_date fields for permits and how they help you understand permit timelines.
- [How to Check Project Completion and Inspection Status](https://docs.shovels.ai/docs/knowledge-base/data/permits/project-completion.md): Learn how to determine if a construction project was completed and passed inspection by checking the permit status in Shovels data.
- [Residential vs Commercial Permit Distribution](https://docs.shovels.ai/docs/knowledge-base/data/permits/permit-distribution.md): Understand the breakdown of residential versus commercial permits in Shovels' data coverage.
- [What are Shovels Decisions?](https://docs.shovels.ai/docs/knowledge-base/data/decisions/overview.md): Shovels Decisions track municipal zoning and land use decisions from city councils and planning boards, giving you earlier visibility into development activity.
- [Decision Categories](https://docs.shovels.ai/docs/knowledge-base/data/decisions/decision-categories.md): Understanding the different types of zoning and land use decisions tracked by Shovels, from spot rezonings to zoning code modifications.
- [Decision Data Fields](https://docs.shovels.ai/docs/knowledge-base/data/decisions/data-fields.md): A complete reference of the Shovels Decisions dataset schema, including metadata, zoning details, property information, and involved parties. This documents the full dataset; the API exposes a subset under different names.
- [From Decision to Permit: The Development Lifecycle](https://docs.shovels.ai/docs/knowledge-base/data/decisions/decision-to-permit.md): How Shovels Decisions connect to permits and contractor data to provide complete visibility into development projects from proposal to completion.
- [Contractor Data Overview](https://docs.shovels.ai/docs/knowledge-base/data/contractors/contractor-data-overview.md): Understand the contractor data available in Shovels, including regional coverage variations and data sources.
- [Assessing Contractor Quality Through Data](https://docs.shovels.ai/docs/knowledge-base/data/contractors/quality-indicators.md): Learn how to use Shovels data metrics to evaluate contractor quality and performance, including permit volume, completion times, and inspection rates.
- [Contractor Contact Information](https://docs.shovels.ai/docs/knowledge-base/data/contractors/contact-information.md): Understand the contractor contact fields in Shovels data, including address information, phone number prioritization, and how contact names relate to emails.
- [Industry Classification Data (NAICS & SIC)](https://docs.shovels.ai/docs/knowledge-base/data/contractors/industry-classification.md): Understand NAICS and SIC industry classification codes in Shovels contractor data, their sources, and limitations.
- [Why Contractor IDs Can Change](https://docs.shovels.ai/docs/knowledge-base/data/contractors/id-changes.md): Understand why contractor IDs may occasionally change as Shovels discovers new permit data, how branch-level assignment works, and how to stay current with the contractor ID changelog.
- [Understanding Shovels Resident Data](https://docs.shovels.ai/docs/knowledge-base/data/residents/resident-data.md): Learn how Shovels assembles and validates resident demographic data, including data sources, available features, and how to access it via API.
- [Understanding the Homeowner Field](https://docs.shovels.ai/docs/knowledge-base/data/residents/homeowner-field.md): Learn how the probabilistic homeowner feature in Shovels resident data is determined and validated through consensus methodology.
- [Latitude and Longitude Data](https://docs.shovels.ai/docs/knowledge-base/data/geographic/coordinates-geocoding.md): Understand how Shovels generates accurate geographic coordinates through our proprietary geocoding process using multiple authoritative data sources.
- [What is a Jurisdiction (AHJ)?](https://docs.shovels.ai/docs/knowledge-base/data/geographic/jurisdictions.md): A jurisdiction is the Authority Having Jurisdiction (AHJ)—typically a city or county government—that issues building permits. The US has ~20,000 AHJs.
- [What Areas Does Shovels Cover?](https://docs.shovels.ai/docs/knowledge-base/data/geographic/coverage-areas.md): Shovels covers ~2,000 US jurisdictions representing ~85% of the US population. Data goes back to 2010+. We add 10-30 new jurisdictions monthly.
- [Where Does Shovels Get Its Data?](https://docs.shovels.ai/docs/knowledge-base/data/quality/data-sources.md): Shovels collects permit data directly from city and county jurisdictions through government relationships, online portals, and public records requests—never from third parties.
- [How Shovels Verifies Data Accuracy](https://docs.shovels.ai/docs/knowledge-base/data/quality/verification-methods.md): Learn about the methods Shovels uses to verify data accuracy, including address standardization and contractor validation.
- [How Often Does Shovels Update Its Data?](https://docs.shovels.ai/docs/knowledge-base/data/quality/refresh-frequency.md): Shovels updates data monthly with 5-10 million new permits and 1-5 million status updates. IDs are generally stable but can occasionally change.
- [Data Labeling and Annotation Process](https://docs.shovels.ai/docs/knowledge-base/data/quality/labeling-process.md): Understand how Shovels ensures high-quality, accurately classified permit data through our rigorous annotation and validation methodology.
- [Historical Data Coverage](https://docs.shovels.ai/docs/knowledge-base/data/quality/historical-data.md): Learn how far back Shovels' historical permit data extends and what affects historical coverage by jurisdiction.
- [Why Am I Getting So Few Results?](https://docs.shovels.ai/docs/knowledge-base/data/quality/few-results.md): Common reasons Shovels searches return fewer results than expected: limited jurisdiction coverage, narrow filters, recent permits not yet indexed, or limited digitization.
- [What is Shovels EDL (Enterprise Data License)?](https://docs.shovels.ai/docs/knowledge-base/edl/overview.md): Shovels EDL delivers complete permit/contractor datasets to Snowflake, BigQuery, or Databricks. Best for bulk analysis with more fields than API.
- [How Monthly EDL Deliveries Work](https://docs.shovels.ai/docs/knowledge-base/edl/monthly-deliveries.md): Understand how Shovels delivers monthly data updates to EDL customers using the overwrite model while maintaining ID consistency.
- [Tracking New vs Modified Records in EDL](https://docs.shovels.ai/docs/knowledge-base/edl/record-tracking.md): Learn how to use first_seen_date and other fields to identify new versus pre-existing records in monthly EDL data deliveries.
- [Contractor Deduplication in EDL](https://docs.shovels.ai/docs/knowledge-base/edl/contractor-deduplication.md): Understand how contractor IDs are deduplicated in Shovels data, including state-level deduplication and contractor group relationships.
- [Understanding the is_representative Field](https://docs.shovels.ai/docs/knowledge-base/edl/is-representative-field.md): Learn how the is_representative field in EDL data identifies the main contractor record within a group of related contractors.
- [Getting Resident Contact Information in EDL](https://docs.shovels.ai/docs/knowledge-base/edl/resident-contact-info.md): Learn how to access resident and homeowner email contact information through Shovels EDL data, including which tables and fields to use.
- [Requesting Manual Reports](https://docs.shovels.ai/docs/knowledge-base/edl/manual-reports.md): Learn how to request custom manual reports from Shovels support when you need specific data beyond standard EDL deliveries.
- [EDL Data Formats and File Sizes](https://docs.shovels.ai/docs/knowledge-base/edl/data-formats.md): Learn about the available data formats and typical file sizes for Shovels Enterprise Data License deliveries.
- [Requesting Sample Records](https://docs.shovels.ai/docs/knowledge-base/edl/sample-records.md): Learn how to request sample records from Shovels to verify that our data fits your specific use case before committing to a subscription.
- [Shovels Contact Information](https://docs.shovels.ai/docs/knowledge-base/company/contact-information.md): Find Shovels' official contact information including mailing address, support email, and sales contacts.
- [How Property Types Are Categorized](https://docs.shovels.ai/docs/knowledge-base/company/property-types.md): Understand how Shovels categorizes property types in permit data using tax assessor records.
- [What Is Shovels' Refund Policy?](https://docs.shovels.ai/docs/knowledge-base/company/refund-policy.md): Shovels reviews refund requests case-by-case. Email support@shovels.ai within 30 days of the charge with your account email, charge details, and reason. Approved refunds appear within 5–10 business days.
- [What Can and Can't I Do With Shovels Data?](https://docs.shovels.ai/docs/knowledge-base/company/data-usage-terms.md): Shovels data is licensed for internal business use: research, prospecting, lead generation, and product integration. Uploading to ad platforms, reselling, or sharing externally is not permitted.

## OpenAPI Specs

- [openapi.production](https://api.shovels.ai/spec/v2/openapi.production.yaml)
- [openapi-from-anchor-url-0](https://docs.shovels.ai/openapi-from-anchor-url-0)
- [openapi](https://docs.shovels.ai/api-reference/openapi.json)

## Optional

- [Data Dictionary](https://www.shovels.ai/data-dictionary)
- [Coverage Dashboard](https://www.shovels.ai/coverage)
- [Community](https://discord.gg/Nypja3cKDx)
- [Blog](https://www.shovels.ai/blog/)