The Shovels API (v1.0)

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!

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.
  • 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.

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/v1/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/v1/list/tags
Request samples
Response samples
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 50,
  • "next_page": 2
}

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)
Default: 1000

Filter by the radius in meters.

Start Date (string) or Start Date (null) (Start Date)

Return records that were filed, issued or finalized after the specified date.It indicates the beginning of a period during which the retrieved permit records are active (filed, issued or finalized). Date format: YYYY-MM-DD

End Date (string) or End Date (null) (End Date)

Return records that were filed, issued or finalized after the specified date.It indicates the end of a period during which the retrieved permit records are active. 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/v1/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 file 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 records that were filed, issued or finalized after the specified date.It indicates the beginning of a period during which the retrieved permit records are active (filed, issued or finalized). Date format: YYYY-MM-DD

End Date (string) or End Date (null) (End Date)

Return records that were filed, issued or finalized after the specified date.It indicates the end of a period during which the retrieved permit records are active. 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/v1/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 records that were filed, issued or finalized after the specified date.It indicates the beginning of a period during which the retrieved permit records are active (filed, issued or finalized). Date format: YYYY-MM-DD

End Date (string) or End Date (null) (End Date)

Return records that were filed, issued or finalized after the specified date.It indicates the end of a period during which the retrieved permit records are active. 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/v1/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/v1/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/v1/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/v1/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/v1/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",
  • "phone": "4154248801,4156839290,6503031620,6508665085",
  • "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 records that were filed, issued or finalized after the specified date.It indicates the beginning of a period during which the retrieved permit records are active (filed, issued or finalized). Date format: YYYY-MM-DD

End Date (string) or End Date (null) (End Date)

Return records that were filed, issued or finalized after the specified date.It indicates the end of a period during which the retrieved permit records are active. 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/v1/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/v1/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",
  • "phone": "4154248801,4156839290,6503031620,6508665085",
  • "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)

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 records that were filed, issued or finalized after the specified date.It indicates the beginning of a period during which the retrieved permit records are active (filed, issued or finalized). Date format: YYYY-MM-DD

End Date (string) or End Date (null) (End Date)

Return records that were filed, issued or finalized after the specified date.It indicates the end of a period during which the retrieved permit records are active. 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/v1/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)

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 records that were filed, issued or finalized after the specified date.It indicates the beginning of a period during which the retrieved permit records are active (filed, issued or finalized). Date format: YYYY-MM-DD

End Date (string) or End Date (null) (End Date)

Return records that were filed, issued or finalized after the specified date.It indicates the end of a period during which the retrieved permit records are active. 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/v1/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)

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 records that were filed, issued or finalized after the specified date.It indicates the beginning of a period during which the retrieved permit records are active (filed, issued or finalized). Date format: YYYY-MM-DD

End Date (string) or End Date (null) (End Date)

Return records that were filed, issued or finalized after the specified date.It indicates the end of a period during which the retrieved permit records are active. 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/v1/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)

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 records that were filed, issued or finalized after the specified date.It indicates the beginning of a period during which the retrieved permit records are active (filed, issued or finalized). Date format: YYYY-MM-DD

End Date (string) or End Date (null) (End Date)

Return records that were filed, issued or finalized after the specified date.It indicates the end of a period during which the retrieved permit records are active. 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/v1/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/v1/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.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",
  • "construction_duration": 121,
  • "approval_duration": 109,
  • "inspections_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)

Filter by the permit's ID.

Responses
200

A list of permits with detailed information

422

Validation Error

get/v1/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 records that were filed, issued or finalized after the specified date.It indicates the beginning of a period during which the retrieved permit records are active (filed, issued or finalized). Date format: YYYY-MM-DD

End Date (string) or End Date (null) (End Date)

Return records that were filed, issued or finalized after the specified date.It indicates the end of a period during which the retrieved permit records are active. 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/v1/markets/permits/zip
Request samples
Response samples
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 4
}

Meta

Get Data Release Date

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

SecurityAPIKeyHeader
Responses
200

The data release date

get/v1/meta/release
Request samples
Response samples
application/json
{
  • "released_at": "2020-01-01"
}

Addresses

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/v1/addresses/search
Request samples
Response samples
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 50
}