> ## 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.

<Note>
  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).
</Note>

<Accordion title="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 |
</Accordion>

<Accordion title="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 |
</Accordion>

<Accordion title="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](mailto:info@builderco.com)" |
  | phone | `string` | The contractor's phone number(s) | "123-456-7890" |
  | email | `string` | The contractor's email(s) | "[info@builderco.com](mailto: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) | |
</Accordion>

<Accordion title="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](mailto: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" |
</Accordion>

<Accordion title="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" |
</Accordion>

<Accordion title="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" |
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.