Skip to main content
GET
/
permits
/
search
Search Permits
curl --request GET \
  --url https://api.shovels.ai/v2/permits/search \
  --header 'X-API-Key: <api-key>'
{
  "items": [
    {
      "property_census_tract": "101",
      "property_congressional_district": "1",
      "property_type": "residential",
      "property_type_detail": "single_family_home",
      "property_legal_owner": "OAKLAND HOUSING AUTHORITY",
      "property_owner_type": "private_owner",
      "property_lot_size": 4000,
      "property_building_area": 1000,
      "property_story_count": 1,
      "property_unit_count": 1,
      "property_year_built": 1970,
      "property_assess_market_value": 105000000,
      "id": "caf3b9d5ce317d53",
      "number": "RE2303928",
      "description": "Battery backup",
      "jurisdiction": "Berkeley",
      "job_value": 500000,
      "type": "Re) - electrical - 1 & 2 unit residential (building)",
      "fees": 61960,
      "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,
      "inspection_pass_rate": 85,
      "contractor_id": "KOm4dMLIuT",
      "tags": [
        "solar",
        "utilities",
        "residential",
        "solar_battery_storage"
      ],
      "address": {
        "street_no": "3360",
        "street": "DWIGHT WAY",
        "city": "OAKLAND",
        "zip_code": "94704",
        "state": "CA",
        "latlng": [
          37.868443,
          -122.24374
        ]
      },
      "geo_ids": {
        "address_id": "asd8a8b19",
        "city_id": "KLais31",
        "county_id": "ALa2s33",
        "jurisdiction_id": "BLa2s33"
      }
    },
    {
      "property_census_tract": "101",
      "property_congressional_district": "1",
      "property_type": "residential",
      "property_type_detail": "single_family_home",
      "property_legal_owner": "OAKLAND HOUSING AUTHORITY",
      "property_owner_type": "private_owner",
      "property_lot_size": 4000,
      "property_building_area": 1000,
      "property_story_count": 1,
      "property_unit_count": 1,
      "property_year_built": 1970,
      "property_assess_market_value": 105000000,
      "id": "71c02bd70f7ce1c9",
      "number": "E2304692",
      "description": "Install 27 kwh back-up batteries in cabinet ",
      "jurisdiction": "Berkeley",
      "job_value": 750000,
      "type": "E) - electrical - 3+ residential units or commercial",
      "fees": 61506,
      "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,
      "tags": [
        "solar",
        "utilities",
        "residential",
        "solar_battery_storage"
      ],
      "address": {
        "street_no": "544",
        "street": "DWIGHT PL",
        "city": "OAKLAND",
        "zip_code": "94704",
        "state": "CA",
        "latlng": [
          37.8671,
          -122.24461
        ]
      },
      "geo_ids": {
        "address_id": "1sd8a8b19",
        "city_id": "KLais31",
        "county_id": "ALa2s33",
        "jurisdiction_id": "BLa2s33"
      }
    },
    {
      "property_census_tract": "101",
      "property_congressional_district": "1",
      "property_type": "residential",
      "property_type_detail": "single_family_home",
      "property_legal_owner": "OAKLAND HOUSING AUTHORITY",
      "property_owner_type": "private_owner",
      "property_lot_size": 4000,
      "property_building_area": 1000,
      "property_story_count": 1,
      "property_unit_count": 1,
      "property_year_built": 1970,
      "property_assess_market_value": 105000000,
      "id": "9525a96a93e0cdb7",
      "number": "B2303829",
      "description": "Install 27 kwh back-up batteries in cabinet",
      "jurisdiction": "Berkeley",
      "job_value": 500100,
      "type": "Building alteration: 3+ residential units or commercial",
      "fees": 7953,
      "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,
      "tags": [
        "solar",
        "sitework",
        "residential",
        "solar_battery_storage",
        "commercial"
      ],
      "address": {
        "street_no": "544",
        "street": "DWIGHT PL",
        "city": "OAKLAND",
        "zip_code": "94704",
        "state": "CA",
        "latlng": [
          37.8671,
          -122.24461
        ]
      },
      "geo_ids": {
        "address_id": "1sd8a8b19",
        "city_id": "KLais31",
        "county_id": "ALa2s33",
        "jurisdiction_id": "BLa2s33"
      }
    }
  ],
  "size": 3,
  "next_cursor": "tfZ.9525a96a93e0cdb7"
}

Authorizations

​
X-API-Key
string
header
required

Query Parameters

​
permit_from
string<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_to
string<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_tags
string[] | null

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

​
geo_id
string
required

Filter by the geolocation ID: address, city, zip code, county, etc.

​
permit_has_contractor
boolean | null

Return only records that have a contractor ID.

​
cursor
string | null

Cursor for pagination

​
size
integer
default:50
Required range: 1 <= x <= 100
​
permit_q
string | null

Substring to search for in permit description (case-insensitive). Matches anywhere in the text, including partial words.

Maximum string length: 50
​
permit_status
string[]

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

Maximum array length: 4
​
permit_min_approval_duration
integer | null

Filter by the minimum permit approval duration in days.

​
permit_min_construction_duration
integer | null

Filter by the minimum project construction duration in days.

​
permit_min_inspection_pr
integer | null

Filter by the minimum inspection pass rate.

​
permit_min_job_value
integer | null

Filter by the minimum job value.

​
permit_min_fees
integer | null

Filter by minimum permit fees.

​
property_type
string | null

Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational.

​
property_min_market_value
integer | null

Minimum assessed market value of the property.

​
property_min_building_area
integer | null

Minimum total building area in sq ft.

​
property_min_lot_size
integer | null

Minimum size of the property lot in sq ft.

​
property_min_story_count
integer | null

Minimum number of property stories.

​
property_min_unit_count
integer | null

Minimum number of property units

​
contractor_classification_derived
string[] | null

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_name
string | null

Filter by contractor's name or part of their name.

​
contractor_website
string | null

Filter by contractor's website. Don't include the http(s):// prefix.

​
contractor_min_total_job_value
integer | null

Minimum lifetime job value of the contractor.

​
contractor_min_total_permits_count
integer | null

Minimum lifetime permits count.

​
contractor_min_inspection_pr
integer | null

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

​
contractor_license
string | null

Filter by the contractor's license

Response

A list of permits.

Schema for paginated permits details response.

​
items
PermitsRead · object[]
required

The list of items returned in the response following given criteria.

​
size
integer
required

The number of items returned in the response.

​
next_cursor
string | null
required

The cursor for retrieving the next page of results.