Download OpenAPI specification:Download
The Shovels REST API makes it easy for real estate and climate technology developers to access detailed information about building contractors and building activity. Our API is designed to be intuitive and fast. We look forward to seeing what you build with it!
The API offers access to two primary objects: Permits and Contractors.
And some additional resources:
To begin using the API, please contact our sales team at sales@shovels.ai or grab a free API key.
Info: 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.
Our API uses a straightforward header-based authentication method:
X-API-Key: YOUR_API_KEY_HERE
Example Request:
curl -X GET "https://api.shovels.ai/v1/list/zip" \
-H "X-API-Key: YOUR_API_KEY_HERE"
A few quick details about our API:
Type | Description |
---|---|
SSL only | We require that all requests are done over SSL. |
UTF-8 encoding | We use UTF-8 everywhere. |
Method | GET for all read calls. |
Date format | All dates in the API are strings in the following format: YYYY-MM-DD. |
The API supports the following response codes:
Code | Description |
---|---|
200 OK | Everything worked as expected. |
400 Bad Request | There was something wrong with your request. Double-check your input. |
401 Unauthorized | You need to log in to access this. Make sure your API key is correct. |
402 Payment Required | You will get this error if your reach your trial API call limit. |
403 Forbidden | You don't have permission to access this. |
404 Not Found | We couldn't find what you're looking for. Check the URL or resource ID. |
422 Unprocessable Entity | There's an issue with the data you sent. Check Error Handling if you get this error. |
429 Too Many Requests | You're sending requests too quickly. Slow down and try again later. |
500 Internal Server Error | Yikes, something went wrong on our end. Please let us know at support@shovels.ai |
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.
The current version of the API is v1, which is reflected in the endpoints URL structure:
/v1/
. We plan to evolve our API by releasing new versions to ensure backward compatibility while
maintaining a steady pace of continuous improvements.
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.
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:
This information helps you correct your request by pinpointing the exact issue. Here are some examples:
Request Body Error
{
"detail": [
{
"loc": ["body", "first_name"],
"msg": "Field is required",
"type": "value_error.missing"
}
]
}
Query Parameter Error
{
"detail": [
{
"loc": ["query", "page"],
"msg": "Page must be a positive integer",
"type": "type_error.integer"
}
]
}
Path Parameter Error
{
"detail": [
{
"loc": ["path", "id"],
"msg": "Invalid ID format",
"type": "value_error.id"
}
]
}
Header Error
{
"detail": [
{
"loc": ["header", "X-API-Key"],
"msg": "API key is missing",
"type": "value_error.missing"
}
]
}
These examples show how different types of errors are reported, helping you to diagnose and fix issues in your API requests.
Predefined lists of values and categories, such as zip codes and tags, which can be utilized as query parameters in other API interactions.
Returns all available ZIP codes for which we have permit and contractor data.
A list of available ZIP codes
Validation Error
{- "items": [
- {
- "zip_code": "90001",
- "zip_code_exts": [
- "1234",
- "1235"
]
}, - {
- "zip_code": "90002",
- "zip_code_exts": [
- "1235",
- "1236"
]
}, - {
- "zip_code": "90003",
- "zip_code_exts": [
- "1236",
- "1237"
]
}, - {
- "zip_code": "90004",
- "zip_code_exts": [
- "1237",
- "1238"
]
}, - {
- "zip_code": "90005",
- "zip_code_exts": [
- "1334",
- "1335"
]
}, - {
- "zip_code": "90006",
- "zip_code_exts": [
- "1434",
- "1435"
]
}, - {
- "zip_code": "90007",
- "zip_code_exts": [
- "1534",
- "1535"
]
}, - {
- "zip_code": "90008",
- "zip_code_exts": [
- "1634",
- "1635"
]
}, - {
- "zip_code": "90009",
- "zip_code_exts": [
- "1734",
- "1735"
]
}, - {
- "zip_code": "90010",
- "zip_code_exts": [
- "1834",
- "1835"
]
}
], - "page": 1,
- "size": 50,
- "next_page": 2
}
US addresses and geographic information, such as zip codes, which can be used as query parameters in other API interactions.
Searches for addresses that have at least one associated permit based on the provided text.
A list of addresses that match the search text, ordered by relevance and in USPS notation.
The specified search query didn't match any addresses
Validation Error
{- "items": [
- {
- "street_no": "1232",
- "street": "MARKET ST",
- "city": "SAN FRANCISCO",
- "zip_code": "94103",
- "zip_code_ext": "1234",
- "state": "CA"
}, - {
- "street_no": "1233",
- "street": "MARKET ST",
- "city": "SAN FRANCISCO",
- "zip_code": "94103",
- "zip_code_ext": "1234",
- "state": "CA"
}, - {
- "street_no": "1234",
- "street": "MARKET ST",
- "city": "SAN FRANCISCO",
- "zip_code": "94103",
- "zip_code_ext": "1234",
- "state": "CA"
}
], - "page": 1,
- "size": 5
}
Returns contractors working within a defined radius of a given address, optionally filtered by type of work. Contractors must meet all specified parameters, with multiple parameters treated as AND queries. NOTE: Contractors are ordered by the file date of the most recent permit on which they worked.
A list of contractor IDs with additional information
At least one of the 'zip_code' or 'city' parameters must be provided
The specified address could not be found
Validation Error
{- "items": [
- {
- "id": "KOm4dMLIuR",
- "license": "12345",
- "name": "SYNERGY POWER",
- "business_name": "SYNERGY POWER"
}, - {
- "id": "ram3dYLIuR",
- "license": "12345",
- "name": "GUINEY JAMES D AND CO",
- "business_name": "JAMES D GUINEY & CO"
}, - {
- "id": "eaa4drLIu1",
- "license": "1022026",
- "name": "DAVID LARA",
- "business_name": "LIFETIME ROOFING SERVICE INC."
}, - {
- "id": "F0NXMva0HD",
- "license": "1070019",
- "name": "TOTAL PLUMBING SERVICES",
- "business_name": "TOTAL PLUMBING SERVICES"
}
], - "page": 1,
- "size": 50
}
Returns contractors doing work within the given city optionally filtered by type of work. Contractors must meet all specified parameters, with multiple parameters treated as AND queries. NOTE: Contractors are ordered by the file date of the most recent permit on which they worked.
A list of contractor IDs with additional information
Validation Error
{- "items": [
- {
- "id": "KOm4dMLIuR",
- "license": "12345",
- "name": "SYNERGY POWER",
- "business_name": "SYNERGY POWER"
}, - {
- "id": "ram3dYLIuR",
- "license": "12345",
- "name": "GUINEY JAMES D AND CO",
- "business_name": "JAMES D GUINEY & CO"
}, - {
- "id": "eaa4drLIu1",
- "license": "1022026",
- "name": "DAVID LARA",
- "business_name": "LIFETIME ROOFING SERVICE INC."
}, - {
- "id": "F0NXMva0HD",
- "license": "1070019",
- "name": "TOTAL PLUMBING SERVICES",
- "business_name": "TOTAL PLUMBING SERVICES"
}
], - "page": 1,
- "size": 50
}
Returns contractors doing work within a given ZIP code optionally filtered by type of work. Contractors must meet all specified parameters, with multiple parameters treated as AND queries. NOTE: Contractors are ordered by the file date of the most recent permit on which they worked.
A list of contractor IDs with additional information
Validation Error
{- "items": [
- {
- "id": "KOm4dMLIuR",
- "license": "12345",
- "name": "SYNERGY POWER",
- "business_name": "SYNERGY POWER"
}, - {
- "id": "ram3dYLIuR",
- "license": "12345",
- "name": "GUINEY JAMES D AND CO",
- "business_name": "JAMES D GUINEY & CO"
}, - {
- "id": "eaa4drLIu1",
- "license": "1022026",
- "name": "DAVID LARA",
- "business_name": "LIFETIME ROOFING SERVICE INC."
}, - {
- "id": "F0NXMva0HD",
- "license": "1070019",
- "name": "TOTAL PLUMBING SERVICES",
- "business_name": "TOTAL PLUMBING SERVICES"
}
], - "page": 1,
- "size": 50
}
Returns contractors by their company name, optionally filtered by type of work. Returns contractors that meet all specified parameters. Multiple parameters are treated as AND queries.
A list of contractor IDs and their business names
Validation Error
{- "items": [
- {
- "id": "ram3dYLIuR",
- "license": "12345",
- "name": "GUINEY JAMES D AND CO",
- "business_name": "JAMES D GUINEY & CO"
}, - {
- "id": "eaa4drLIu1",
- "license": "1022026",
- "name": "DAVID LARA",
- "business_name": "LIFETIME ROOFING SERVICE INC."
}, - {
- "id": "F0NXMva0HD",
- "license": "1070019",
- "name": "TOTAL PLUMBING SERVICES",
- "business_name": "TOTAL PLUMBING SERVICES"
}
], - "page": 1,
- "size": 50
}
Returns contractors by their business license and state.
A list of contractor business entities under the same license
The contractor with the given license and state was not found.
Validation Error
{- "items": [
- {
- "id": "ram3dYLIuR",
- "license": "12345",
- "name": "GUINEY JAMES D AND CO",
- "business_name": "JAMES D GUINEY & CO"
}, - {
- "id": "eaa4drLIu1",
- "license": "1022026",
- "name": "DAVID LARA",
- "business_name": "LIFETIME ROOFING SERVICE INC."
}, - {
- "id": "F0NXMva0HD",
- "license": "1070019",
- "name": "TOTAL PLUMBING SERVICES",
- "business_name": "TOTAL PLUMBING SERVICES"
}
], - "page": 1,
- "size": 50
}
Returns contractors with a business address in a given ZIP code optionally filtered by type of work. Returns contractors meeting ALL of the parameter filters. Multiple parameters are treated as AND queries.
A list of contractor IDs and their business names.
Validation Error
{- "items": [
- {
- "id": "ram3dYLIuR",
- "license": "12345",
- "name": "GUINEY JAMES D AND CO",
- "business_name": "JAMES D GUINEY & CO"
}, - {
- "id": "eaa4drLIu1",
- "license": "1022026",
- "name": "DAVID LARA",
- "business_name": "LIFETIME ROOFING SERVICE INC."
}, - {
- "id": "F0NXMva0HD",
- "license": "1070019",
- "name": "TOTAL PLUMBING SERVICES",
- "business_name": "TOTAL PLUMBING SERVICES"
}
], - "page": 1,
- "size": 50
}
Returns the contractor identified by the given ID.
The detailed record of the requested contractor
The requested contractor ID was not found
Validation Error
{- "id": "e79c3393ad",
- "license": "961870",
- "name": "CA SUNRISE CONSTRUCTION SOLUTION INC.",
- "business_name": "CA SUNRISE CONSTRUCTION SOLUTION INC.",
- "street_no": "2800",
- "street": "COTTONWOOD DR",
- "city": "SAN BRUNO",
- "zip_code": "94066",
- "state": "CA",
- "latlng": [
- 37.37619,
- -121.869064
], - "business_type": "Corporation",
- "classification": "CFC",
- "primary_phone": "(425) 507-4300",
- "primary_email": "atobar.casunrise@gmail.com",
- "phone": "(425) 507-4300,(425) 241-7407,(425) 270-9678,(425) 281-6152",
- "email": "atobar.casunrise@gmail.com,david@calsunrise.com",
- "status_tally": {
- "final": 754,
- "active": 81,
- "unknown": 2,
- "inactive": 313
}, - "tag_tally": {
- "hvac": 27,
- "solar": 39,
- "reroof": 1,
- "pool_spa": 1,
- "heat_pump": 267,
- "utilities": 1110,
- "commercial": 20
}
}
Retrieves all permits associated with a single contractor.
A list of permits associated with the contractor and grouped by address
The requested contractor ID was not found
Validation Error
{- "items": [
- {
- "permits": [
- "838d8ec643a3d117",
- "c9ed877ca95aa1ca",
- "1bc94405319a4ba4",
- "ffdbadd3d19f2423",
- "260eb0baa8e1267d",
- "063ffbeb8d8d9442"
], - "address": {
- "street_no": "991",
- "street": "DIONNE WAY",
- "city": "SAN JOSE",
- "zip_code": "95133-1163",
- "state": "CA"
}
}, - {
- "permits": [
- "c713c4cd90040b45"
], - "address": {
- "street_no": "154",
- "street": "FRISBIE ST",
- "city": "OAKLAND",
- "zip_code": "94611",
- "state": "CA"
}
}
], - "page": 1,
- "size": 2
}
Returns contractor overall and historical work metrics. Work metrics are calculated by summing up the duration and inspection pass rate of each permit. Historical metrics are calculated on a monthly basis.
The contractor work metrics
The requested contractor ID was not found
Validation Error
{- "id": "e79c3393ad",
- "license": "961870",
- "name": "CA SUNRISE CONSTRUCTION SOLUTION INC.",
- "business_name": "CA SUNRISE CONSTRUCTION SOLUTION INC.",
- "street_no": "2800",
- "street": "COTTONWOOD DR",
- "city": "SAN BRUNO",
- "zip_code": "94066",
- "state": "CA",
- "business_type": "Corporation",
- "primary_phone": "(425) 507-4300,(425)",
- "primary_email": "atobar.casunrise@gmail.com",
- "phone": "(425) 507-4300,(425) 241-7407,(425) 270-9678,(425) 281-6152",
- "email": "atobar.casunrise@gmail.com,david@calsunrise.com",
- "avg_duration_days": 120.4,
- "avg_pass_rt": 0.51,
- "count": 21,
- "permit_history": [
- {
- "avg_duration_days": 71,
- "avg_pass_rt": 0.78,
- "count": 5,
- "date": "2023-03-01"
}, - {
- "avg_duration_days": 104,
- "avg_pass_rt": 0.33,
- "count": 2,
- "date": "2023-02-01"
}, - {
- "avg_duration_days": 120,
- "avg_pass_rt": 0.51,
- "count": 1,
- "date": "2023-01-01"
}
]
}
Official documents issued by cities or counties before construction or alteration of a building can begin.
Returns permits that include a given search term in their description. Permits should meet ALL of the parameter filters. Multiple parameters are treated as AND queries.
A list of permit IDs with corresponding descriptions.
The 'state' parameter is required when the 'city' parameter is specified
Validation Error
{- "items": [
- {
- "id": "4625cd3ed73c7e33",
- "description": "Gpi for (n) 7' x 12' endless wave pool and 4' wall"
}, - {
- "id": "89403309315ea7fc",
- "description": "Rida hotel & convention center project - building 8, wave pool mechanical building & parcel h-3"
}, - {
- "id": "e36acba1064bd3d1",
- "description": "Rida foundation only project - building 8 - wave pool mech bldg foundation, parcel h-3"
}, - {
- "id": "2898cb200832d45b",
- "description": "Sprink - undgd legoland water park expansion to wave pool_add new underground piping to wave mechanical bldg fro fire sprinkler system."
}
], - "page": 1,
- "size": 5
}
Returns permits associated with a given address. Returns permits meeting ALL of the parameter filters. Multiple parameters are treated as AND queries. NOTE: Returned records are sorted by the file_date
field.
A list of permit IDs
At least one of the 'zip_code' or 'city' parameters must be provided
The address was not found OR we don't have permit coverage in the area.
Validation Error
{- "items": [
- "838d8ec643a3d117",
- "9bfc5f1aa30de4e8",
- "4854304c593cc4b8"
], - "page": 1,
- "size": 3
}
Returns permits with activity in one or more United States ZIP codes. Returns permits meeting ALL of the parameter filters. Multiple parameters are treated as AND queries. NOTE: Returned records are sorted by the file_date
field.
A list of permit IDs
Validation Error
{- "items": [
- {
- "id": "838d8ec643a3d117",
- "address": {
- "street_no": "9540",
- "street": "W BROADVIEW DR",
- "city": "BAY HARBOR ISLANDS",
- "zip_code": "33154-1926",
- "state": "FL",
- "latlng": [
- 25.886079788208008,
- -80.1387939453125
]
}
}, - {
- "id": "6a7a26a3f1249a78",
- "address": {
- "street_no": "1150",
- "street": "101ST ST",
- "city": "BAY HARBOR ISLANDS",
- "zip_code": "33154-1926",
- "state": "FL",
- "latlng": [
- 25.891536712646484,
- -80.13243865966797
]
}
}, - {
- "id": "9554114fa7ec82fe",
- "address": {
- "street_no": "1000",
- "street": "KANE CONC",
- "city": "BAY HARBOR ISLANDS",
- "zip_code": "33154-2107",
- "state": "FL",
- "latlng": [
- 25.88628578186035,
- -80.12944030761719
]
}
}
], - "page": 1,
- "size": 3
}
Returns permits with activity in one or more United States states. Returns permits meeting ALL of the parameter filters. Multiple parameters are treated as AND queries. NOTE: For this endpoint records are not sorted by any date field.
A list of permit IDs.
Validation Error
{- "items": [
- {
- "id": "838d8ec643a3d117",
- "address": {
- "street_no": "9540",
- "street": "W BROADVIEW DR",
- "city": "BAY HARBOR ISLANDS",
- "zip_code": "33154-1926",
- "state": "FL",
- "latlng": [
- 25.886079788208008,
- -80.1387939453125
]
}
}, - {
- "id": "6a7a26a3f1249a78",
- "address": {
- "street_no": "1150",
- "street": "101ST ST",
- "city": "BAY HARBOR ISLANDS",
- "zip_code": "33154-1926",
- "state": "FL",
- "latlng": [
- 25.891536712646484,
- -80.13243865966797
]
}
}, - {
- "id": "9554114fa7ec82fe",
- "address": {
- "street_no": "1000",
- "street": "KANE CONC",
- "city": "BAY HARBOR ISLANDS",
- "zip_code": "33154-2107",
- "state": "FL",
- "latlng": [
- 25.88628578186035,
- -80.12944030761719
]
}
}
], - "page": 1,
- "size": 3
}
Returns the requested permit details by ID.
The permit details record
The requested permit ID was not found
Validation Error
{- "id": "71c02bd70f7ce1c9",
- "description": "Service panel replacement 200 amp like for like",
- "number": "B2022-04886",
- "jurisdiction": "Berkeley",
- "job_value": "5000.0",
- "type": "Permit",
- "subtype": "Building permit record created from esr-2022-02371",
- "status": "Final",
- "file_date": "2022-10-19",
- "issue_date": "2023-01-18",
- "final_date": "2023-05-17",
- "start_date": "2022-10-19",
- "end_date": "2023-05-17",
- "total_duration": 230,
- "construction_duration": 121,
- "approval_duration": 109,
- "inspections_pass_rate": 0.33,
- "contractor_id": "48d93f3020c4",
- "address": {
- "street_no": "2435",
- "street": "CALIFORNIA ST",
- "city": "BERKELEY",
- "zip_code": "94703",
- "state": "CA",
- "latlng": [
- 37.86321,
- -122.278625
]
}, - "tags": [
- "utilities"
]
}
Returns a list of permits with details for the specified permit IDs. You can specify multiple permit IDs.
A list of permits with detailed information
Validation Error
[- {
- "id": "caf3b9d5ce317d53",
- "description": "Battery backup",
- "number": "RE2303928",
- "jurisdiction": "Berkeley",
- "type": "Re) - electrical - 1 & 2 unit residential (building)",
- "fees": "619.6",
- "status": "active",
- "file_date": "2023-10-02",
- "issue_date": "2023-10-11",
- "final_date": "2023-12-11",
- "start_date": "2022-10-19",
- "end_date": "2023-12-11",
- "total_duration": 230,
- "construction_duration": 61,
- "approval_duration": 9,
- "contractor_id": "KOm4dMLIuT",
- "address": {
- "street_no": "3360",
- "street": "DWIGHT WAY",
- "city": "OAKLAND",
- "zip_code": "94704",
- "state": "CA",
- "latlng": [
- 37.868443,
- -122.24374
]
}, - "tags": [
- "solar",
- "utilities",
- "residential",
- "solar_battery_storage"
]
}, - {
- "id": "71c02bd70f7ce1c9",
- "description": "Install 27 kwh back-up batteries in cabinet ",
- "number": "E2304692",
- "jurisdiction": "Berkeley",
- "type": "E) - electrical - 3+ residential units or commercial",
- "fees": "615.06",
- "status": "in_review",
- "file_date": "2023-11-29",
- "start_date": "2022-11-29",
- "end_date": "2023-11-29",
- "total_duration": 0,
- "construction_duration": 154,
- "approval_duration": 204,
- "address": {
- "street_no": "544",
- "street": "DWIGHT PL",
- "city": "OAKLAND",
- "zip_code": "94704",
- "state": "CA",
- "latlng": [
- 37.8671,
- -122.24461
]
}, - "tags": [
- "solar",
- "utilities",
- "residential",
- "solar_battery_storage"
]
}, - {
- "id": "9525a96a93e0cdb7",
- "description": "Install 27 kwh back-up batteries in cabinet",
- "number": "B2303829",
- "jurisdiction": "Berkeley",
- "job_value": "5001.0",
- "type": "B) - building alteration - 3+ residential units or commercial",
- "fees": "779.53",
- "status": "in_review",
- "file_date": "2023-11-29",
- "start_date": "2022-11-29",
- "end_date": "2023-11-29",
- "total_duration": 0,
- "construction_duration": 154,
- "approval_duration": 204,
- "address": {
- "street_no": "544",
- "street": "DWIGHT PL",
- "city": "OAKLAND",
- "zip_code": "94704",
- "state": "CA",
- "latlng": [
- 37.8671,
- -122.24461
]
}, - "tags": [
- "solar",
- "sitework",
- "residential",
- "solar_battery_storage",
- "commercial"
]
}
]
Returns the building permit activity statistics for a given ZIP code.
A list of activity statistics for the specified ZIP code
Validation Error
{- "items": [
- {
- "month": "2022-10",
- "count": 100
}, - {
- "month": "2022-09",
- "count": 140
}, - {
- "month": "2022-08",
- "count": 320
}, - {
- "month": "2022-07",
- "count": 230
}
], - "page": 1,
- "size": 4
}