Powered by Redocly

The Shovels API v1 (1.0.5)

Download OpenAPI specification:Download

Support: support@shovels.ai

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 zip codes and tags for query parameters.
  • Addresses: Endpoint for searching valid addresses that appear on permits.
  • Markets: Endpoints for historical contractor and building activity by statistical area, jurisdiction, and zip code.
  • Meta: Endpoints for metadata about the API and the data behind it.

Getting started

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.

Authentication

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"

API Details

Quick Overview

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.

Response Types

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

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.

Versioning

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.

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.

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.

Meta

Endpoints that provide information about the API and the data.

Get Data Release Date

Returns the release date of the current data served by the API.

SecurityAPIKeyHeader
Responses
200

The data release date

get/meta/release
Request samples 
Response samples 
application/json
{
  • "released_at": "2020-01-01"
}
Lists
Predefined lists of values and categories, such as zip codes and tags, which can be utilized as query parameters in other API interactions.


Get All Available Zip Codes
Returns all available ZIP codes for which we have permit and contractor data.


SecurityAPIKeyHeader 
Request 
query Parameters
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of available ZIP codes


422
Validation Error


get/list/zip
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 50,
  • "next_page": 2
}
Get All Available Tags
Returns all available permit tags.


SecurityAPIKeyHeader 
Request 
query Parameters
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of available permit tags


422
Validation Error


get/list/tags
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 50,
  • "next_page": 2
}
Addresses
US addresses and geographic information, such as zip codes, which can be used as query parameters in other API interactions.


Search Addresses
Searches for addresses that have at least one associated permit based on the provided text.


SecurityAPIKeyHeader 
Request 
query Parameters
q
required
string (Address Search Text) 
The text to search for in the address fields.


 
Responses 
200
A list of addresses that match the search text, ordered by relevance and in USPS notation.


404
The specified search query didn't match any addresses


422
Validation Error


get/addresses/search
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 5
}
Contractors
Licensed professionals who do permitted work on residential and commercial buildings.


Get Contractors By Activity Address
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.


SecurityAPIKeyHeader 
Request 
query Parameters
street_no
required
string (Street number) 
Street number


 
street
required
string (Street name) 
Street name in USPS notation


 
state
required
string (US State Code)   = 2 characters ^[A-Z]{2}$
Filter by the specified 2-letter US state code.


 
City (string) or City (null) (City) 
Filter by the specified city.


 
ZIP code (string) or ZIP code (null) (ZIP code) 
Filter by the 5-digit ZIP code with optional 4 digit extension.


 
Array of Permit Tags (strings) or Permit Tags (null) (Permit Tags) 
Filter by one or more permit tags.


 
radius
integer (Radius In Meters)   [ 1 .. 50000 ] 
 Default:  1000
Filter by the radius in meters.


 
Start Date (string) or Start Date (null) (Start Date) 
Return permits that started on or after the specified date.This includes all permits with the earliest date (file, issue, or start date) that falls on or after this date. Date format: YYYY-MM-DD


 
End Date (string) or End Date (null) (End Date) 
Return permits that started on or before the specified date.This includes all permits with the latest date (file, issue, or end date) that falls on or before this date. Date format: YYYY-MM-DD


 
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of contractor IDs with additional information


400
At least one of the 'zip_code' or 'city' parameters must be provided


404
The specified address could not be found


422
Validation Error


get/contractors/activity/address
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 50
}
Get Contractors By Activity City
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 start date of the most recent permit on which they worked.


SecurityAPIKeyHeader 
Request 
query Parameters
city
required
string (City) 
Filter by the specified city.


 
state
required
string (US State Code)   = 2 characters ^[A-Z]{2}$
Filter by the specified 2-letter US state code.


 
Array of Permit Tags (strings) or Permit Tags (null) (Permit Tags) 
Filter by one or more tags.


 
Contractor Classification/Certification Code (string) or Contractor Classification/Certification Code (null) (Contractor Classification/Certification Code) 
State license board classification or other certification codes.


 
Start Date (string) or Start Date (null) (Start Date) 
Return permits that started on or after the specified date.This includes all permits with the earliest date (file, issue, or start date) that falls on or after this date. Date format: YYYY-MM-DD


 
End Date (string) or End Date (null) (End Date) 
Return permits that started on or before the specified date.This includes all permits with the latest date (file, issue, or end date) that falls on or before this date. Date format: YYYY-MM-DD


 
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of contractor IDs with additional information


422
Validation Error


get/contractors/activity/city
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 50
}
Get Contractors By Activity Zipcode
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.


SecurityAPIKeyHeader 
Request 
query Parameters
zip_code
required
string (ZIP Code)   [ 5 .. 10 ] characters ^[0-9]{5}-?([0-9]{4})?$
Filter by the 5-digit ZIP code with optional 4 digit extension.


 
Array of Permit Tags (strings) or Permit Tags (null) (Permit Tags) 
Filter by one or more tags.


 
Contractor Classification/Certification Code (string) or Contractor Classification/Certification Code (null) (Contractor Classification/Certification Code) 
State license board classification or other certification codes.


 
Start Date (string) or Start Date (null) (Start Date) 
Return permits that started on or after the specified date.This includes all permits with the earliest date (file, issue, or start date) that falls on or after this date. Date format: YYYY-MM-DD


 
End Date (string) or End Date (null) (End Date) 
Return permits that started on or before the specified date.This includes all permits with the latest date (file, issue, or end date) that falls on or before this date. Date format: YYYY-MM-DD


 
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of contractor IDs with additional information


422
Validation Error


get/contractors/activity/zip
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 50
}
Get Contractors Business By Name
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.


SecurityAPIKeyHeader 
Request 
query Parameters
name
required
string (Contractor Name) 
Filter by contractor's name or part of their name.


 
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of contractor IDs and their business names


422
Validation Error


get/contractors/business/name
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 50
}
Get Contractors Business By License
Returns contractors by their business license and state.


SecurityAPIKeyHeader 
Request 
query Parameters
license
required
string (Contractor License) 
Filter by the contractor's license


 
state
required
string (US State Code)   = 2 characters ^[A-Z]{2}$
Filter by the 2-letter US state code.


 
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of contractor business entities under the same license


404
The contractor with the given license and state was not found.


422
Validation Error


get/contractors/business/license
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 50
}
Get Contractors Business By Zip Codes
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.


SecurityAPIKeyHeader 
Request 
query Parameters
zip_codes
required
Array of strings (ZIP Codes) 
Filter the results by 5-digit ZIP codes, optionally including the 4-digit extension.


 
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of contractor IDs and their business names.


422
Validation Error


get/contractors/business/zip
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 50
}
Get Contractor By Id
Returns the contractor identified by the given ID.


SecurityAPIKeyHeader 
Request 
path Parameters
id
required
string (Contractor ID) 
Filter by the specified contractor ID.


 
Responses 
200
The detailed record of the requested contractor


404
The requested contractor ID was not found


422
Validation Error


get/contractors/{id}
Request samples 
Response samples 
application/json
{
  • "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": [
    ],
  • "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": {
    },
  • "tag_tally": {
    }
}
Get Permits By Contractor Id
Retrieves all permits associated with a single contractor.


SecurityAPIKeyHeader 
Request 
path Parameters
id
required
string (Contractor ID) 
Filter by the specified contractor ID.


 
query Parameters
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Start Date (string) or Start Date (null) (Start Date) 
Return permits that started on or after the specified date.This includes all permits with the earliest date (file, issue, or start date) that falls on or after this date. Date format: YYYY-MM-DD


 
End Date (string) or End Date (null) (End Date) 
Return permits that started on or before the specified date.This includes all permits with the latest date (file, issue, or end date) that falls on or before this date. Date format: YYYY-MM-DD


 
Responses 
200
A list of permits associated with the contractor and grouped by address


404
The requested contractor ID was not found


422
Validation Error


get/contractors/{id}/permits
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 2
}
Get Metrics By Contractor Id
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.


SecurityAPIKeyHeader 
Request 
path Parameters
id
required
string (Contractor ID) 
Filter by the specified contractor ID.


 
Responses 
200
The contractor work metrics


404
The requested contractor ID was not found


422
Validation Error


get/contractors/{id}/metrics
Request samples 
Response samples 
application/json
{
  • "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": [
    ]
}
Permits
Official documents issued by cities or counties before construction or alteration of a building can begin.


Search Permits Description
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.


SecurityAPIKeyHeader 
Request 
query Parameters
Search Query (string) or Search Query (null) (Search Query) 
The keyword or phrase to search for.


 
US State Code (string) or US State Code (null) (US State Code) 
Filter by the 2-letter US state code.


 
ZIP Code (string) or ZIP Code (null) (ZIP Code) 
Filter by the 5-digit ZIP code, optionally including the 4-digit extension.


 
City (string) or City (null) (City) 
Filter by the specified city.


 
Array of Permit Status (strings) or Permit Status (null) (Permit Status)   <= 4 items 
Filter by one or more statuses: final, in_review, inactive, active.


 
Array of Permit Tags (strings) or Permit Tags (null) (Permit Tags) 
Filter by one or more tags.


 
Has Contractor (boolean) or Has Contractor (null) (Has Contractor) 
Return only records that have a contractor ID.


 
Minimum Job Value (number) or Minimum Job Value (string) or Minimum Job Value (null) (Minimum Job Value) 
Filter by the minimum job value.


 
Minimum Permit Fees (number) or Minimum Permit Fees (string) or Minimum Permit Fees (null) (Minimum Permit Fees) 
Filter by minimum permit fees.


 
Start Date (string) or Start Date (null) (Start Date) 
Return permits that started on or after the specified date.This includes all permits with the earliest date (file, issue, or start date) that falls on or after this date. Date format: YYYY-MM-DD


 
End Date (string) or End Date (null) (End Date) 
Return permits that started on or before the specified date.This includes all permits with the latest date (file, issue, or end date) that falls on or before this date. Date format: YYYY-MM-DD


 
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of permit IDs with corresponding descriptions.


400
The 'state' parameter is required when the 'city' parameter is specified


422
Validation Error


get/permits/search
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 5
}
Get Permits By Address
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.


SecurityAPIKeyHeader 
Request 
query Parameters
street_no
required
string (Street Number) 
Filter by the specified street number.


 
street
required
string (Street Name) 
Filter by the specified street name in USPS notation.


 
state
required
string (US State Code)   = 2 characters ^[A-Z]{2}$
Filter by 2-letter US state code.


 
City (string) or City (null) (City) 
Filter by the specified city.


 
ZIP Code (string) or ZIP Code (null) (ZIP Code) 
Filter by 5-digit ZIP code with optional 4 digit extension.


 
Array of Permit Status (strings) or Permit Status (null) (Permit Status)   <= 4 items 
Filter by one or more statuses: final, in_review, inactive, active.


 
Array of Permit Tags (strings) or Permit Tags (null) (Permit Tags) 
Filter by one or more permit tags.


 
Has Contractor (boolean) or Has Contractor (null) (Has Contractor) 
Only return records that have a contractor ID.


 
Minimum Job Value (number) or Minimum Job Value (string) or Minimum Job Value (null) (Minimum Job Value) 
Filter by minimum job value.


 
Minimum Permit Fees (number) or Minimum Permit Fees (string) or Minimum Permit Fees (null) (Minimum Permit Fees) 
Filter by minimum permit fees value.


 
Start Date (string) or Start Date (null) (Start Date) 
Return permits that started on or after the specified date.This includes all permits with the earliest date (file, issue, or start date) that falls on or after this date. Date format: YYYY-MM-DD


 
End Date (string) or End Date (null) (End Date) 
Return permits that started on or before the specified date.This includes all permits with the latest date (file, issue, or end date) that falls on or before this date. Date format: YYYY-MM-DD


 
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of permit IDs


400
At least one of the 'zip_code' or 'city' parameters must be provided


404
The address was not found OR we don't have permit coverage in the area.


422
Validation Error


get/permits/address
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 3
}
Get Permits By Zip Code
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.


SecurityAPIKeyHeader 
Request 
query Parameters
zip_code
required
string (ZIP Code)   [ 5 .. 10 ] characters ^[0-9]{5}-?([0-9]{4})?$
5-digit ZIP code with optional 4 digit extension.


 
Array of Permit Status (strings) or Permit Status (null) (Permit Status)   <= 4 items 
Filter by one or more statuses: final, in_review, inactive, active.


 
Array of Permit Tags (strings) or Permit Tags (null) (Permit Tags) 
Filter by one or more tags.


 
Has Contractor (boolean) or Has Contractor (null) (Has Contractor) 
Only return records that have a contractor ID.


 
Minimum Job Value (number) or Minimum Job Value (string) or Minimum Job Value (null) (Minimum Job Value) 
Filter by the minimum job value.


 
Minimum Permit Fees (number) or Minimum Permit Fees (string) or Minimum Permit Fees (null) (Minimum Permit Fees) 
Filter by minimum permit fees.


 
Start Date (string) or Start Date (null) (Start Date) 
Return permits that started on or after the specified date.This includes all permits with the earliest date (file, issue, or start date) that falls on or after this date. Date format: YYYY-MM-DD


 
End Date (string) or End Date (null) (End Date) 
Return permits that started on or before the specified date.This includes all permits with the latest date (file, issue, or end date) that falls on or before this date. Date format: YYYY-MM-DD


 
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of permit IDs


422
Validation Error


get/permits/zip
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 3
}
Get Permits By State
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.


SecurityAPIKeyHeader 
Request 
query Parameters
state
required
string (US State Code)   = 2 characters ^[A-Z]{2}$
Filter by the 2-letter US state code.


 
Array of Permit Status (strings) or Permit Status (null) (Permit Status)   <= 4 items 
Filter by one or more statuses: final, in_review, inactive, active.


 
Array of Permit Tags (strings) or Permit Tags (null) (Permit Tags) 
Filter by one or more tags.


 
Has Contractor (boolean) or Has Contractor (null) (Has Contractor) 
Only return records that have a contractor ID.


 
Minimum Job Value (number) or Minimum Job Value (string) or Minimum Job Value (null) (Minimum Job Value) 
Filter by the minimum job value.


 
Minimum Permit Fees (number) or Minimum Permit Fees (string) or Minimum Permit Fees (null) (Minimum Permit Fees) 
Filter by minimum permit fees.


 
Start Date (string) or Start Date (null) (Start Date) 
Return permits that started on or after the specified date.This includes all permits with the earliest date (file, issue, or start date) that falls on or after this date. Date format: YYYY-MM-DD


 
End Date (string) or End Date (null) (End Date) 
Return permits that started on or before the specified date.This includes all permits with the latest date (file, issue, or end date) that falls on or before this date. Date format: YYYY-MM-DD


 
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of permit IDs.


422
Validation Error


get/permits/state
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 3
}
Get Permit By Id
Returns the requested permit details by ID.


SecurityAPIKeyHeader 
Request 
path Parameters
id
required
string (Permit ID) 
Filter by the permit's ID.


 
Responses 
200
The permit details record


404
The requested permit ID was not found


422
Validation Error


get/permits/{id}
Request samples 
Response samples 
application/json
{
  • "id": "71c02bd70f7ce1c9",
  • "description": "Service panel replacement 200 amp like for like",
  • "number": "B2022-04886",
  • "jurisdiction": "Berkeley",
  • "job_value": 5000,
  • "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,
  • "inspection_pass_rate": 0.33,
  • "contractor_id": "48d93f3020c4",
  • "address": {
    },
  • "tags": [
    ]
}
Get Permits By Id
Returns a list of permits with details for the specified permit IDs. You can specify multiple permit IDs.


SecurityAPIKeyHeader 
Request 
query Parameters
id
required
Array of strings (Permit ID)   <= 50 items 
Filter by the permit's ID.


 
Responses 
200
A list of permits with detailed information


422
Validation Error


get/permits
Request samples 
Response samples 
application/json
[
  • {
    },
  • {
    },
  • {
    }
]
Markets
Historical contractor and building activity by statistical area, jurisdiction, and zip code.


Get Market Activity By Zip Code
Returns the building permit activity statistics for a given ZIP code.


SecurityAPIKeyHeader 
Request 
query Parameters
zip_code
required
string (ZIP Code)   [ 5 .. 10 ] characters ^[0-9]{5}-?([0-9]{4})?$
Filter by the 5-digit ZIP code, optionally including 4-digit extension.


 
Array of Permit Tags (strings) or Permit Tags (null) (Permit Tags) 
Filter by one or more tags.


 
Start Date (string) or Start Date (null) (Start Date) 
Return permits that started on or after the specified date.This includes all permits with the earliest date (file, issue, or start date) that falls on or after this date. Date format: YYYY-MM-DD


 
End Date (string) or End Date (null) (End Date) 
Return permits that started on or before the specified date.This includes all permits with the latest date (file, issue, or end date) that falls on or before this date. Date format: YYYY-MM-DD


 
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of activity statistics for the specified ZIP code


422
Validation Error


get/markets/permits/zip
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 4
}