> ## Documentation Index > Fetch the complete documentation index at: https://docs.shovels.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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). | 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 | 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 | | 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](mailto: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](mailto: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 | | 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](mailto: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 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 | | 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 |