API

Monetary fields (job_value, fees, total_job_value, avg_job_value, property_assess_market_value, assess_market_value) are integers expressed in cents — divide by 100 for the dollar amount (e.g. 2500000 = $25,000).

Permits

Field Name	Data Type	Description	Example
id	`string`	The permit identifier	”caf3b9d5ce317d53”
number	`string`	The permit number provided by the jurisdiction — Source: Permit Jurisdiction	”No-15837”
jurisdiction	`string`	The jurisdiction where the permit was filed — Source: Permit Jurisdiction	”City of Oakland”
description	`string`	The free-form description of the work on the permit — Source: Permit Jurisdiction	”Solar panel installation”
job_value	`integer`	The reported job value on the permit, in cents — Source: Permit Jurisdiction	2500000
type	`string`	The type of permit — Source: Permit Jurisdiction	”Residential accessory structure”
subtype	`string`	The subtype of permit — Source: Permit Jurisdiction	”garage”
fees	`integer`	The fees charged by the jurisdiction, in cents — Source: Permit Jurisdiction	15000
status	`string`	The status of the permit	”active”
file_date	`string`	The date the permit was filed (YYYY-MM-DD) — Source: Permit Jurisdiction	”2023-01-01”
issue_date	`string`	The date the permit was issued (YYYY-MM-DD) — Source: Permit Jurisdiction	”2023-01-31”
final_date	`string`	The date the permit was finalized (YYYY-MM-DD) — Source: Permit Jurisdiction	”2023-06-01”
start_date	`string`	The earliest of `file_date`, `issue_date`, and `final_date`	”2023-01-01”
end_date	`string`	The latest of `file_date`, `issue_date`, and `final_date`	”2023-06-01”
total_duration	`integer`	Number of days from `start_date` to `end_date`	151
construction_duration	`integer`	Number of days it took to complete the project	120
approval_duration	`integer`	Number of days it took to approve the permit	30
inspection_pass_rate	`integer`	The inspection pass rate as a percentage (0-100)	95
contractor_id	`string`	The unique ID of the contractor associated with the permit	”c452b7d5cf317a76”
tags	`array`	A list of tags associated with the permit	`["solar", "residential"]`
address	`object`	The property’s address
geo_ids	`object`	Geographic identifiers
property_census_tract	`string`	The property’s census tract	”06075000100”
property_congressional_district	`string`	The property’s congressional district	”11”
property_type	`string`	The property’s type	”Residential”
property_type_detail	`string`	The property’s sub-classification	”Single Family Home”
property_legal_owner	`string`	The property’s legal owner	”Robert Johnson”
property_owner_type	`string`	The property’s owner classification	”individual”
property_lot_size	`integer`	The property’s lot size (in square feet)	5000
property_building_area	`integer`	The property’s building area (in square feet)	1250
property_story_count	`integer`	The property’s number of stories	2
property_unit_count	`integer`	The property’s number of units	1
property_year_built	`integer`	The property’s year built	1978
property_assess_market_value	`integer`	The property’s assessed market value, in cents	75000000

Properties

Served by the /properties endpoints (beta). One record per property, with its permit history summarized on the record. The trust object and its fields are present only on absence-class search responses (a --prefixed tag in permit_tags).

Field Name	Data Type	Description	Example
id	`string`	The property’s ID (its address geolocation ID)	“cmVzMTIzNDU2”
street_no	`string`	Street number of the address	”123”
street	`string`	Street name of the address	”Main St”
city	`string`	City of the address	”San Francisco”
city_id	`string`	The city’s geolocation ID	”Y2l0eTk4NzY”
zip_code	`string`	ZIP code of the address	”94103”
zip_code_ext	`string`	ZIP+4 extension of the address	”1234”
county	`string`	County of the address	”San Francisco County”
county_id	`string`	The county’s geolocation ID	”Y291bnR5NTQz”
state	`string`	State of the address	”CA”
lat	`number`	Latitude of the address	37.7749
long	`number`	Longitude of the address	-122.4194
permit_count	`integer`	Count of permits linked to the property	12
untagged_permit_count	`integer`	Count of the property’s permits carrying no canonical tag	2
total_job_value	`integer`	Sum of permit job values, in cents	250000000
contractor_count	`integer`	Distinct contractors across the property’s permits	5
tags	`array`	Distinct canonical tags present on the property’s permits	`["solar", "roofing"]`
statuses	`array`	Distinct permit statuses present, including `unknown`	`["final", "active"]`
tag_status_pairs	`array`	Distinct tag:status pairs present	`["solar:final"]`
tag_tally	`object`	Map of tag → permit count	`{"solar": 2}`
last_date_by_tag	`object`	Map of tag → latest permit start_date	`{"solar": "2023-06-01"}`
last_date_by_status	`object`	Map of status → latest permit start_date	`{"final": "2023-06-01"}`
last_date_by_pair	`object`	Map of tag:status → latest permit start_date	`{"solar:final": "2023-06-01"}`
last_unfinaled_date_by_tag	`object`	Map of tag → latest unfinaled permit start_date	`{"roofing": "2024-02-15"}`
last_permit_date	`string`	Latest permit start_date across all the property’s permits; null when never permitted	”2024-02-15”
apn	`string`	Assessor parcel number (returned for mapping; not searchable)	“1234-056-789”
property_type	`string`	The property’s type	”residential”
property_type_detail	`string`	The property’s sub-classification	”Single Family Home”
year_built	`integer`	Year the property was built	1978
lot_size	`integer`	Lot size (in square feet)	5000
building_area	`integer`	Building area (in square feet)	1250
story_count	`integer`	Number of stories	2
unit_count	`integer`	Number of units	1
assess_market_value	`integer`	Assessed market value, in cents	75000000
legal_owner	`string`	The property’s legal owner	”Robert Johnson”
owner_type	`string`	The property owner’s classification	”individual”
trust	`object`	Per-row absence-confidence fields; absence-class responses only
trust.coverage_tier	`string`	Permit coverage bucket for the row’s jurisdiction: high, medium, low	”high”
trust.unresolved_rate	`number`	Share of the jurisdiction’s permits of the tag that never linked to an address (0–1)	0.04
trust.data_horizon	`string`	Most recent date past which “no permit since D” is under-observed (YYYY-MM-DD)	“2026-03-15”
trust.horizon_basis	`string`	How the horizon was estimated: measured, pooled, prior	”measured”
trust.footprint_basis	`string`	Whether coverage suppression could resolve the row’s geography: matched, unknown	”matched”
trust.flags	`array`	Row-level caveats	`["since_d_beyond_horizon"]`

Absence-class search responses also carry a page-level trust_summary object:

Field Name	Data Type	Description	Example
expected_miss_rate	`number`	Estimated probability that a returned “no permit” answer is wrong due to ingestion lag (0–1)	0.02
rows_flagged	`integer`	Number of rows on the page carrying a trust flag	3
row_weighted_unresolved_rate	`number`	Row-weighted mean unresolved_rate across the page (0–1)	0.05
suppressed_scopes	`integer`	Number of coverage scopes removed from the result	1

Contractors

Field Name	Data Type	Description	Example
id	`string`	The contractor ID	”c452b7d5cf317a76”
license	`string`	The contractor license number — Source: Permit Jurisdiction	”123456”
name	`string`	The contractor name — Source: Permit Jurisdiction	”John Builder”
business_name	`string`	The contractor’s business name — Source: Permit Jurisdiction	”Builder Co”
business_type	`string`	The type of business: JointVenture, Corporation, Partnership, Limited Liability, Sole Owner	”Corporation”
classification	`string`	The contractor’s classification/certification	”B - General Building”
classification_derived	`array`	Array of derived contractor classifications	`["General Building"]`
license_issue_date	`string`	The license issue date (YYYY-MM-DD) — Source: Permit Jurisdiction	”2015-04-01”
license_exp_date	`string`	The license expiration date (YYYY-MM-DD) — Source: Permit Jurisdiction	”2025-04-01”
license_inact_date	`string`	Date the license became inactive (YYYY-MM-DD) — Source: Permit Jurisdiction	”2020-01-01”
license_act_date	`string`	Date the license became active (YYYY-MM-DD) — Source: Permit Jurisdiction	”2015-04-01”
primary_phone	`string`	The contractor’s primary phone number	”123-456-7890”
primary_email	`string`	The contractor’s primary email	”info@builderco.com”
phone	`string`	The contractor’s phone number(s)	“123-456-7890”
email	`string`	The contractor’s email(s)	“info@builderco.com”
website	`string`	The contractor’s website	”builderco.com”
dba	`string`	Doing Business As name for the contractor	”Builder Co”
sic	`string`	Standard Industrial Classification (SIC) code	”1521”
naics	`string`	North American Industry Classification System (NAICS) code	”236118”
linkedin_url	`string`	LinkedIn URL of the contractor	”linkedin.com/company/builderco”
revenue	`string`	Annual revenue of the contractor’s business	”$1M-$5M”
employee_count	`string`	Number of employees working for the contractor	”10-50”
primary_industry	`string`	Primary industry in which the contractor operates	”Construction”
review_count	`integer`	Number of reviews the contractor has received	42
rating	`number`	Rating of the contractor based on reviews	4.7
status_tally	`object`	Summary of status counts for the contractor’s work (active, final, unknown, inactive, in_review)	`{"active": 5, "final": 10}`
tag_tally	`object`	Summary of tag counts for the contractor’s work	`{"solar": 3}`
permit_count	`integer`	The total number of permits	100
avg_job_value	`integer`	The average job value of all permits, in cents	2500000
total_job_value	`integer`	The total job value of all permits, in cents	250000000
avg_construction_duration	`integer`	The average construction duration in days	120
avg_inspection_pass_rate	`integer`	The average inspection pass rate as a percentage (0-100)	95
first_seen_date	`string`	Date the contractor was first seen in the system (YYYY-MM-DD)	“2018-06-15”
address	`object`	The contractor’s address (street_no, street, city, jurisdiction, zip_code, zip_code_ext, state, latlng)

Residents

Field Name	Data Type	Description	Example
name	`string`	Name of the resident	”Jane Doe”
personal_emails	`string`	Email(s) of the resident	”jane.doe@example.com”
phone	`string`	Phone number of the resident	”123-456-7890”
linkedin_url	`string`	LinkedIn URL of the resident	”linkedin.com/in/janedoe”
net_worth	`string`	Net worth range of the resident	”1,000,000-2,499,999”
income_range	`string`	Income range of the resident	”150,000-199,999”
is_homeowner	`boolean`	Whether the resident is a homeowner	true
street_no	`string`	Street number of the resident’s address	”123”
street	`string`	Street name of the resident’s address	”Main St”
city	`string`	City of the resident’s address	”Anytown”
state	`string`	State of the resident’s address	”CA”
zip_code	`string`	Zip code of the resident’s address	”12345”
zip_code_ext	`string`	Zip code extension of the resident’s address	”6789”

Metrics

Metrics are returned in current and monthly variants across geographies (address, city, county, jurisdiction, state) and contractors. Fields common to the metrics schemas are listed below; the notes column indicates where a field is variant-specific.

Field Name	Data Type	Description	Example
geo_id	`string`	Unique identifier for the entity	”CA”
tag	`string`	Specific tag or category for the metrics	”solar”
permit_count	`integer`	Total number of permits issued	100
permit_active_count	`integer`	Total number of permits in active status — Current metrics only	50
permit_in_review_count	`integer`	Total number of permits in review status — Current metrics only	10
contractor_count	`integer`	Total number of unique contractors	25
avg_construction_duration	`integer`	Average duration of construction projects in days	120
avg_approval_duration	`integer`	Average duration of permit approval process in days	30
total_job_value	`integer`	Total value of all jobs/permits, in cents	250000000
avg_inspection_pass_rate	`integer`	Average inspection pass rate as a percentage (0-100)	95
property_type	`string`	Type of property (e.g. residential, commercial) — City/county/jurisdiction metrics only (not address)	“residential”
date	`string`	The month for which the metrics are calculated (YYYY-MM-DD) — Monthly metrics only	”2024-01-01”

Geographies

Field Name	Data Type	Description	Example
state	`string`	The state of the property.	”CA”
county	`string`	The county of the property.	”Santa Clara County”
city	`string`	The city of the property.	”San Jose”
zip_code	`string`	The ZIP code of the property.	”95112”

Overview

Shovels Online

Shovels API

Shovels CLI

Shovels for Google Sheets

Tutorials

Troubleshooting

Platform Reference

Shovels Foundations