Return city details and related location hierarchy.

Get City Details

Location

Message

Error Type

ValidationError

APIKeyHeader

City details and related location hierarchy.

CitiesDetailsRead

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. This endpoint supports both pagination styles:

1. **Cursor-based pagination (default)**: Used when no pagination parameters are provided or when `cursor` parameter is specified. This provides better performance for large datasets.

2. **Offset-based pagination**: Used when `page` parameter is explicitly provided (and no cursor). If both cursor and page are provided, cursor pagination takes precedence.

Search Permits

Returns a list of permits records for given IDs. This endpoint supports both pagination styles:

1. **Cursor-based pagination (default)**: Used when no pagination parameters are provided or when `cursor` parameter is specified. This provides better performance for large datasets.

2. **Offset-based pagination**: Used when `page` parameter is explicitly provided (and no cursor). If both cursor and page are provided, cursor pagination takes precedence.

Get Permits By Id

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. **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. This endpoint supports both pagination styles:

1. **Cursor-based pagination (default)**: Used when no pagination parameters are provided or when `cursor` parameter is specified. This provides better performance for large datasets.

2. **Offset-based pagination**: Used when `page` parameter is explicitly provided (and no cursor). If both cursor and page are provided, cursor pagination takes precedence.

Get Residents

Searches for cities based on the provided search term.

Search Cities

Get City Monthly Metrics

Get City Current Metrics

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 Jurisdictions

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 general announcements, 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.

Retrieving Permit History for an Address

Overview

The complete list of fields and filters available in **Shovels Online**.

Online

All fields, parameters, and objects available in the **Shovels API** schema.

The exhaustive list of all fields in the Shovels platform, sorted by table.

Permits

Contractors

Addresses

Cities

Counties

Jurisdictions

Zipcodes

States

Meta

Lists

Get City Details

Authorizations

Query Parameters

Response