API

All fields, parameters, and objects available in the Shovels API schema.

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	”[e-mail]”
phone	string	The contractor’s phone number(s)	“123-456-7890”
email	string	The contractor’s email(s)	“[e-mail]”
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	”[e-mail]”
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”