Get City Current Metrics

Average duration of permit approval process in days

Avg Approval Duration

Average duration of construction projects in days

Avg Construction Duration

Avg Inspection Pass Rate

Contractor Count

Geo Id

Permit Active Count

Permit Count

Permit In Review Count

Type of property (e.g., residential, commercial)

Property Type

Total value of all jobs/permits in the city

Total Job Value

CitiesMetricsCurrentRead

Location

Message

Error Type

ValidationError

APIKeyHeader

Schema for City Metrics in list response.

PaginatedCitiesMetricsCurrent

HTTPValidationError

Shovels Documentation

The Home of Construction Intelligence, built for developers *and* developers.

Welcome to Shovels.ai

This guide will help you get started with Shovels Online, the web-based application for exploring the Shovels dataset.

Quickstart Guide

Learn how to use the Shovels API to programmatically access permit, contractor, and regional insights.

Introducing the Shovels API

Frequently asked questions about the Shovels platform.

Common issues and how to fix them when using Shovels Online.

Shovels Online Troubleshooting

Common issues and how to fix them when using the Shovels API.

Shovels API Troubleshooting

Understanding the key data components that make up the Shovels platform.

Building Blocks

Gain insights into how the Shovels team approaches the data in our platform.

Data Philosophy

Introduction to US permit availability and variation across 20k+ jurisdictions.

Permit Availability

Returns a list of matching permits records. Permits should meet ALL of the parameter filters. Multiple parameters are treated as AND queries.

Search Permits

Returns a list of permits records for given IDs.

Get Permits By Id

Returns contractors doing work within the given location area filtered by type of work, permit keywords, etc.. Contractors must meet all specified parameters, with multiple parameters treated as AND queries. **NOTE:** Contractors are ordered by the start date of the most recent permit on which they worked.

Search Contractors

Returns contractors by their IDs. Multiple `id` query parameters can be provided in the same API call

Get Contractors By Id

Retrieves all permits associated with a single contractor.

Get Permits By Contractor Id

Returns contractor monthly metrics filtered by contractor ID, property type, and tags. Metrics include permit count, average duration, and average pass rate.

Get Filtered Metrics By Contractor Id

Returns a paginated list of employees for a specific contractor.

List Contractor Employees

Searches for addresses that have at least one associated permit based on the provided text.

Search Addresses

Get Address Monthly Metrics

Get Address Current Metrics

Return residents for a given address geo ID.

Get Residents

Searches for cities based on the provided search term.

Search Cities

Get City Monthly Metrics

Return city details and related location hierarchy.

Get City Details

Searches for counties based on the provided search term.

Search Counties

Get County Monthly Metrics

Get County Current Metrics

Return county details and related location hierarchy.

Get County Details

Searches for jurisdictions based on the provided search term.

Search Jurisditions

Get Jurisdiction Monthly Metrics

Get Jurisdiction Current Metrics

Return jurisdiction details and related location hierarchy.

Get Jurisdiction Details

Searches for zipcodes based on the provided search term.

Search Zipcodes

Searches for US states based on the provided search term.

Search States

Returns the release date of the current data served by the API.

Get Data Release Date

Returns all available ZIP codes for which we have permit and contractor data.

Get All Available Zip Codes

Get All Available Tags

Find out what the Engineering team has been up to across our entire platform, including updates and bugfixes.

Release Notes

Data Dictionary

Coverage Dashboard

Community

Blog

API Reference

Free Trial

Contact Support

This tutorial will help you build an accurate search query in Shovels Online to find Contractors.

Building an Accurate Contractor Search

This tutorial will show you how to use the Shovels API to retrieve permit history for an address.

Permits

Contractors

Addresses

Cities

Counties

Jurisdictions

Zipcodes

States

Meta

Lists

Get City Current Metrics

Authorizations

Path Parameters

Query Parameters

Response