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

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

Get City Current 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 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.

Field Name	Data Type	Description	Example	Source
property_census_tract	`string`	The property’s census tract	”06075000100”
property_congressional_district	`string`	The property’s congressional district	”11”	Shovels
property_type	`string`	The property’s type	”Residential”	Shovels
property_type_detail	`string`	The property’s sub-classification	”Single Family Home”	Shovels
property_legal_owner	`string`	The property’s legal owner	”Robert Johnson”	Shovels
property_owner_type	`string`	The property’s owner classification	”individual”	Shovels
property_lot_size	`integer`	The property’s lot size (in square feet)	“5000”	Shovels
property_building_area	`integer`	The property’s building area (in square feet)	“1250”	Shovels
property_story_count	`integer`	The property’s number of stories	”2”	Shovels
property_unit_count	`integer`	The property’s number of units	”1”	Shovels
property_year_built	`integer`	The property’s year built	”1978”	Shovels
id	`string`	The Shovels ID for the permit	”caf3b9d5ce317d53”	Shovels
description	`string`	The description of the work from the permit	”Solar panel installation”	Permit Jurisdiction
number	`string`	The permit jurisdiction’s internal tracking number	”No-15837”	Permit Jurisdiction
jurisdiction	`string`	The jurisdiction that issued the permit	”City of Oakland”	Permit Jurisdiction
job_value

Shovels Online

Shovels API

Tutorials

Troubleshooting

Platform Reference

Shovels Foundations

API