Powered by Redocly

The Shovels API v2 (2.0.0)

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

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/v2/meta/release" \
        -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 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.

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 tags and property types, 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
}
Permits
Official documents issued by cities or counties before construction or alteration of a building can begin.


Search Permits
Returns a list of matching permits records. Permits should meet ALL of the parameter filters. Multiple parameters are treated as AND queries.


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


 
permit_from
required
string <date>  (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


 
permit_to
required
string <date>  (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


 
Search Query (string) or Search Query (null) (Search Query) 
The keyword or phrase to search for in permit description.


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


 
Minimum Permit Approval Duration (integer) or Minimum Permit Approval Duration (null) (Minimum Permit Approval Duration) 
Filter by the minimum permit approval duration in days.


 
Minimum Project Construction Duration (integer) or Minimum Project Construction Duration (null) (Minimum Project Construction Duration) 
Filter by the minimum project construction duration in days.


 
Minimum Inspection Pass Rate (integer) or Minimum Inspection Pass Rate (null) (Minimum Inspection Pass Rate) 
Filter by the minimum inspection pass rate.


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


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


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


 
geo_id
required
string (Geolocation ID) 
Filter by the geolocation ID: address, city, zip code, county, etc.


 
Property Type (string) or Property Type (null) (Property Type) 
Filter by property type: Residential, Commercial, Industrial, Agricultural, Vacant Land, Exempt, Miscellaneous, Office, Recreational.


 
Mininum Property Market Value (integer) or Mininum Property Market Value (null) (Mininum Property Market Value) 
Minimum assessed market value of the property.


 
Mininum Property Building Area (integer) or Mininum Property Building Area (null) (Mininum Property Building Area) 
Minimum total building area in sq ft.


 
Mininum Property Lot Size (integer) or Mininum Property Lot Size (null) (Mininum Property Lot Size) 
Minimum size of the property lot in sq ft.


 
Mininum Property Story Count (integer) or Mininum Property Story Count (null) (Mininum Property Story Count) 
Minimum number of property stories.


 
Mininum Property Unit Count (integer) or Mininum Property Unit Count (null) (Mininum Property Unit Count) 
Minimum number of property units


 
Array of Contractor Classification/Certification Codes (strings) or Contractor Classification/Certification Codes (null) (Contractor Classification/Certification Codes) 
State license board classification or other certification codes.


 
Contractor Name (string) or Contractor Name (null) (Contractor Name) 
Filter by contractor's name or part of their name.


 
Mininum Contractor Total Job Value (integer) or Mininum Contractor Total Job Value (null) (Mininum Contractor Total Job Value) 
Minimum lifetime job value of the contractor.


 
Mininum Contractor Permits Count (integer) or Mininum Contractor Permits Count (null) (Mininum Contractor Permits Count) 
Minimum lifetime permits count.


 
Mininum Contractor Inspection Pass Rate (number) or Mininum Contractor Inspection Pass Rate (null) (Mininum Contractor Inspection Pass Rate) 
Minimum lifetime inspection pass rate.


 
Contractor License (string) or Contractor License (null) (Contractor License) 
Filter by the contractor's license


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


422
Validation Error


get/permits/search
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 3
}
Get Permits By Id
Returns a list of permits records for given IDs.


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


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


422
Validation Error


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


Search Contractors
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.


SecurityAPIKeyHeader 
Request 
query Parameters
permit_from
required
string <date>  (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


 
permit_to
required
string <date>  (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


 
Search Query (string) or Search Query (null) (Search Query) 
The keyword or phrase to search for in permit description.


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


 
Minimum Permit Approval Duration (integer) or Minimum Permit Approval Duration (null) (Minimum Permit Approval Duration) 
Filter by the minimum permit approval duration in days.


 
Minimum Project Construction Duration (integer) or Minimum Project Construction Duration (null) (Minimum Project Construction Duration) 
Filter by the minimum project construction duration in days.


 
Minimum Inspection Pass Rate (integer) or Minimum Inspection Pass Rate (null) (Minimum Inspection Pass Rate) 
Filter by the minimum inspection pass rate.


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


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


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


 
geo_id
required
string (Geolocation ID) 
Filter by the geolocation ID: address, city, zip code, county, etc.


 
Property Type (string) or Property Type (null) (Property Type) 
Filter by property type: Residential, Commercial, Industrial, Agricultural, Vacant Land, Exempt, Miscellaneous, Office, Recreational.


 
Mininum Property Market Value (integer) or Mininum Property Market Value (null) (Mininum Property Market Value) 
Minimum assessed market value of the property.


 
Mininum Property Building Area (integer) or Mininum Property Building Area (null) (Mininum Property Building Area) 
Minimum total building area in sq ft.


 
Mininum Property Lot Size (integer) or Mininum Property Lot Size (null) (Mininum Property Lot Size) 
Minimum size of the property lot in sq ft.


 
Mininum Property Story Count (integer) or Mininum Property Story Count (null) (Mininum Property Story Count) 
Minimum number of property stories.


 
Mininum Property Unit Count (integer) or Mininum Property Unit Count (null) (Mininum Property Unit Count) 
Minimum number of property units


 
Array of Contractor Classification/Certification Codes (strings) or Contractor Classification/Certification Codes (null) (Contractor Classification/Certification Codes) 
State license board classification or other certification codes.


 
Contractor Name (string) or Contractor Name (null) (Contractor Name) 
Filter by contractor's name or part of their name.


 
Mininum Contractor Total Job Value (integer) or Mininum Contractor Total Job Value (null) (Mininum Contractor Total Job Value) 
Minimum lifetime job value of the contractor.


 
Mininum Contractor Permits Count (integer) or Mininum Contractor Permits Count (null) (Mininum Contractor Permits Count) 
Minimum lifetime permits count.


 
Mininum Contractor Inspection Pass Rate (number) or Mininum Contractor Inspection Pass Rate (null) (Mininum Contractor Inspection Pass Rate) 
Minimum lifetime inspection pass rate.


 
Contractor License (string) or Contractor License (null) (Contractor License) 
Filter by the contractor's license


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


422
Validation Error


get/contractors/search
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 1
}
Get Contractors By Id
Returns contractors by their IDs. Multiple id query parameters can be provided in the same API call


SecurityAPIKeyHeader 
Request 
query Parameters
id
required
Array of strings (Contractor ID)   <= 50 items 
Filter by the contractor ID.


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


422
Validation Error


get/contractors
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 1
}
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
 
Responses 
200
A list of permits associated with the contractor and grouped by address


422
Validation Error


get/contractors/{id}/permits
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 3
}
Addresses
US address ID resolution, lookup and metrics endpoints.


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": 3
}
Get Permits By Address Id
Retrieves all permits associated with a given address.


SecurityAPIKeyHeader 
Request 
path Parameters
geo_id
required
string (Address ID) 
Filter by the specified address geolocation ID.


 
query Parameters
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of permits associated with the address.


422
Validation Error


get/addresses/{geo_id}/permits
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 3
}
Get Residents
Return residents for a given address geo ID.


SecurityAPIKeyHeader 
Request 
path Parameters
geo_id
required
string (Geo Id) 
Address geo ID


 
query Parameters
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
Residents for a given address geo ID


404
The given geo_id doesn't have residents information.


422
Validation Error


get/addresses/{geo_id}/residents
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 2
}
Cities
City ID resolution, lookup and metrics endpoints.


Search Cities
Searches for cities based on the provided search term.


SecurityAPIKeyHeader 
Request 
query Parameters
q
required
string (City Name Search) 
The name to search for in the city fields.


 
Responses 
200
A list of cities that match the search text.


404
The specified search query didn't match any cities


422
Validation Error


get/cities/search
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 3
}
Get City Metrics
Returns monthly city metrics.


SecurityAPIKeyHeader 
Request 
query Parameters
geo_id
required
string (Geo Id) 
Geolocation ID


 
metric_from
required
string <date>  (Metric From) 
Start date for metrics (inclusive)


 
metric_to
required
string <date>  (Metric To) 
End date for metrics (inclusive)


 
property_type
required
string (Property type) 
Filter by property type


 
required
Tag (string) or Tag (null) (Tag) 
Filter by tag


 
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
Paginated list of city metrics


422
Validation Error


get/cities/metrics
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "size": 0,
  • "next_page": 0
}
Get Permits By City Id
Retrieves all permits associated with a given city.


SecurityAPIKeyHeader 
Request 
path Parameters
geo_id
required
string (City ID) 
Filter by the specified city geolocation ID.


 
query Parameters
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of permits associated with the city.


422
Validation Error


get/cities/{geo_id}/permits
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 3
}
Get City Details
Return city details and related location hierarchy.


SecurityAPIKeyHeader 
Request 
query Parameters
geo_id
required
string (Geo Id) 
Geolocation ID


 
Responses 
200
City details and related location hierarchy.


404
The given geo_id didn't match any cities


422
Validation Error


get/cities
Request samples 
Response samples 
application/json
{
  • "geo_id": "1",
  • "name": "SAN FRANCISCO, SAN FRANCISCO, CA",
  • "counties": {
    },
  • "jurisdictions": {
    },
  • "zipcodes": [
    ],
  • "state": "CA"
}
Counties
County ID resolution, lookup and metrics endpoints.


Search Counties
Searches for counties based on the provided search term.


SecurityAPIKeyHeader 
Request 
query Parameters
q
required
string (County Name Search) 
The name to search for in the county fields.


 
Responses 
200
A list of counties that match the search text.


404
The specified search query didn't match any counties


422
Validation Error


get/counties/search
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 3
}
Get County Metrics
Returns monthly county metrics.


SecurityAPIKeyHeader 
Request 
query Parameters
geo_id
required
string (Geo Id) 
Geolocation ID


 
metric_from
required
string <date>  (Metric From) 
Start date for metrics (inclusive)


 
metric_to
required
string <date>  (Metric To) 
End date for metrics (inclusive)


 
property_type
required
string (Property type) 
Filter by property type


 
required
Tag (string) or Tag (null) (Tag) 
Filter by tag


 
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
Paginated list of county metrics


422
Validation Error


get/counties/metrics
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "size": 0,
  • "next_page": 0
}
Get Permits By County Id
Retrieves all permits associated with a given county.


SecurityAPIKeyHeader 
Request 
path Parameters
geo_id
required
string (County ID) 
Filter by the specified county geolocation ID.


 
query Parameters
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of permits associated with the county.


422
Validation Error


get/counties/{geo_id}/permits
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 3
}
Get County Details
Return county details and related location hierarchy.


SecurityAPIKeyHeader 
Request 
query Parameters
geo_id
required
string (Geo Id) 
Geolocation ID


 
Responses 
200
OK


404
The given geo_id didn't match any counties


422
Validation Error


get/counties
Request samples 
Response samples 
application/json
{
  • "geo_id": "1",
  • "name": "SAN FRANCISCO, SAN FRANCISCO, CA",
  • "cities": {
    },
  • "jurisdictions": {
    },
  • "zipcodes": [
    ],
  • "state": "CA"
}
Jurisdictions
Jurisdiction ID resolution, lookup and metrics endpoints.


Search Jurisditions
Searches for jurisdictions based on the provided search term.


SecurityAPIKeyHeader 
Request 
query Parameters
q
required
string (Jurisdiction Name Search) 
The name to search for in the jurisdiction fields.


 
Responses 
200
A list of jurisdictions that match the search text.


404
The specified search query didn't match any jurisdictions


422
Validation Error


get/jurisdictions/search
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 3
}
Get Jurisdiction Metrics
Returns monthly jurisdiction metrics.


SecurityAPIKeyHeader 
Request 
query Parameters
geo_id
required
string (Geo Id) 
Geolocation ID


 
metric_from
required
string <date>  (Metric From) 
Start date for metrics (inclusive)


 
metric_to
required
string <date>  (Metric To) 
End date for metrics (inclusive)


 
property_type
required
string (Property type) 
Filter by property type


 
required
Tag (string) or Tag (null) (Tag) 
Filter by tag


 
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
Paginated list of jurisdiction metrics


422
Validation Error


get/jurisdictions/metrics
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "size": 0,
  • "next_page": 0
}
Get Permits By Jurisdiction Id
Retrieves all permits associated with a given jurisdiction.


SecurityAPIKeyHeader 
Request 
path Parameters
geo_id
required
string (Jurisdiction ID) 
Filter by the specified jurisdiction geolocation ID.


 
query Parameters
page
integer (Page)   >= 1 
 Default:  1
 
size
integer (Size)   [ 1 .. 100 ] 
 Default:  50
 
Responses 
200
A list of permits associated with the jurisdiction.


422
Validation Error


get/jurisdictions/{geo_id}/permits
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 3
}
Get Jurisdiction Details
Return jurisdiction details and related location hierarchy.


SecurityAPIKeyHeader 
Request 
query Parameters
geo_id
required
string (Geo Id) 
Geolocation ID


 
Responses 
200
OK


404
The given geo_id didn't match any jurisdictions


422
Validation Error


get/jurisdictions
Request samples 
Response samples 
application/json
{
  • "geo_id": "1",
  • "name": "SAN FRANCISCO, SAN FRANCISCO, CA",
  • "cities": {
    },
  • "counties": {
    },
  • "zipcodes": [
    ],
  • "state": "CA"
}
States
State metrics endpoints.


Search States
Searches for US states based on the provided search term.


SecurityAPIKeyHeader 
Request 
query Parameters
q
required
string (US State Search) 
The name to search for in the state fields.


 
Responses 
200
A list of states that match the search term.


404
The specified search query didn't match any states


422
Validation Error


get/states/search
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 3
}
Zipcodes
Search Zipcodes
Searches for zipcodes based on the provided search term.


SecurityAPIKeyHeader 
Request 
query Parameters
q
required
string (ZIP Code Search) 
The code to search for in the zipcodes fields.


 
Responses 
200
A list of zipcodes that match the search code.


404
The specified search query didn't match any zipcodes


422
Validation Error


get/zipcodes/search
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 3
}