GET
/
permits
Get Permits By Id
curl --request GET \
  --url https://api.shovels.ai/v2/permits \
  --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

id
string[]
required

Filter by the permit's ID.

Maximum length: 50
cursor
string | null

Cursor for pagination

page
integer | null

Page number for offset-based pagination (only used if cursor is not provided)

Required range: x >= 1
size
integer
default:50

Number of items per page

Required range: 1 <= x <= 100

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.

page
integer
required

The page number of the response.

size
integer
required

The number of items returned in the response.

next_page
integer | null
required

The next page number of the response.

pagination_type
string
default:offset
Allowed value: "offset"