The Shovels REST API makes it easy for technology developers in the property, climate, and construction industries to access detailed information about building permits, contractors and construction activity. Our API is designed to be intuitive and fast. We look forward to seeing what you build with it: let us know and we’ll check it out!

​
Key Features

The API offers access to two primary objects: Permits and Contractors.
  • Permits: Official documents issued by city or county authorities required before commencing construction or alterations to a building.
  • Contractors: Skilled professionals in the building trades who undertake permitted construction projects on various properties.
And some additional resources:
  • Lists: Endpoints for predefined values like tags and property types for query parameters.
  • Addresses: Endpoint for searching and resolving valid US addresses.
  • Meta: Endpoints for metadata about the API and the data behind it.

​
Use Cases

The use cases are endless, but the most common we see today are:
  • Sales and Marketing: Generate lead lists with precision, at scale.
  • Development: Build direct product integrations to bring Shovels data into your own applications.
  • Market Research: Programmatically return and export Shovels data into your own tools, dashboards, and reports.

​
Getting Started

To begin using the API, please contact our sales team at sales@shovels.ai or grab a free API key.
The free API key has a limited number of calls. If you hit the limit and need more, please reach out to sales@shovels.ai or call us at 1-800-511-7457.

​
API Key

For any API request, you’ll need to include your API key. This is available in your Profile Settings > API Key.

​
API Free Trial

We want you to be able to adequately test our API before making your decision. Completely separate from the Shovels Online web app trial, there is a free trial of the API key as well. API Key free trials include 1000 requests with no time limit or credit card required. If you exceed 1000 request and still need more, please reach out to Sales for an extension.

​
Authentication

Authentication is required for any API request that you make, whether it’s in the API Playground or in your own scripts. Our API uses a straightforward header-based authentication method: X-API-Key: YOUR_API_KEY_HERE. Here’s an example request: 
curl -X GET "https://api.shovels.ai/v2/meta/release" \
 -H "X-API-Key: YOUR_API_KEY_HERE"
If you have any issues with your API key, rate limits, or other authentication issues, please reach out to Support.

​
Acceptable Use Policy

We do not enforce any usage or rate limits at this time, but we expect that you will respect our platform and avoid frivolous requests. However, we are constantly monitoring usage and will enforce rate limits on an individual basis as needed. If you feel that you’re API key is rate limited, please reach out to Support for clarification.

​
API Details

​
Quick Overview

A few quick details about our API:
TypeDescription
SSL OnlyWe require that all requests be made over SSL.
UTF-8 EncodingWe use UTF-8 encoding for all requests and responses.
MethodHTTP GET for all read calls.
Date FormatAll dates in the API are strings in the format: YYYY-MM-DD.

​
Response Types

The API supports the following response codes:
CodeDescription
200 OKEverything worked as expected.
400 Bad RequestThere was something wrong with your request. Double-check your input.
401 UnauthorizedYou need to log in to access this. Make sure your API key is correct.
402 Payment RequiredYou will get this error if your reach your trial API call limit.
403 ForbiddenYou don’t have permission to access this.
404 Not FoundWe couldn’t find what you’re looking for. Check the URL or resource ID.
422 Unprocessable EntityThere’s an issue with the data you sent. Check Error Handling if you get this error.
429 Too Many RequestsYou’re sending requests too quickly. Slow down and try again later.
500 Internal Server ErrorYikes, something went wrong on our end. Please let us know at support@shovels.ai

​
Data Format

The API returns data in JSON format, either as pages or single objects. Paginated responses have the following structure: 
{
 "items": [...],
 "page": 1,
 "size": 50,
 "next_page": 2 | null
}
Where objects are returned as an array in the ‘items’ field.

​
Pagination

The API supports two types of pagination: Cursor-based pagination is the default and recommended method for paginating through results. It uses an opaque cursor token to maintain your position in the result set, offering better performance, consistency, and stability, especially for large datasets. 
{
 "items": [...],
 "size": 50,
 "next_cursor": "eyJkYXR.lIjoiMjA.yMy0",
 "pagination_type": "cursor"
}
To use cursor-based pagination:
  • For the first page: Simply make a request without any pagination parameters
  • For subsequent pages: Include the next_cursor value from the previous response using the cursor parameter
Example: 
GET /v2/permits/search?size=10
GET /v2/permits/search?size=10&cursor=eyJkYXR.lIjoiMjA.yMy0
When there are no more results, the next_cursor value will be null.

​
2. Offset-Based Pagination (Deprecated)

⚠️ IMPORTANT: Offset-based pagination is deprecated and will be removed in a future release. We recommend migrating to cursor-based pagination for better performance and reliability. This traditional pagination method uses page numbers and is less efficient: 
{
 "items": [...],
 "page": 1,
 "size": 50,
 "next_page": 2,
 "pagination_type": "offset"
}
To use offset-based pagination, explicitly provide a page parameter in your request: 
GET /v2/permits/search?page=1&size=50

​
Pagination Priority

If both cursor and page parameters are provided in the same request, cursor-based pagination takes precedence.

​
Versioning

The current version of the API is v2, which is reflected in the endpoints URL structure: /v2/. We plan to evolve our API by releasing new versions to ensure backward compatibility while maintaining a steady pace of continuous improvements.

​
API Reference

If you’re looking for the Shovels API Reference, then you’re in the right place. The API Reference tab in this documentation hub outlines all of our endpoints, parameters, requirements, and responses. Additionally, there are examples of both requests and responses to help you get started.

​
Using the Shovels API Playground

The easiest way to get started with the Shovels API is to use the API Playground. This is a web-based tool that allows you to test out the API without having to write any code.

​
Authentication

In order to use the playground, you’ll need to authenticate with your API key. Enter your API Key in the “Authentication” drop down (as shown below), and proceed to the next step. API Playground Authentication
If you have forgotten your API key, or need one in the first place, this is available in your Profile Settings > API Key.

​
Server

Ensure that the “Server” drop down is set to api.shovels.ai/v2.

​
Required fields

Different endpoints will have different required fields. Select the “Query” dropdown to see all available fields. Required fields are indicated with a red asterisk (as shown below). API Playground Required Fields Generally speaking, the required fields are the start and end dates for the query, and the corresponding geo_id to point the query to the right place. If the query is for a specific object, like an individual permit, address, or contractor, then you’ll only need the corresponding id field.

​
Parameters

In order to fine-tune your query results, you can add parameters to the request. A full list of the parameters available (with definitions) for each endpoint can be found in the “Query Parameters” section, beneath the “Query Dropdown” (as shown below). API Playground Query Parameters

​
Tips and Tricks

Using a REST API is generally the same everywhere, but here are a few things that may help you with our Shovels API specifically.

​
Use Optional Parameters

Permit data goes deep, and our data-cleaning allows you to go even deeper. Read through all the options in the “Query Parameters” and see if there are any that will help narrow down your query. Not every parameter will have complete fill rates (as in, that field may be null), but it’s best to take a bottom-up approach of creating as fine and detailed a query as possible, with all the extra data points you could be interested in. If that specific query doesn’t return the results you need, in either quality or quantity, then you can slowly whittle away at these extra parameters until you get what you need.

​
Break Down Your Queries

Our endpoints are answers to straightforward questions, and sometimes the query you may want to build isn’t possible with a single endpoint. In such cases, a sequential approach of chaining endpoint queries together can be effective. In others, where the required field is a value, like a specific contractor_id or address_id, then it’s mandatory to first retrieve the foundational data point before getting the insights for it. An example of this can be found in our Tutorial section.

​
Use the API Request Examples

If you’re new to using REST APIs, or even if you’re a seasoned veteran, it can be helpful to see an example of the exact syntax and formatting of the request, to give you the piece of mind that it’s formatted correctly. To the right of each endpoint in our API Playground there is a request example in a variety of languages. These will either give you a good starting point for building your own request, or can be directly copy and pasted in simple use cases.

​
Error Handling

Proper error messages and HTTP codes are provided to help you troubleshoot issues effectively. Refer to the Response Types section for an overview of HTTP error codes and how to handle them. Below we describe how to interpret HTTP 422 code.

​
422 Unprocessable Entity

A 422 Unprocessable Entity response occurs when the server understands the request but cannot process it due to invalid data. This helps you identify issues with your input. The response includes:
  • loc: The location of the error. The first value indicates the location and the second specifies the problematic field. Common values for the first value include:
    • body: The error is in the request body.
    • query: The error is in the query parameters.
    • path: The error is in the URL path.
    • header: The error is in the request headers.
  • msg: A message describing the error.
  • type: The type of error.
Here are some examples: 
{
    "loc": ["body", "start_date"],
    "msg": "Field required",
    "type": "value_error.missing"
}
If these examples don’t help, please reach out to Support for assistance.

​
Troubleshooting

We will outline below a few of the main methodologies for analyzing what happened to a REST API request, and what to do from there.

​
Missing Data and Empty Fields

A common thought after receiving a 404 error is to wonder if the query itself was incorrect, or somehow misconfigured. While that may be the case, it’s also important to consider that there may be no data available at this time. We talk about this in much more detail under the Shovels Foundations section, but to be succinct: there are many complications in obtaining complete and total permit data, from variability in digitization practices to required permit fields in individual jurisdictions. While we do our best, we aren’t there yet. If you find that we’re missing key data for your needs, please reach out to Support and we’ll confirm for you whether we have it or not, and if not, add it to our roadmap to get it soon.

​
Release Notes

Another possibility, especially for existing queries that failed, are that the endpoints and data structure may have changed. Any such changes are documented in our Release Notes. Please note that such breaking changes are exceedingly rare, and we do our best to minimize them wherever possible. If you need any assistance, or notice that existing queries are suddenly failing, please reach out to Support for assistance. If you have any questions, please don’t hesitate to reach out to Support.