Download OpenAPI specification:Download
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!
The API offers access to two primary objects: Permits and Contractors.
And some additional resources:
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.
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"
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. |
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 |
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.
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.
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.
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:
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.
Predefined lists of values and categories, such as tags and property types, which can be utilized as query parameters in other API interactions.
Returns all available ZIP codes for which we have permit and contractor data.
A list of available ZIP codes
Validation Error
{- "items": [
- {
- "zip_code": "90001",
- "zip_code_exts": [
- "1234",
- "1235"
]
}, - {
- "zip_code": "90002",
- "zip_code_exts": [
- "1235",
- "1236"
]
}, - {
- "zip_code": "90003",
- "zip_code_exts": [
- "1236",
- "1237"
]
}, - {
- "zip_code": "90004",
- "zip_code_exts": [
- "1237",
- "1238"
]
}, - {
- "zip_code": "90005",
- "zip_code_exts": [
- "1334",
- "1335"
]
}, - {
- "zip_code": "90006",
- "zip_code_exts": [
- "1434",
- "1435"
]
}, - {
- "zip_code": "90007",
- "zip_code_exts": [
- "1534",
- "1535"
]
}, - {
- "zip_code": "90008",
- "zip_code_exts": [
- "1634",
- "1635"
]
}, - {
- "zip_code": "90009",
- "zip_code_exts": [
- "1734",
- "1735"
]
}, - {
- "zip_code": "90010",
- "zip_code_exts": [
- "1834",
- "1835"
]
}
], - "page": 1,
- "size": 50,
- "next_page": 2
}
Official documents issued by cities or counties before construction or alteration of a building can begin.
Returns a list of matching permits records. Permits should meet ALL of the parameter filters. Multiple parameters are treated as AND queries.
A list of permits.
Validation Error
{- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "caf3b9d5ce317d53",
- "description": "Battery backup",
- "number": "RE2303928",
- "jurisdiction": "Berkeley",
- "type": "Re) - electrical - 1 & 2 unit residential (building)",
- "fees": 619.6,
- "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,
- "contractor_id": "KOm4dMLIuT",
- "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"
}, - "tags": [
- "solar",
- "utilities",
- "residential",
- "solar_battery_storage"
]
}, - {
- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "71c02bd70f7ce1c9",
- "description": "Install 27 kwh back-up batteries in cabinet ",
- "number": "E2304692",
- "jurisdiction": "Berkeley",
- "type": "E) - electrical - 3+ residential units or commercial",
- "fees": 615.06,
- "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,
- "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"
}, - "tags": [
- "solar",
- "utilities",
- "residential",
- "solar_battery_storage"
]
}, - {
- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "9525a96a93e0cdb7",
- "description": "Install 27 kwh back-up batteries in cabinet",
- "number": "B2303829",
- "jurisdiction": "Berkeley",
- "job_value": 5001,
- "type": "Building alteration: 3+ residential units or commercial",
- "fees": 79.53,
- "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,
- "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"
}, - "tags": [
- "solar",
- "sitework",
- "residential",
- "solar_battery_storage",
- "commercial"
]
}
], - "page": 1,
- "size": 3
}
Returns a list of permits records for given IDs.
A list of permits.
Validation Error
{- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "caf3b9d5ce317d53",
- "description": "Battery backup",
- "number": "RE2303928",
- "jurisdiction": "Berkeley",
- "type": "Re) - electrical - 1 & 2 unit residential (building)",
- "fees": 619.6,
- "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,
- "contractor_id": "KOm4dMLIuT",
- "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"
}, - "tags": [
- "solar",
- "utilities",
- "residential",
- "solar_battery_storage"
]
}, - {
- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "71c02bd70f7ce1c9",
- "description": "Install 27 kwh back-up batteries in cabinet ",
- "number": "E2304692",
- "jurisdiction": "Berkeley",
- "type": "E) - electrical - 3+ residential units or commercial",
- "fees": 615.06,
- "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,
- "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"
}, - "tags": [
- "solar",
- "utilities",
- "residential",
- "solar_battery_storage"
]
}, - {
- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "9525a96a93e0cdb7",
- "description": "Install 27 kwh back-up batteries in cabinet",
- "number": "B2303829",
- "jurisdiction": "Berkeley",
- "job_value": 5001,
- "type": "Building alteration: 3+ residential units or commercial",
- "fees": 79.53,
- "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,
- "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"
}, - "tags": [
- "solar",
- "sitework",
- "residential",
- "solar_battery_storage",
- "commercial"
]
}
], - "page": 1,
- "size": 3
}
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.
A list of contractors.
Validation Error
{- "items": [
- {
- "id": "e79c3393ad",
- "license": "961870",
- "name": "CA SUNRISE CONSTRUCTION SOLUTION INC.",
- "business_name": "CA SUNRISE CONSTRUCTION SOLUTION INC.",
- "business_type": "Corporation",
- "classification": "CFC",
- "primary_phone": "(425) 507-4300",
- "primary_email": "atobar.casunrise@gmail.com",
- "phone": "(425) 270-9678,(425) 281-6152",
- "email": "atobar.casunrise@gmail.com,david@calsunrise.com",
- "status_tally": {
- "final": 754,
- "active": 81,
- "unknown": 2,
- "inactive": 313
}, - "tag_tally": {
- "hvac": 27,
- "solar": 39,
- "reroof": 1,
- "pool_spa": 1,
- "heat_pump": 267,
- "utilities": 1110,
- "commercial": 20
}, - "address": {
- "street_no": "2800",
- "street": "COTTONWOOD DR",
- "city": "SAN BRUNO",
- "zip_code": "94066",
- "state": "CA",
- "address_id": "asd8a8b19",
- "latlng": [
- 37.37619,
- -121.869064
]
}
}
], - "page": 1,
- "size": 1
}
Returns contractors by their IDs. Multiple id
query parameters can be provided in the same API call
A list of contractors.
Validation Error
{- "items": [
- {
- "id": "e79c3393ad",
- "license": "961870",
- "name": "CA SUNRISE CONSTRUCTION SOLUTION INC.",
- "business_name": "CA SUNRISE CONSTRUCTION SOLUTION INC.",
- "business_type": "Corporation",
- "classification": "CFC",
- "primary_phone": "(425) 507-4300",
- "primary_email": "atobar.casunrise@gmail.com",
- "phone": "(425) 270-9678,(425) 281-6152",
- "email": "atobar.casunrise@gmail.com,david@calsunrise.com",
- "status_tally": {
- "final": 754,
- "active": 81,
- "unknown": 2,
- "inactive": 313
}, - "tag_tally": {
- "hvac": 27,
- "solar": 39,
- "reroof": 1,
- "pool_spa": 1,
- "heat_pump": 267,
- "utilities": 1110,
- "commercial": 20
}, - "address": {
- "street_no": "2800",
- "street": "COTTONWOOD DR",
- "city": "SAN BRUNO",
- "zip_code": "94066",
- "state": "CA",
- "address_id": "asd8a8b19",
- "latlng": [
- 37.37619,
- -121.869064
]
}
}
], - "page": 1,
- "size": 1
}
Retrieves all permits associated with a single contractor.
A list of permits associated with the contractor and grouped by address
Validation Error
{- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "caf3b9d5ce317d53",
- "description": "Battery backup",
- "number": "RE2303928",
- "jurisdiction": "Berkeley",
- "type": "Re) - electrical - 1 & 2 unit residential (building)",
- "fees": 619.6,
- "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,
- "contractor_id": "KOm4dMLIuT",
- "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"
}, - "tags": [
- "solar",
- "utilities",
- "residential",
- "solar_battery_storage"
]
}, - {
- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "71c02bd70f7ce1c9",
- "description": "Install 27 kwh back-up batteries in cabinet ",
- "number": "E2304692",
- "jurisdiction": "Berkeley",
- "type": "E) - electrical - 3+ residential units or commercial",
- "fees": 615.06,
- "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,
- "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"
}, - "tags": [
- "solar",
- "utilities",
- "residential",
- "solar_battery_storage"
]
}, - {
- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "9525a96a93e0cdb7",
- "description": "Install 27 kwh back-up batteries in cabinet",
- "number": "B2303829",
- "jurisdiction": "Berkeley",
- "job_value": 5001,
- "type": "Building alteration: 3+ residential units or commercial",
- "fees": 79.53,
- "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,
- "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"
}, - "tags": [
- "solar",
- "sitework",
- "residential",
- "solar_battery_storage",
- "commercial"
]
}
], - "page": 1,
- "size": 3
}
Returns contractor monthly metrics filtered by contractor ID, property type, and tags. Metrics include permit count, average duration, and average pass rate.
Contractor monthly metrics
Contractor not found
Validation Error
{- "items": [
- {
- "date": "2022-01-01",
- "property_type": "residential",
- "tag": "solar",
- "permit_count": 10,
- "avg_job_value": "10000",
- "total_job_value": "100000",
- "avg_construction_duration": 100,
- "avg_inspection_pass_rate": "95"
}, - {
- "date": "2022-02-01",
- "property_type": "residential",
- "tag": "solar",
- "permit_count": 4,
- "avg_job_value": "10000",
- "total_job_value": "100000",
- "avg_construction_duration": 30,
- "avg_inspection_pass_rate": "45"
}
], - "page": 1,
- "size": 10
}
Returns contractor monthly metrics filtered by contractor ID, property type, and tags. Metrics include permit count, average duration, and average pass rate.
Contractor monthly metrics
Contractor not found
Validation Error
{- "items": [
- {
- "date": "2022-01-01",
- "property_type": "residential",
- "tag": "solar",
- "permit_count": 10,
- "avg_job_value": "10000",
- "total_job_value": "100000",
- "avg_construction_duration": 100,
- "avg_inspection_pass_rate": "95"
}, - {
- "date": "2022-02-01",
- "property_type": "residential",
- "tag": "solar",
- "permit_count": 4,
- "avg_job_value": "10000",
- "total_job_value": "100000",
- "avg_construction_duration": 30,
- "avg_inspection_pass_rate": "45"
}
], - "page": 1,
- "size": 10
}
Searches for addresses that have at least one associated permit based on the provided text.
A list of addresses that match the search text, ordered by relevance and in USPS notation.
The specified search query didn't match any addresses
Validation Error
{- "items": [
- {
- "street_no": "1232",
- "street": "MARKET ST",
- "city": "SAN FRANCISCO",
- "zip_code": "94103",
- "zip_code_ext": "1234",
- "state": "CA",
- "geo_id": "1",
- "name": "123 Market St, San Francisco, CA",
- "county": "SAN FRANCISCO",
- "jurisdiction": "SAN FRANCISCO",
- "lat": 37.7749,
- "long": -122.41
}, - {
- "street_no": "1233",
- "street": "MARKET ST",
- "city": "SAN FRANCISCO",
- "zip_code": "94103",
- "zip_code_ext": "1234",
- "state": "CA",
- "geo_id": "2",
- "name": "1233 Market St, San Francisco, CA",
- "county": "SAN FRANCISCO",
- "jurisdiction": "SAN FRANCISCO",
- "lat": 37.7749,
- "long": -122.41
}, - {
- "street_no": "1234",
- "street": "MARKET ST",
- "city": "SAN FRANCISCO",
- "zip_code": "94103",
- "zip_code_ext": "1234",
- "state": "CA",
- "geo_id": "3",
- "name": "1234 Market St, San Francisco, CA",
- "county": "SAN FRANCISCO",
- "jurisdiction": "SAN FRANCISCO",
- "lat": 37.7749,
- "long": -122.41
}
], - "page": 1,
- "size": 3
}
Retrieves all permits associated with a given address.
A list of permits associated with the address.
Validation Error
{- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "caf3b9d5ce317d53",
- "description": "Battery backup",
- "number": "RE2303928",
- "jurisdiction": "Berkeley",
- "type": "Re) - electrical - 1 & 2 unit residential (building)",
- "fees": 619.6,
- "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,
- "contractor_id": "KOm4dMLIuT",
- "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"
}, - "tags": [
- "solar",
- "utilities",
- "residential",
- "solar_battery_storage"
]
}, - {
- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "71c02bd70f7ce1c9",
- "description": "Install 27 kwh back-up batteries in cabinet ",
- "number": "E2304692",
- "jurisdiction": "Berkeley",
- "type": "E) - electrical - 3+ residential units or commercial",
- "fees": 615.06,
- "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,
- "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"
}, - "tags": [
- "solar",
- "utilities",
- "residential",
- "solar_battery_storage"
]
}, - {
- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "9525a96a93e0cdb7",
- "description": "Install 27 kwh back-up batteries in cabinet",
- "number": "B2303829",
- "jurisdiction": "Berkeley",
- "job_value": 5001,
- "type": "Building alteration: 3+ residential units or commercial",
- "fees": 79.53,
- "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,
- "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"
}, - "tags": [
- "solar",
- "sitework",
- "residential",
- "solar_battery_storage",
- "commercial"
]
}
], - "page": 1,
- "size": 3
}
Return residents for a given address geo ID.
Residents for a given address geo ID
The given geo_id doesn't have residents information.
Validation Error
{- "items": [
- {
- "name": "John Doe",
- "email": "john.doe@example.com",
- "phone": "(978) 314-5196",
- "net_worth": "$750,000 to $999,999",
- "income_range": "$150,000 to $299,999",
- "is_homeowner": true,
- "street_no": "123",
- "street": "Main St",
- "city": "New York",
- "state": "NY",
- "zip_code": "10001"
}, - {
- "name": "Jane Doe",
- "email": "jane.doe@example.com",
- "phone": "(310) 555-7890",
- "net_worth": "$500,000 to $749,999",
- "income_range": "$100,000 to $149,999",
- "is_homeowner": false,
- "street_no": "456",
- "street": "Ocean Ave",
- "city": "Los Angeles",
- "state": "CA",
- "zip_code": "90001",
- "zip_code_ext": "1234"
}
], - "page": 1,
- "size": 2
}
Searches for cities based on the provided search term.
A list of cities that match the search text.
The specified search query didn't match any cities
Validation Error
{- "items": [
- {
- "geo_id": "1",
- "name": "SAN FRANCISCO, SAN FRANCISCO, CA",
- "state": "CA"
}, - {
- "geo_id": "2",
- "name": "SAN RAMON, CONTRA COSTA COUNTY, CA",
- "state": "CA"
}, - {
- "geo_id": "3",
- "name": "SAN DIEGO, SAN DIEGO COUNTY, CA",
- "state": "CA"
}
], - "page": 1,
- "size": 3
}
Returns monthly city metrics.
Paginated list of city metrics
Validation Error
{- "items": [
- {
- "date": "2019-08-24",
- "property_type": "string",
- "tag": "string",
- "permit_count": 0,
- "contractor_count": 0,
- "permit_active_count": 0,
- "permit_in_review_count": 0,
- "total_job_value": "string",
- "avg_construction_duration": 0,
- "avg_approval_duration": 0,
- "avg_inspection_pass_rate": "string",
- "geo_id": "string"
}
], - "page": 0,
- "size": 0,
- "next_page": 0
}
Retrieves all permits associated with a given city.
A list of permits associated with the city.
Validation Error
{- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "caf3b9d5ce317d53",
- "description": "Battery backup",
- "number": "RE2303928",
- "jurisdiction": "Berkeley",
- "type": "Re) - electrical - 1 & 2 unit residential (building)",
- "fees": 619.6,
- "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,
- "contractor_id": "KOm4dMLIuT",
- "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"
}, - "tags": [
- "solar",
- "utilities",
- "residential",
- "solar_battery_storage"
]
}, - {
- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "71c02bd70f7ce1c9",
- "description": "Install 27 kwh back-up batteries in cabinet ",
- "number": "E2304692",
- "jurisdiction": "Berkeley",
- "type": "E) - electrical - 3+ residential units or commercial",
- "fees": 615.06,
- "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,
- "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"
}, - "tags": [
- "solar",
- "utilities",
- "residential",
- "solar_battery_storage"
]
}, - {
- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "9525a96a93e0cdb7",
- "description": "Install 27 kwh back-up batteries in cabinet",
- "number": "B2303829",
- "jurisdiction": "Berkeley",
- "job_value": 5001,
- "type": "Building alteration: 3+ residential units or commercial",
- "fees": 79.53,
- "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,
- "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"
}, - "tags": [
- "solar",
- "sitework",
- "residential",
- "solar_battery_storage",
- "commercial"
]
}
], - "page": 1,
- "size": 3
}
Return city details and related location hierarchy.
City details and related location hierarchy.
The given geo_id didn't match any cities
Validation Error
{- "geo_id": "1",
- "name": "SAN FRANCISCO, SAN FRANCISCO, CA",
- "counties": {
- "SAN FRANCISCO": "Ra4e342yy",
- "SAN RAMON": "2Ra4eyaa"
}, - "jurisdictions": {
- "SAN FRANCISCO": "12a4Dxy"
}, - "zipcodes": [
- "94705",
- "94706"
], - "state": "CA"
}
Searches for counties based on the provided search term.
A list of counties that match the search text.
The specified search query didn't match any counties
Validation Error
{- "items": [
- {
- "geo_id": "11",
- "name": "Los Angeles County, CA",
- "state": "CA"
}, - {
- "geo_id": "12",
- "name": "Harris County, TX",
- "state": "TX"
}, - {
- "geo_id": "13",
- "name": "Cook County, IL",
- "state": "IL"
}
], - "page": 1,
- "size": 3
}
Returns monthly county metrics.
Paginated list of county metrics
Validation Error
{- "items": [
- {
- "date": "2019-08-24",
- "property_type": "string",
- "tag": "string",
- "permit_count": 0,
- "contractor_count": 0,
- "permit_active_count": 0,
- "permit_in_review_count": 0,
- "total_job_value": "string",
- "avg_construction_duration": 0,
- "avg_approval_duration": 0,
- "avg_inspection_pass_rate": "string",
- "geo_id": "string"
}
], - "page": 0,
- "size": 0,
- "next_page": 0
}
Retrieves all permits associated with a given county.
A list of permits associated with the county.
Validation Error
{- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "caf3b9d5ce317d53",
- "description": "Battery backup",
- "number": "RE2303928",
- "jurisdiction": "Berkeley",
- "type": "Re) - electrical - 1 & 2 unit residential (building)",
- "fees": 619.6,
- "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,
- "contractor_id": "KOm4dMLIuT",
- "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"
}, - "tags": [
- "solar",
- "utilities",
- "residential",
- "solar_battery_storage"
]
}, - {
- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "71c02bd70f7ce1c9",
- "description": "Install 27 kwh back-up batteries in cabinet ",
- "number": "E2304692",
- "jurisdiction": "Berkeley",
- "type": "E) - electrical - 3+ residential units or commercial",
- "fees": 615.06,
- "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,
- "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"
}, - "tags": [
- "solar",
- "utilities",
- "residential",
- "solar_battery_storage"
]
}, - {
- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "9525a96a93e0cdb7",
- "description": "Install 27 kwh back-up batteries in cabinet",
- "number": "B2303829",
- "jurisdiction": "Berkeley",
- "job_value": 5001,
- "type": "Building alteration: 3+ residential units or commercial",
- "fees": 79.53,
- "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,
- "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"
}, - "tags": [
- "solar",
- "sitework",
- "residential",
- "solar_battery_storage",
- "commercial"
]
}
], - "page": 1,
- "size": 3
}
Return county details and related location hierarchy.
OK
The given geo_id didn't match any counties
Validation Error
{- "geo_id": "1",
- "name": "SAN FRANCISCO, SAN FRANCISCO, CA",
- "cities": {
- "SAN FRANCISCO": "Ra4e342yy",
- "SAN RAMON": "2Ra4eyaa"
}, - "jurisdictions": {
- "SAN FRANCISCO": "12a4Dxy"
}, - "zipcodes": [
- "94705",
- "94706"
], - "state": "CA"
}
Searches for jurisdictions based on the provided search term.
A list of jurisdictions that match the search text.
The specified search query didn't match any jurisdictions
Validation Error
{- "items": [
- {
- "geo_id": "1",
- "name": "Sanford, FL",
- "state": "FL"
}, - {
- "geo_id": "2",
- "name": "Abilene, TX",
- "state": "TX"
}, - {
- "geo_id": "3",
- "name": "Albany, CA",
- "state": "CA"
}
], - "page": 1,
- "size": 3
}
Returns monthly jurisdiction metrics.
Paginated list of jurisdiction metrics
Validation Error
{- "items": [
- {
- "date": "2019-08-24",
- "property_type": "string",
- "tag": "string",
- "permit_count": 0,
- "contractor_count": 0,
- "permit_active_count": 0,
- "permit_in_review_count": 0,
- "total_job_value": "string",
- "avg_construction_duration": 0,
- "avg_approval_duration": 0,
- "avg_inspection_pass_rate": "string",
- "geo_id": "string"
}
], - "page": 0,
- "size": 0,
- "next_page": 0
}
Retrieves all permits associated with a given jurisdiction.
A list of permits associated with the jurisdiction.
Validation Error
{- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "caf3b9d5ce317d53",
- "description": "Battery backup",
- "number": "RE2303928",
- "jurisdiction": "Berkeley",
- "type": "Re) - electrical - 1 & 2 unit residential (building)",
- "fees": 619.6,
- "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,
- "contractor_id": "KOm4dMLIuT",
- "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"
}, - "tags": [
- "solar",
- "utilities",
- "residential",
- "solar_battery_storage"
]
}, - {
- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "71c02bd70f7ce1c9",
- "description": "Install 27 kwh back-up batteries in cabinet ",
- "number": "E2304692",
- "jurisdiction": "Berkeley",
- "type": "E) - electrical - 3+ residential units or commercial",
- "fees": 615.06,
- "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,
- "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"
}, - "tags": [
- "solar",
- "utilities",
- "residential",
- "solar_battery_storage"
]
}, - {
- "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_assess_market_value": 1050000,
- "property_lot_size": 4000,
- "property_building_area": 1000,
- "property_story_count": 1,
- "property_unit_count": 1,
- "property_year_built": 1970,
- "id": "9525a96a93e0cdb7",
- "description": "Install 27 kwh back-up batteries in cabinet",
- "number": "B2303829",
- "jurisdiction": "Berkeley",
- "job_value": 5001,
- "type": "Building alteration: 3+ residential units or commercial",
- "fees": 79.53,
- "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,
- "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"
}, - "tags": [
- "solar",
- "sitework",
- "residential",
- "solar_battery_storage",
- "commercial"
]
}
], - "page": 1,
- "size": 3
}
Return jurisdiction details and related location hierarchy.
OK
The given geo_id didn't match any jurisdictions
Validation Error
{- "geo_id": "1",
- "name": "SAN FRANCISCO, SAN FRANCISCO, CA",
- "cities": {
- "SAN FRANCISCO": "Ra4e342yy",
- "SAN RAMON": "2Ra4eyaa"
}, - "counties": {
- "SAN FRANCISCO": "12a4Dxy"
}, - "zipcodes": [
- "94705",
- "94706"
], - "state": "CA"
}
Searches for US states based on the provided search term.
A list of states that match the search term.
The specified search query didn't match any states
Validation Error
{- "items": [
- {
- "geo_id": "CA",
- "name": "CALIFORNIA"
}, - {
- "geo_id": "TX",
- "name": "TEXAS"
}, - {
- "geo_id": "MT",
- "name": "MONTANA"
}
], - "page": 1,
- "size": 3
}
Searches for zipcodes based on the provided search term.
A list of zipcodes that match the search code.
The specified search query didn't match any zipcodes
Validation Error
{- "items": [
- {
- "geo_id": "94705",
- "state": "CA"
}, - {
- "geo_id": "94704",
- "state": "CA"
}, - {
- "geo_id": "73301-5678",
- "state": "TX"
}
], - "page": 1,
- "size": 3
}