Data Dictionary

Coverage Dashboard

Community

Blog

Shovels Documentation

API Reference

Release Notes

Free Trial

Contact Support

Return city details and related location hierarchy.

Get City Details

Location

Message

Error Type

ValidationError

APIKeyHeader

CitiesDetailsRead

HTTPValidationError

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

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

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

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

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 Metrics

Return residents for a given address geo ID.

Get Residents

Searches for cities based on the provided search term.

Search Cities

Get City Metrics

Searches for counties based on the provided search term.

Search Counties

Get County Metrics

Return county details and related location hierarchy.

Get County Details

Searches for jurisdictions based on the provided search term.

Search Jurisditions

Get Jurisdiction 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.

Permits

Contractors

Addresses

Cities

Counties

Jurisdictions

Zipcodes

States

Meta

Lists

Get City Details

Authorizations

Query Parameters

Response