Search Permits

Search Permits

curl --request GET \
  --url https://api.shovels.ai/v2/permits/search \
  --header 'X-API-Key: <api-key>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.shovels.ai/v2/permits/search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.shovels.ai/v2/permits/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.shovels.ai/v2/permits/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "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",
      "description_derived": "Battery storage installation",
      "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",
        "battery",
        "electrical"
      ],
      "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 ",
      "description_derived": "Battery storage installation",
      "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",
        "battery",
        "electrical"
      ],
      "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",
      "description_derived": "Battery storage installation",
      "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": [
        "battery",
        "electrical",
        "remodel"
      ],
      "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"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

GET

permits

Search Permits

curl --request GET \
  --url https://api.shovels.ai/v2/permits/search \
  --header 'X-API-Key: <api-key>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.shovels.ai/v2/permits/search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.shovels.ai/v2/permits/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.shovels.ai/v2/permits/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "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",
      "description_derived": "Battery storage installation",
      "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",
        "battery",
        "electrical"
      ],
      "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 ",
      "description_derived": "Battery storage installation",
      "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",
        "battery",
        "electrical"
      ],
      "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",
      "description_derived": "Battery storage installation",
      "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": [
        "battery",
        "electrical",
        "remodel"
      ],
      "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"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

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

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

permit_has_contractor

boolean | null

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

cursor

string | null

Cursor for pagination

size

integer

default:10

Required range: 1 <= x <= 100

include_count

boolean

default:false

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_q

string | null

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.

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, in cents (e.g. 5000000 = $50,000).

permit_min_fees

integer | null

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

property_type

string[] | null

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_value

integer | null

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

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 business name (partial match supported). Must be at least 3 characters — shorter patterns cannot use the trigram index and would force a sequential scan.

Minimum string length: 3

contractor_website

string | null

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_value

integer | null

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

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.

Show child attributes

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.

total_count

TotalCount · object | null

Top-level count object, not an integer: {"value": 970, "relation": "eq"}. "eq" means an exact count up to 10,000. "gte" means at least 10,000 matches, with value set to 10,000. Counted only when requested on the first page without a cursor. null when not requested, on later pages, or when the count query times out.

Show child attributes

Example:

{ "relation": "eq", "value": 970 }

Getting Started

Endpoints

Authorizations

Query Parameters

Response