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

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

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

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

Contractors

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

Residents

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

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	Notes
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	50	Current metrics only
permit_in_review_count	`integer`	Total number of permits in review status	10	Current metrics only
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)	“residential”	City/county/jurisdiction metrics only (not address)
date	`string`	The month for which the metrics are calculated (YYYY-MM-DD)	“2024-01-01”	Monthly metrics only

Geographies

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

Shovels Online

Shovels API

Shovels CLI

Tutorials

Troubleshooting

Platform Reference

Shovels Foundations