SHshovels
Permits
Permits

Search Permits

Changed on

Returns a list of matching permits records. Permits should meet ALL of the parameter filters. Multiple parameters are treated as AND queries. Use contractor_classification_derived to filter by contractor's derived classifications (ALL specified values required).

get/permits/search

Request

  • Base URL
    https://api.shovels.ai/v2
  • Auth
    API key in header X-API-Key

Query parameters

permit_fromstring date required

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_tostring date required

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

permit_tagsstring[] nullable

Filter by one or more tags. Use '-' prefix to exclude tags. Example: ?permit_tags=solar&permit_tags=-roofing (has solar, not roofing).

geo_idstring required

Filter results by geographic area. Accepts:

  • US state code (e.g. CA)
  • ZIP code (e.g. 90210 or 90210-1234)
  • Shovels geolocation ID for an address, city, county, or jurisdiction (e.g. a4xysKbZwqg)

Resolve addresses and places to geolocation IDs via:

  • Search Addresses
  • Search Cities
  • Search Counties
  • Search Jurisdictions

Free-form text such as "123 Main St" is not accepted.

permit_has_contractorboolean nullable

Filter by contractor presence: true returns only permits with a contractor, false only permits without one. Omit to apply no filter.

cursorstring nullable

Cursor for pagination

sizeinteger
include_countboolean

When true and on the first page (no cursor), include total_count in the response. The count is exact up to 10,000; above that, relation is 'gte'.

permit_qstring nullable

Search permit descriptions. Permits search uses case-insensitive substring matching, including partial words. Contractors search uses full-text search with English stemming. For example, installing matches install. Multi-word contractor queries require all words after English text processing. For example, solar panel requires both solar and panel.

permit_statusstring[] nullable

Filter by one or more statuses: final, in_review, inactive, active.

permit_min_approval_durationinteger nullable

Filter by the minimum permit approval duration in days.

permit_min_construction_durationinteger nullable

Filter by the minimum project construction duration in days.

permit_min_inspection_printeger nullable

Filter by the minimum inspection pass rate.

permit_min_job_valueinteger nullable

Filter by the minimum job value, in cents (e.g. 5000000 = $50,000).

permit_min_feesinteger nullable

Filter by minimum permit fees, in cents (e.g. 5000000 = $50,000).

property_typestring[] nullable

Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational. Repeat the key to match any of several types (e.g. ?property_type=residential&property_type=commercial).

property_min_market_valueinteger nullable

Minimum assessed market value of the property, in cents (e.g. 5000000 = $50,000).

property_min_building_areainteger nullable

Minimum total building area in sq ft.

property_min_lot_sizeinteger nullable

Minimum size of the property lot in sq ft.

property_min_story_countinteger nullable

Minimum number of property stories.

property_min_unit_countinteger nullable

Minimum number of property units

contractor_classification_derivedstring[] nullable

Filter by derived contractor classifications. Use '-' prefix to exclude. Example: ?classification_derived=electrical&classification_derived=-hvac. Returns results containing ALL specified classifications. Possible values: concrete_and_paving, demolition_and_excavation, electrical, fencing_and_glazing, framing_and_carpentry, general_building_contractor, general_engineering_contractor, hvac, landscaping_and_outdoor_work, other, plumbing, roofing, specialty_trades.

contractor_namestring nullable

Filter by contractor's name or business name (partial match supported). Must be at least 3 characters — shorter patterns cannot use the trigram index and would force a sequential scan.

contractor_websitestring nullable

Filter by contractor's website prefix. Surrounding whitespace is trimmed and input is lowercased. Leading http://, https://, and www. prefixes and trailing slashes are removed. Paths are retained. A value that is empty after normalization applies no website filter.

contractor_min_total_job_valueinteger nullable

Minimum lifetime job value of the contractor, in cents (e.g. 5000000 = $50,000).

contractor_min_total_permits_countinteger nullable

Minimum lifetime permits count.

contractor_min_inspection_printeger nullable

Minimum lifetime inspection pass rate. The value must be an integer between 0 and 100, inclusive.

contractor_licensestring nullable

Filter by the contractor's license

Response

A list of permits.

sizeinteger required

The number of items returned in the response.

next_cursorstring nullable required

The cursor for retrieving the next page of results.

Changes

  • 64df4c8074f5Revision changes
    • breaking

      for the query request parameter size, default value was changed from 50 to 10

  • 685b8866c451Revision changes
    • breaking

      query request parameter property_type list-of-types was narrowed by removing types string

    • breaking

      for the query request parameter property_type, the type of property anyOf[subschema #1]/ was specialized from string to array

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status