openapi: 3.1.0 info: title: The Shovels API v2 description: "\nThe Shovels REST API makes it easy for technology developers in\ \ the property, climate, and\nconstruction industries to access detailed information\ \ about building permits, contractors and\nconstruction activity. Our API is designed\ \ to be intuitive and fast. We look forward to seeing what\nyou build with it:\n\ [let us know](https://docs.google.com/forms/d/e/1FAIpQLSfs5Z6NZyPdnRpL96bMduH95OhfFZgLz9Hkc0-Y7pukUxSLxQ/viewform)\n\ and we'll check it out!\n\n## Key Features\nThe API offers access to two primary\ \ objects: **Permits** and **Contractors**.\n- **Permits**: Official documents\ \ issued by city or county authorities required before commencing\nconstruction\ \ or alterations to a building.\n- **Contractors**: Skilled professionals in the\ \ building trades who undertake permitted\nconstruction projects on various properties.\n\ \nAnd some additional resources:\n- **Lists**: Endpoints for predefined values\ \ like tags and property types for query parameters.\n- **Addresses**: Endpoint\ \ for searching and resolving valid US addresses.\n- **Meta**: Endpoints for metadata\ \ about the API and the data behind it.\n\n## Getting started\n\nTo begin using\ \ the API, please contact our sales team at\n[sales@shovels.ai](mailto:sales@shovels.ai)\ \ or grab a\n[free API key](https://app.shovels.ai/create-account/).\n\n> **Info**:\ \ The free API key has a limited number of calls.\nIf you hit the limit and need\ \ more, please reach out to [sales@shovels.ai](mailto:sales@shovels.ai)\nor call\ \ us at [1-800-511-7457](tel:+18005117457).\n\n### Authentication\nOur API uses\ \ a straightforward header-based authentication method:\n```\nX-API-Key: YOUR_API_KEY_HERE\n\ ```\n\nExample Request:\n\n```sh\ncurl -X GET \"https://api.shovels.ai/v2/meta/release\"\ \ \\\n -H \"X-API-Key: YOUR_API_KEY_HERE\"\n```\n\n## API Details\n\n###\ \ Quick Overview\n\nA few quick details about our API:\n\n| Type \ \ | Description \ \ |\n|---------------------|----------------------------------------------------------------------------|\n\ | SSL only | We require that all requests are done over SSL. \ \ |\n| UTF-8 encoding | We use UTF-8 everywhere. \ \ |\n| Method | GET\ \ for all read calls. |\n|\ \ Date format | All dates in the API are strings in the following format:\ \ YYYY-MM-DD. |\n\n### Response Types\n\nThe API supports the following response\ \ codes:\n\n| Code | Description |\n|------|-------------|\n| **200 OK** | Everything\ \ worked as expected. |\n| **400 Bad Request** | There was something wrong with\ \ your request. Double-check your input. |\n| **401 Unauthorized** | You need\ \ to log in to access this. Make sure your API key is correct. |\n| **402 Payment\ \ Required** | Credit or trial limit exceeded. Response includes an upgrade link.\ \ |\n| **403 Forbidden** | You don't have permission to access this. |\n| **404\ \ Not Found** | We couldn't find what you're looking for. Check the URL or resource\ \ ID. |\n| **422 Unprocessable Entity** | There's an issue with the data you sent.\ \ Check [Error Handling](#error-handling) if you get this error. |\n|\ \ **429 Too Many Requests** | You're sending requests too quickly. Slow down and\ \ try again later. |\n| **500 Internal Server Error** | Yikes, something went\ \ wrong on our end. Please let us know at [support@shovels.ai](support@shovels.ai)\ \ |\n\n### Data Format\n\nThe API returns data in JSON format, either as pages\ \ or single objects.\n\nPaginated responses have the following structure:\n```json\n\ {\n \"items\": [...],\n \"size\": 50,\n \"next_cursor\": \"eyJkYXR...\" | null\n\ }\n```\nWhere objects are returned as an array in the 'items' field.\n\n### Cursor-Based\ \ Pagination\n\nThe API uses cursor-based pagination for all paginated endpoints.\ \ This method uses an opaque\ncursor token to maintain your position in the result\ \ set, offering better performance,\nconsistency, and stability, especially for\ \ large datasets.\n\n```json\n{\n \"items\": [...],\n \"size\": 50,\n \"next_cursor\"\ : \"eyJkYXR.lIjoiMjA.yMy0\"\n}\n```\n\nTo use cursor-based pagination:\n- For\ \ the first page: Simply make a request without any pagination parameters (or\ \ optionally\n specify `size` to control page size)\n- For subsequent pages:\ \ Include the `next_cursor` value from the previous response using the\n `cursor`\ \ parameter\n\nExample:\n```\nGET /v2/permits/search?size=10\nGET /v2/permits/search?size=10&cursor=eyJkYXR.lIjoiMjA.yMy0\n\ ```\n\nWhen there are no more results, the `next_cursor` value will be `null`.\n\ \n### Versioning\n\nThe current version of the API is v2, which is reflected in\ \ the endpoints URL structure:\n`/v2/`. We plan to evolve our API by releasing\ \ new versions to ensure backward compatibility while\nmaintaining a steady pace\ \ of continuous improvements.\n\n### Error Handling\n\nProper error messages and\ \ HTTP codes are provided to help you troubleshoot issues effectively. Refer\n\ to the [Response Types](#response-types) section for an overview of HTTP error\ \ codes and how to\nhandle them. Below we describe how to interpret HTTP 422 code.\n\ \n#### 422 Unprocessable Entity\nA 422 Unprocessable Entity response occurs when\ \ the server understands the request but cannot\nprocess it due to invalid data.\ \ This helps you identify issues with your input.\n\nThe response includes:\n\n\ - **loc**: The location of the error. The first value indicates the location and\ \ the second\n specifies the problematic field. Common values for the first value\ \ include:\n - **body**: The error is in the request body.\n - **query**:\ \ The error is in the query parameters.\n - **path**: The error is in the URL\ \ path.\n - **header**: The error is in the request headers.\n- **msg**: A\ \ message describing the error.\n- **type**: The type of error.\n\nThis information\ \ helps you correct your request by pinpointing the exact issue. Here are some\n\ examples:\n\n**Request Body Error**\n```json\n{\n \"detail\": [\n {\n \ \ \"loc\": [\"body\", \"first_name\"],\n \"msg\": \"Field is required\"\ ,\n \"type\": \"value_error.missing\"\n }\n ]\n}\n```\n\n**Query Parameter\ \ Error**\n```json\n{\n \"detail\": [\n {\n \"loc\": [\"query\", \"page\"\ ],\n \"msg\": \"Page must be a positive integer\",\n \"type\": \"type_error.integer\"\ \n }\n ]\n}\n```\n**Path Parameter Error**\n```json\n{\n \"detail\": [\n\ \ {\n \"loc\": [\"path\", \"id\"],\n \"msg\": \"Invalid ID format\"\ ,\n \"type\": \"value_error.id\"\n }\n ]\n}\n```\n**Header Error**\n\ ```json\n{\n \"detail\": [\n {\n \"loc\": [\"header\", \"X-API-Key\"\ ],\n \"msg\": \"API key is missing\",\n \"type\": \"value_error.missing\"\ \n }\n ]\n}\n```\nThese examples show how different types of errors are reported,\ \ helping you to diagnose and fix\nissues in your API requests.\n\n## Credit Limits\n\ \nAPI usage is tracked using credits. Each record returned counts as one credit.\n\ \n### Response Headers\n\nSuccessful JSON responses that return records include\ \ credit headers:\n- `X-Credits-Request`: Credits consumed by this request\n-\ \ `X-Credits-Limit`: Your monthly credit limit (omitted if unlimited)\n- `X-Credits-Remaining`:\ \ Credits remaining in your limit (omitted if unlimited)\n\n### Checking Usage\n\ \nUse `GET /v2/usage` to check your current credit usage:\n\n```json\n{\n \"\ credits_used\": 847293,\n \"credit_limit\": 1000000\n}\n```\n\n### Exceeding\ \ Limits\n\nWhen you exceed your credit limit, the API returns HTTP 402 with a\ \ structured `detail` object:\n\n```json\n{\n \"detail\": {\n \"error\": \"\ Monthly credit limit exceeded.\",\n \"limit\": 1000000,\n \"upgrade_url\"\ : \"https://pay.shovels.ai/p/login/14k6qo1KG7MjdlSaEE\"\n }\n}\n```\n\nWhen a\ \ trial API key exceeds its call limit, HTTP 402 is returned with `detail` as\ \ a plain string containing the upgrade URL inline:\n\n```json\n{\n \"detail\"\ : \"...trial limit message... Self-serve upgrade: https://pay.shovels.ai/p/login/14k6qo1KG7MjdlSaEE\ \ \u2014 ...\"\n}\n```\n\nCredits are calculated on a rolling 30-day window. Usage\ \ older than 30 days automatically falls off.\n" version: 2.0.0 paths: /permits/search: get: tags: - Permits - Permits summary: Search Permits description: Returns a list of matching permits records. Permits should meet ALL of the parameter filters. Multiple parameters are treated as AND queries. Use contractor_classification_derived to filter by contractor's derived classifications (ALL specified values required). operationId: search_permits_permits_search_get security: - APIKeyHeader: [] parameters: - name: permit_from in: query required: true schema: type: string format: date title: Permit From Date description: 'Return permits that started on or after the specified date.This includes all permits with the earliest date (file, issue, or start date) that falls on or after this date. Date format: `YYYY-MM-DD`' description: 'Return permits that started on or after the specified date.This includes all permits with the earliest date (file, issue, or start date) that falls on or after this date. Date format: `YYYY-MM-DD`' - name: permit_to in: query required: true schema: type: string format: date title: Permit To Date description: 'Return permits that started on or before the specified date.This includes all permits with the latest date (file, issue, or end date) that falls on or before this date. Date format: `YYYY-MM-DD`' description: 'Return permits that started on or before the specified date.This includes all permits with the latest date (file, issue, or end date) that falls on or before this date. Date format: `YYYY-MM-DD`' - name: permit_tags in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Permit Tags description: 'Filter by one or more tags. Use ''-'' prefix to exclude tags. Example: ?permit_tags=solar&permit_tags=-roofing (has solar, not roofing).' description: 'Filter by one or more tags. Use ''-'' prefix to exclude tags. Example: ?permit_tags=solar&permit_tags=-roofing (has solar, not roofing).' - name: geo_id in: query required: true schema: type: string title: Geolocation ID description: 'Filter results by geographic area. Accepts: - US state code (e.g. `CA`) - ZIP code (e.g. `90210` or `90210-1234`) - Shovels geolocation ID for an address, city, county, or jurisdiction (e.g. `a4xysKbZwqg`) Resolve addresses and places to geolocation IDs via: - [Search Addresses](/api-reference/addresses/search-addresses) - [Search Cities](/api-reference/cities/search-cities) - [Search Counties](/api-reference/counties/search-counties) - [Search Jurisdictions](/api-reference/jurisdictions/search-jurisdictions) Free-form text such as `"123 Main St"` is not accepted.' description: 'Filter results by geographic area. Accepts: - US state code (e.g. `CA`) - ZIP code (e.g. `90210` or `90210-1234`) - Shovels geolocation ID for an address, city, county, or jurisdiction (e.g. `a4xysKbZwqg`) Resolve addresses and places to geolocation IDs via: - [Search Addresses](/api-reference/addresses/search-addresses) - [Search Cities](/api-reference/cities/search-cities) - [Search Counties](/api-reference/counties/search-counties) - [Search Jurisdictions](/api-reference/jurisdictions/search-jurisdictions) Free-form text such as `"123 Main St"` is not accepted.' - name: permit_has_contractor in: query required: false schema: anyOf: - type: boolean - type: 'null' title: Has Contractor description: 'Filter by contractor presence: `true` returns only permits with a contractor, `false` only permits without one. Omit to apply no filter.' description: 'Filter by contractor presence: `true` returns only permits with a contractor, `false` only permits without one. Omit to apply no filter.' - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size - name: include_count in: query required: false schema: type: boolean description: When true and on the first page (no cursor), include total_count in the response. The count is exact up to 10,000; above that, relation is 'gte'. default: false title: Include Count description: When true and on the first page (no cursor), include total_count in the response. The count is exact up to 10,000; above that, relation is 'gte'. - name: permit_q in: query required: false schema: anyOf: - type: string maxLength: 50 - type: 'null' title: Search Query description: Substring to search for in permit description (case-insensitive). Matches anywhere in the text, including partial words. description: Substring to search for in permit description (case-insensitive). Matches anywhere in the text, including partial words. - name: permit_status in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Permit Status description: 'Filter by one or more statuses: final, in_review, inactive, active.' maxItems: 4 description: 'Filter by one or more statuses: final, in_review, inactive, active.' - name: permit_min_approval_duration in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Permit Approval Duration description: Filter by the minimum permit approval duration in days. description: Filter by the minimum permit approval duration in days. - name: permit_min_construction_duration in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Project Construction Duration description: Filter by the minimum project construction duration in days. description: Filter by the minimum project construction duration in days. - name: permit_min_inspection_pr in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Inspection Pass Rate description: Filter by the minimum inspection pass rate. description: Filter by the minimum inspection pass rate. - name: permit_min_job_value in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Job Value description: Filter by the minimum job value, in cents (e.g. 5000000 = $50,000). description: Filter by the minimum job value, in cents (e.g. 5000000 = $50,000). - name: permit_min_fees in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Permit Fees description: Filter by minimum permit fees, in cents (e.g. 5000000 = $50,000). description: Filter by minimum permit fees, in cents (e.g. 5000000 = $50,000). - name: property_type in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Property Type description: 'Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational. Repeat the key to match any of several types (e.g. `?property_type=residential&property_type=commercial`).' description: 'Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational. Repeat the key to match any of several types (e.g. `?property_type=residential&property_type=commercial`).' - name: property_min_market_value in: query required: false schema: anyOf: - type: integer - type: 'null' title: Mininum Property Market Value description: Minimum assessed market value of the property, in cents (e.g. 5000000 = $50,000). description: Minimum assessed market value of the property, in cents (e.g. 5000000 = $50,000). - name: property_min_building_area in: query required: false schema: anyOf: - type: integer - type: 'null' title: Mininum Property Building Area description: Minimum total building area in sq ft. description: Minimum total building area in sq ft. - name: property_min_lot_size in: query required: false schema: anyOf: - type: integer - type: 'null' title: Mininum Property Lot Size description: Minimum size of the property lot in sq ft. description: Minimum size of the property lot in sq ft. - name: property_min_story_count in: query required: false schema: anyOf: - type: integer - type: 'null' title: Mininum Property Story Count description: Minimum number of property stories. description: Minimum number of property stories. - name: property_min_unit_count in: query required: false schema: anyOf: - type: integer - type: 'null' title: Mininum Property Unit Count description: Minimum number of property units description: Minimum number of property units - name: contractor_classification_derived in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Contractor Classification Derived description: 'Filter by derived contractor classifications. Use ''-'' prefix to exclude. Example: ?classification_derived=electrical&classification_derived=-hvac. Returns results containing ALL specified classifications. Possible values: concrete_and_paving, demolition_and_excavation, electrical, fencing_and_glazing, framing_and_carpentry, general_building_contractor, general_engineering_contractor, hvac, landscaping_and_outdoor_work, other, plumbing, roofing, specialty_trades.' description: 'Filter by derived contractor classifications. Use ''-'' prefix to exclude. Example: ?classification_derived=electrical&classification_derived=-hvac. Returns results containing ALL specified classifications. Possible values: concrete_and_paving, demolition_and_excavation, electrical, fencing_and_glazing, framing_and_carpentry, general_building_contractor, general_engineering_contractor, hvac, landscaping_and_outdoor_work, other, plumbing, roofing, specialty_trades.' - name: contractor_name in: query required: false schema: anyOf: - type: string minLength: 3 - type: 'null' title: Contractor Name description: "Filter by contractor's name or business name (partial match\ \ supported). Must be at least 3 characters \u2014 shorter patterns cannot\ \ use the trigram index and would force a sequential scan." description: "Filter by contractor's name or business name (partial match\ \ supported). Must be at least 3 characters \u2014 shorter patterns cannot\ \ use the trigram index and would force a sequential scan." - name: contractor_website in: query required: false schema: anyOf: - type: string - type: 'null' title: Contractor Website description: Filter by contractor's website. Don't include the http(s):// prefix. description: Filter by contractor's website. Don't include the http(s):// prefix. - name: contractor_min_total_job_value in: query required: false schema: anyOf: - type: integer - type: 'null' title: Mininum Contractor Total Job Value description: Minimum lifetime job value of the contractor, in cents (e.g. 5000000 = $50,000). description: Minimum lifetime job value of the contractor, in cents (e.g. 5000000 = $50,000). - name: contractor_min_total_permits_count in: query required: false schema: anyOf: - type: integer - type: 'null' title: Mininum Contractor Permits Count description: Minimum lifetime permits count. description: Minimum lifetime permits count. - name: contractor_min_inspection_pr in: query required: false schema: anyOf: - type: integer - type: 'null' title: Mininum Contractor Inspection Pass Rate description: Minimum lifetime inspection pass rate. The value must be an integer between 0 and 100, inclusive. description: Minimum lifetime inspection pass rate. The value must be an integer between 0 and 100, inclusive. - name: contractor_license in: query required: false schema: anyOf: - type: string - type: 'null' title: Contractor License description: Filter by the contractor's license description: Filter by the contractor's license responses: '200': description: A list of permits. content: application/json: schema: $ref: '#/components/schemas/PaginatedPermitsResponse' example: items: - property_census_tract: '101' property_congressional_district: '1' property_type: residential property_type_detail: single_family_home property_legal_owner: OAKLAND HOUSING AUTHORITY property_owner_type: private_owner property_lot_size: 4000 property_building_area: 1000 property_story_count: 1 property_unit_count: 1 property_year_built: 1970 property_assess_market_value: 105000000 id: caf3b9d5ce317d53 number: RE2303928 description: Battery backup description_derived: Battery storage installation jurisdiction: Berkeley job_value: 500000 type: Re) - electrical - 1 & 2 unit residential (building) fees: 61960 status: active file_date: '2023-10-02' issue_date: '2023-10-11' final_date: '2023-12-11' start_date: '2022-10-19' end_date: '2023-12-11' total_duration: 230 construction_duration: 61 approval_duration: 9 inspection_pass_rate: 85 contractor_id: KOm4dMLIuT tags: - solar - utilities - residential - solar_battery_storage address: street_no: '3360' street: DWIGHT WAY city: OAKLAND zip_code: '94704' state: CA latlng: - 37.868443 - -122.24374 geo_ids: address_id: asd8a8b19 city_id: KLais31 county_id: ALa2s33 jurisdiction_id: BLa2s33 - property_census_tract: '101' property_congressional_district: '1' property_type: residential property_type_detail: single_family_home property_legal_owner: OAKLAND HOUSING AUTHORITY property_owner_type: private_owner property_lot_size: 4000 property_building_area: 1000 property_story_count: 1 property_unit_count: 1 property_year_built: 1970 property_assess_market_value: 105000000 id: 71c02bd70f7ce1c9 number: E2304692 description: 'Install 27 kwh back-up batteries in cabinet ' description_derived: Battery storage installation jurisdiction: Berkeley job_value: 750000 type: E) - electrical - 3+ residential units or commercial fees: 61506 status: in_review file_date: '2023-11-29' start_date: '2022-11-29' end_date: '2023-11-29' total_duration: 0 construction_duration: 154 approval_duration: 204 tags: - solar - utilities - residential - solar_battery_storage address: street_no: '544' street: DWIGHT PL city: OAKLAND zip_code: '94704' state: CA latlng: - 37.8671 - -122.24461 geo_ids: address_id: 1sd8a8b19 city_id: KLais31 county_id: ALa2s33 jurisdiction_id: BLa2s33 - property_census_tract: '101' property_congressional_district: '1' property_type: residential property_type_detail: single_family_home property_legal_owner: OAKLAND HOUSING AUTHORITY property_owner_type: private_owner property_lot_size: 4000 property_building_area: 1000 property_story_count: 1 property_unit_count: 1 property_year_built: 1970 property_assess_market_value: 105000000 id: 9525a96a93e0cdb7 number: B2303829 description: Install 27 kwh back-up batteries in cabinet description_derived: Battery storage installation jurisdiction: Berkeley job_value: 500100 type: 'Building alteration: 3+ residential units or commercial' fees: 7953 status: in_review file_date: '2023-11-29' start_date: '2022-11-29' end_date: '2023-11-29' total_duration: 0 construction_duration: 154 approval_duration: 204 tags: - solar - sitework - residential - solar_battery_storage - commercial address: street_no: '544' street: DWIGHT PL city: OAKLAND zip_code: '94704' state: CA latlng: - 37.8671 - -122.24461 geo_ids: address_id: 1sd8a8b19 city_id: KLais31 county_id: ALa2s33 jurisdiction_id: BLa2s33 size: 3 next_cursor: tfZ.9525a96a93e0cdb7 '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /permits: get: tags: - Permits summary: Get Permits By Id description: Returns a list of permits records for given IDs. Results are paginated using cursor-based pagination for efficient navigation. operationId: get_permits_by_id_permits_get security: - APIKeyHeader: [] parameters: - name: id in: query required: true schema: type: array items: type: string title: Permit ID description: Filter by the permit's ID. maxItems: 50 description: Filter by the permit's ID. responses: '200': description: A list of permits. content: application/json: schema: $ref: '#/components/schemas/PaginatedPermitsResponse' example: items: - property_census_tract: '101' property_congressional_district: '1' property_type: residential property_type_detail: single_family_home property_legal_owner: OAKLAND HOUSING AUTHORITY property_owner_type: private_owner property_lot_size: 4000 property_building_area: 1000 property_story_count: 1 property_unit_count: 1 property_year_built: 1970 property_assess_market_value: 105000000 id: caf3b9d5ce317d53 number: RE2303928 description: Battery backup description_derived: Battery storage installation jurisdiction: Berkeley job_value: 500000 type: Re) - electrical - 1 & 2 unit residential (building) fees: 61960 status: active file_date: '2023-10-02' issue_date: '2023-10-11' final_date: '2023-12-11' start_date: '2022-10-19' end_date: '2023-12-11' total_duration: 230 construction_duration: 61 approval_duration: 9 inspection_pass_rate: 85 contractor_id: KOm4dMLIuT tags: - solar - utilities - residential - solar_battery_storage address: street_no: '3360' street: DWIGHT WAY city: OAKLAND zip_code: '94704' state: CA latlng: - 37.868443 - -122.24374 geo_ids: address_id: asd8a8b19 city_id: KLais31 county_id: ALa2s33 jurisdiction_id: BLa2s33 - property_census_tract: '101' property_congressional_district: '1' property_type: residential property_type_detail: single_family_home property_legal_owner: OAKLAND HOUSING AUTHORITY property_owner_type: private_owner property_lot_size: 4000 property_building_area: 1000 property_story_count: 1 property_unit_count: 1 property_year_built: 1970 property_assess_market_value: 105000000 id: 71c02bd70f7ce1c9 number: E2304692 description: 'Install 27 kwh back-up batteries in cabinet ' description_derived: Battery storage installation jurisdiction: Berkeley job_value: 750000 type: E) - electrical - 3+ residential units or commercial fees: 61506 status: in_review file_date: '2023-11-29' start_date: '2022-11-29' end_date: '2023-11-29' total_duration: 0 construction_duration: 154 approval_duration: 204 tags: - solar - utilities - residential - solar_battery_storage address: street_no: '544' street: DWIGHT PL city: OAKLAND zip_code: '94704' state: CA latlng: - 37.8671 - -122.24461 geo_ids: address_id: 1sd8a8b19 city_id: KLais31 county_id: ALa2s33 jurisdiction_id: BLa2s33 - property_census_tract: '101' property_congressional_district: '1' property_type: residential property_type_detail: single_family_home property_legal_owner: OAKLAND HOUSING AUTHORITY property_owner_type: private_owner property_lot_size: 4000 property_building_area: 1000 property_story_count: 1 property_unit_count: 1 property_year_built: 1970 property_assess_market_value: 105000000 id: 9525a96a93e0cdb7 number: B2303829 description: Install 27 kwh back-up batteries in cabinet description_derived: Battery storage installation jurisdiction: Berkeley job_value: 500100 type: 'Building alteration: 3+ residential units or commercial' fees: 7953 status: in_review file_date: '2023-11-29' start_date: '2022-11-29' end_date: '2023-11-29' total_duration: 0 construction_duration: 154 approval_duration: 204 tags: - solar - sitework - residential - solar_battery_storage - commercial address: street_no: '544' street: DWIGHT PL city: OAKLAND zip_code: '94704' state: CA latlng: - 37.8671 - -122.24461 geo_ids: address_id: 1sd8a8b19 city_id: KLais31 county_id: ALa2s33 jurisdiction_id: BLa2s33 size: 3 next_cursor: tfZ.9525a96a93e0cdb7 '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /decisions/search: get: tags: - Decisions summary: Search Decisions description: Returns a list of zoning / land-use decisions matching the supplied filters. Decisions should meet ALL parameter filters (AND logic). Date range (`decision_from`/`decision_to`) and `geo_id` are required. operationId: search_decisions_decisions_search_get security: - APIKeyHeader: [] parameters: - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size - name: include_count in: query required: false schema: type: boolean description: When true and on the first page (no cursor), include total_count in the response. The count is exact up to 10,000; above that, relation is 'gte'. default: false title: Include Count description: When true and on the first page (no cursor), include total_count in the response. The count is exact up to 10,000; above that, relation is 'gte'. - name: decision_from in: query required: true schema: type: string format: date title: Decision From Date description: 'Return decisions with `decision_date` on or after this date. Date format: `YYYY-MM-DD`.' description: 'Return decisions with `decision_date` on or after this date. Date format: `YYYY-MM-DD`.' - name: decision_to in: query required: true schema: type: string format: date title: Decision To Date description: 'Return decisions with `decision_date` on or before this date. Date format: `YYYY-MM-DD`.' description: 'Return decisions with `decision_date` on or before this date. Date format: `YYYY-MM-DD`.' - name: geo_id in: query required: true schema: type: string title: Decisions Geolocation ID description: "Filter decisions by geographic area. Accepts:\n- US state\ \ code (e.g. `CA`)\n- Shovels geolocation ID for an address, city, county,\ \ or jurisdiction (e.g. `a4xysKbZwqg`)\n\nZIP and ZIP+4 inputs are not\ \ supported \u2014 the upstream rezone source emits no ZIP information,\ \ so decisions cannot be filtered by ZIP.\n\nResolve addresses and places\ \ to geolocation IDs via:\n- [Search Addresses](/api-reference/addresses/search-addresses)\n\ - [Search Cities](/api-reference/cities/search-cities)\n- [Search Counties](/api-reference/counties/search-counties)\n\ - [Search Jurisdictions](/api-reference/jurisdictions/search-jurisdictions)\n\ \nFree-form text such as `\"123 Main St\"` is not accepted." description: "Filter decisions by geographic area. Accepts:\n- US state code\ \ (e.g. `CA`)\n- Shovels geolocation ID for an address, city, county, or\ \ jurisdiction (e.g. `a4xysKbZwqg`)\n\nZIP and ZIP+4 inputs are not supported\ \ \u2014 the upstream rezone source emits no ZIP information, so decisions\ \ cannot be filtered by ZIP.\n\nResolve addresses and places to geolocation\ \ IDs via:\n- [Search Addresses](/api-reference/addresses/search-addresses)\n\ - [Search Cities](/api-reference/cities/search-cities)\n- [Search Counties](/api-reference/counties/search-counties)\n\ - [Search Jurisdictions](/api-reference/jurisdictions/search-jurisdictions)\n\ \nFree-form text such as `\"123 Main St\"` is not accepted." - name: asset_class in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Decision Asset Class description: Filter by one or more asset classes (e.g. Residential, Commercial, Mixed-Use). description: Filter by one or more asset classes (e.g. Residential, Commercial, Mixed-Use). - name: category in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Decision Category description: Filter by one or more decision categories (e.g. Rezoning, Variance). description: Filter by one or more decision categories (e.g. Rezoning, Variance). - name: subcategory in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Decision Subcategory description: Filter by one or more decision subcategories. description: Filter by one or more decision subcategories. - name: property_type in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Decision Property Type description: Filter by one or more property types. description: Filter by one or more property types. - name: min_project_value in: query required: false schema: anyOf: - type: integer minimum: 0 - type: 'null' title: Minimum Project Value description: Minimum project value in cents (inclusive). description: Minimum project value in cents (inclusive). - name: max_project_value in: query required: false schema: anyOf: - type: integer minimum: 0 - type: 'null' title: Maximum Project Value description: Maximum project value in cents (inclusive). description: Maximum project value in cents (inclusive). - name: decision_q in: query required: false schema: anyOf: - type: string maxLength: 100 - type: 'null' title: Decision Search Query description: Full-text query against decision `title` and `description`, tokenized with PostgreSQL `plainto_tsquery('english', ...)`. description: Full-text query against decision `title` and `description`, tokenized with PostgreSQL `plainto_tsquery('english', ...)`. responses: '200': description: A list of decisions. content: application/json: schema: $ref: '#/components/schemas/PaginatedDecisionsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /decisions: get: tags: - Decisions summary: Get Decisions By Id description: Returns the requested decisions by ID. Unknown IDs are silently omitted (no per-ID 404). Up to 50 IDs per request. operationId: get_decisions_by_id_decisions_get security: - APIKeyHeader: [] parameters: - name: id in: query required: true schema: type: array items: type: string minItems: 1 maxItems: 50 title: Decision ID description: Filter by the decision's ID. Up to 50 IDs per request. description: Filter by the decision's ID. Up to 50 IDs per request. responses: '200': description: A list of decisions matching the requested IDs. content: application/json: schema: $ref: '#/components/schemas/PaginatedDecisionsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /contractors: get: tags: - Contractors - Contractors summary: Get Contractors By Id description: Returns contractors by their IDs. Multiple `id` query parameters can be provided in the same API call operationId: get_contractors_by_id_contractors_get security: - APIKeyHeader: [] parameters: - name: id in: query required: true schema: type: array items: type: string title: Contractor ID description: Filter by the contractor ID. maxItems: 50 description: Filter by the contractor ID. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination responses: '200': description: A list of contractors. content: application/json: schema: $ref: '#/components/schemas/PaginatedContractorsResponse' example: example: items: - id: e79c3393ad license: '961870' name: CA SUNRISE CONSTRUCTION SOLUTION INC. business_name: CA SUNRISE CONSTRUCTION SOLUTION INC. business_type: Corporation classification: CFC license_issue_date: '2018-05-15' license_exp_date: '2024-05-15' license_act_date: '2018-05-15' primary_phone: (425) 507-4300 primary_email: atobar.casunrise@gmail.com phone: (425) 270-9678,(425) 281-6152 email: atobar.casunrise@gmail.com,david@calsunrise.com dba: SUNRISE SOLAR sic: '1731' naics: '238210' linkedin_url: https://linkedin.com/company/ca-sunrise-constr revenue: $1M-$5M employee_count: 10-49 primary_industry: Solar Installation review_count: 42 rating: 4.8 status_tally: final: 754 active: 81 in_review: 2 inactive: 313 tag_tally: hvac: 27 solar: 39 roofing: 1 pool_and_hot_tub: 1 heat_pump: 267 electrical: 1110 new_construction: 20 permit_count: 1150 avg_job_value: 1500000 total_job_value: 172500000 avg_construction_duration: 45 avg_inspection_pass_rate: 85 address: street_no: '2800' street: COTTONWOOD DR city: SAN BRUNO zip_code: '94066' state: CA address_id: asd8a8b19 latlng: - 37.37619 - -121.869064 size: 1 '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /contractors/search: get: tags: - Contractors - Contractors summary: Search Contractors description: Returns contractors doing work within the given location area filtered by type of work. Contractors must meet all specified parameters, with multiple parameters treated as AND queries. Use contractor_classification_derived to filter by derived classifications (ALL specified values required). The permit_q parameter uses full-text search with English stemming (e.g., 'installing' matches 'install'). Multi-word queries use AND semantics (e.g., 'solar panel' finds permits mentioning both words). **NOTE:** Contractors are ordered by the start date of the most recent permit on which they worked. operationId: search_contractors_contractors_search_get security: - APIKeyHeader: [] parameters: - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size - name: include_count in: query required: false schema: type: boolean description: When true and on the first page (no cursor), include total_count in the response. The count is exact up to 10,000; above that, relation is 'gte'. default: false title: Include Count description: When true and on the first page (no cursor), include total_count in the response. The count is exact up to 10,000; above that, relation is 'gte'. - name: include_tallies in: query required: false schema: type: boolean description: Include tag and status tallies in response. Tallies are the only aggregate fields scoped to the search filters (permit_count, avg_job_value and total_job_value are lifetime totals), so they are the way to count a contractor's permits within the searched area and date range. Set to false to omit tally computation for faster response times when tallies are not needed. default: true title: Include Tallies description: Include tag and status tallies in response. Tallies are the only aggregate fields scoped to the search filters (permit_count, avg_job_value and total_job_value are lifetime totals), so they are the way to count a contractor's permits within the searched area and date range. Set to false to omit tally computation for faster response times when tallies are not needed. - name: permit_from in: query required: true schema: type: string format: date title: Permit From Date description: 'Return permits that started on or after the specified date.This includes all permits with the earliest date (file, issue, or start date) that falls on or after this date. Date format: `YYYY-MM-DD`' description: 'Return permits that started on or after the specified date.This includes all permits with the earliest date (file, issue, or start date) that falls on or after this date. Date format: `YYYY-MM-DD`' - name: permit_to in: query required: true schema: type: string format: date title: Permit To Date description: 'Return permits that started on or before the specified date.This includes all permits with the latest date (file, issue, or end date) that falls on or before this date. Date format: `YYYY-MM-DD`' description: 'Return permits that started on or before the specified date.This includes all permits with the latest date (file, issue, or end date) that falls on or before this date. Date format: `YYYY-MM-DD`' - name: permit_q in: query required: false schema: anyOf: - type: string maxLength: 50 - type: 'null' title: Search Query description: Substring to search for in permit description (case-insensitive). Matches anywhere in the text, including partial words. description: Substring to search for in permit description (case-insensitive). Matches anywhere in the text, including partial words. - name: permit_status in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Permit Status description: 'Filter by one or more statuses: final, in_review, inactive, active.' maxItems: 4 description: 'Filter by one or more statuses: final, in_review, inactive, active.' - name: permit_min_approval_duration in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Permit Approval Duration description: Filter by the minimum permit approval duration in days. description: Filter by the minimum permit approval duration in days. - name: permit_min_construction_duration in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Project Construction Duration description: Filter by the minimum project construction duration in days. description: Filter by the minimum project construction duration in days. - name: permit_min_inspection_pr in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Inspection Pass Rate description: Filter by the minimum inspection pass rate. description: Filter by the minimum inspection pass rate. - name: permit_min_job_value in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Job Value description: Filter by the minimum job value, in cents (e.g. 5000000 = $50,000). description: Filter by the minimum job value, in cents (e.g. 5000000 = $50,000). - name: permit_min_fees in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Permit Fees description: Filter by minimum permit fees, in cents (e.g. 5000000 = $50,000). description: Filter by minimum permit fees, in cents (e.g. 5000000 = $50,000). - name: permit_tags in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Permit Tags description: 'Filter by one or more tags. Use ''-'' prefix to exclude tags. Example: ?permit_tags=solar&permit_tags=-roofing (has solar, not roofing).' description: 'Filter by one or more tags. Use ''-'' prefix to exclude tags. Example: ?permit_tags=solar&permit_tags=-roofing (has solar, not roofing).' - name: geo_id in: query required: true schema: type: string title: Geolocation ID description: 'Filter results by geographic area. Accepts: - US state code (e.g. `CA`) - ZIP code (e.g. `90210` or `90210-1234`) - Shovels geolocation ID for an address, city, county, or jurisdiction (e.g. `a4xysKbZwqg`) Resolve addresses and places to geolocation IDs via: - [Search Addresses](/api-reference/addresses/search-addresses) - [Search Cities](/api-reference/cities/search-cities) - [Search Counties](/api-reference/counties/search-counties) - [Search Jurisdictions](/api-reference/jurisdictions/search-jurisdictions) Free-form text such as `"123 Main St"` is not accepted.' description: 'Filter results by geographic area. Accepts: - US state code (e.g. `CA`) - ZIP code (e.g. `90210` or `90210-1234`) - Shovels geolocation ID for an address, city, county, or jurisdiction (e.g. `a4xysKbZwqg`) Resolve addresses and places to geolocation IDs via: - [Search Addresses](/api-reference/addresses/search-addresses) - [Search Cities](/api-reference/cities/search-cities) - [Search Counties](/api-reference/counties/search-counties) - [Search Jurisdictions](/api-reference/jurisdictions/search-jurisdictions) Free-form text such as `"123 Main St"` is not accepted.' - name: property_type in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Property Type description: 'Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational. Repeat the key to match any of several types (e.g. `?property_type=residential&property_type=commercial`).' description: 'Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational. Repeat the key to match any of several types (e.g. `?property_type=residential&property_type=commercial`).' - name: property_min_market_value in: query required: false schema: anyOf: - type: integer - type: 'null' title: Mininum Property Market Value description: Minimum assessed market value of the property, in cents (e.g. 5000000 = $50,000). description: Minimum assessed market value of the property, in cents (e.g. 5000000 = $50,000). - name: property_min_building_area in: query required: false schema: anyOf: - type: integer - type: 'null' title: Mininum Property Building Area description: Minimum total building area in sq ft. description: Minimum total building area in sq ft. - name: property_min_lot_size in: query required: false schema: anyOf: - type: integer - type: 'null' title: Mininum Property Lot Size description: Minimum size of the property lot in sq ft. description: Minimum size of the property lot in sq ft. - name: property_min_story_count in: query required: false schema: anyOf: - type: integer - type: 'null' title: Mininum Property Story Count description: Minimum number of property stories. description: Minimum number of property stories. - name: property_min_unit_count in: query required: false schema: anyOf: - type: integer - type: 'null' title: Mininum Property Unit Count description: Minimum number of property units description: Minimum number of property units - name: contractor_classification_derived in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Contractor Classification Derived description: 'Filter by derived contractor classifications. Use ''-'' prefix to exclude. Example: ?classification_derived=electrical&classification_derived=-hvac. Returns results containing ALL specified classifications. Possible values: concrete_and_paving, demolition_and_excavation, electrical, fencing_and_glazing, framing_and_carpentry, general_building_contractor, general_engineering_contractor, hvac, landscaping_and_outdoor_work, other, plumbing, roofing, specialty_trades.' description: 'Filter by derived contractor classifications. Use ''-'' prefix to exclude. Example: ?classification_derived=electrical&classification_derived=-hvac. Returns results containing ALL specified classifications. Possible values: concrete_and_paving, demolition_and_excavation, electrical, fencing_and_glazing, framing_and_carpentry, general_building_contractor, general_engineering_contractor, hvac, landscaping_and_outdoor_work, other, plumbing, roofing, specialty_trades.' - name: contractor_name in: query required: false schema: anyOf: - type: string minLength: 3 - type: 'null' title: Contractor Name description: "Filter by contractor's name or business name (partial match\ \ supported). Must be at least 3 characters \u2014 shorter patterns cannot\ \ use the trigram index and would force a sequential scan." description: "Filter by contractor's name or business name (partial match\ \ supported). Must be at least 3 characters \u2014 shorter patterns cannot\ \ use the trigram index and would force a sequential scan." - name: contractor_website in: query required: false schema: anyOf: - type: string - type: 'null' title: Contractor Website description: Filter by contractor's website. Don't include the http(s):// prefix. description: Filter by contractor's website. Don't include the http(s):// prefix. - name: contractor_min_total_job_value in: query required: false schema: anyOf: - type: integer - type: 'null' title: Mininum Contractor Total Job Value description: Minimum lifetime job value of the contractor, in cents (e.g. 5000000 = $50,000). description: Minimum lifetime job value of the contractor, in cents (e.g. 5000000 = $50,000). - name: contractor_min_total_permits_count in: query required: false schema: anyOf: - type: integer - type: 'null' title: Mininum Contractor Permits Count description: Minimum lifetime permits count. description: Minimum lifetime permits count. - name: contractor_min_inspection_pr in: query required: false schema: anyOf: - type: integer - type: 'null' title: Mininum Contractor Inspection Pass Rate description: Minimum lifetime inspection pass rate. The value must be an integer between 0 and 100, inclusive. description: Minimum lifetime inspection pass rate. The value must be an integer between 0 and 100, inclusive. - name: contractor_license in: query required: false schema: anyOf: - type: string - type: 'null' title: Contractor License description: Filter by the contractor's license description: Filter by the contractor's license responses: '200': description: A list of contractors. content: application/json: schema: $ref: '#/components/schemas/PaginatedContractorsResponse' example: example: items: - id: e79c3393ad license: '961870' name: CA SUNRISE CONSTRUCTION SOLUTION INC. business_name: CA SUNRISE CONSTRUCTION SOLUTION INC. business_type: Corporation classification: CFC license_issue_date: '2018-05-15' license_exp_date: '2024-05-15' license_act_date: '2018-05-15' primary_phone: (425) 507-4300 primary_email: atobar.casunrise@gmail.com phone: (425) 270-9678,(425) 281-6152 email: atobar.casunrise@gmail.com,david@calsunrise.com dba: SUNRISE SOLAR sic: '1731' naics: '238210' linkedin_url: https://linkedin.com/company/ca-sunrise-constr revenue: $1M-$5M employee_count: 10-49 primary_industry: Solar Installation review_count: 42 rating: 4.8 status_tally: final: 754 active: 81 in_review: 2 inactive: 313 tag_tally: hvac: 27 solar: 39 roofing: 1 pool_and_hot_tub: 1 heat_pump: 267 electrical: 1110 new_construction: 20 permit_count: 1150 avg_job_value: 1500000 total_job_value: 172500000 avg_construction_duration: 45 avg_inspection_pass_rate: 85 address: street_no: '2800' street: COTTONWOOD DR city: SAN BRUNO zip_code: '94066' state: CA address_id: asd8a8b19 latlng: - 37.37619 - -121.869064 size: 1 '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /contractors/{id}/permits: get: tags: - Contractors - Contractors summary: Get Permits By Contractor Id description: Retrieves all permits associated with a single contractor. operationId: get_permits_by_contractor_id_contractors__id__permits_get security: - APIKeyHeader: [] parameters: - name: id in: path required: true schema: type: string title: Contractor ID description: Filter by the specified contractor ID. description: Filter by the specified contractor ID. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size - name: include_count in: query required: false schema: type: boolean description: When true and on the first page (no cursor), include total_count in the response. The count is exact up to 10,000; above that, relation is 'gte'. default: false title: Include Count description: When true and on the first page (no cursor), include total_count in the response. The count is exact up to 10,000; above that, relation is 'gte'. responses: '200': description: A list of permits associated with the contractor and grouped by address content: application/json: schema: $ref: '#/components/schemas/PaginatedPermitsResponse' example: items: - property_census_tract: '101' property_congressional_district: '1' property_type: residential property_type_detail: single_family_home property_legal_owner: OAKLAND HOUSING AUTHORITY property_owner_type: individual property_lot_size: 4000 property_building_area: 1000 property_story_count: 1 property_unit_count: 1 property_year_built: 1970 property_assess_market_value: 1050000 id: caf3b9d5ce317d53 number: RE2303928 description: Battery backup description_derived: Battery storage installation jurisdiction: Berkeley type: Re) - electrical - 1 & 2 unit residential (building) fees: 61960 status: active file_date: '2023-10-02' issue_date: '2023-10-11' final_date: '2023-12-11' start_date: '2022-10-19' end_date: '2023-12-11' total_duration: 230 construction_duration: 61 approval_duration: 9 contractor_id: KOm4dMLIuT tags: - solar - battery address: street_no: '3360' street: DWIGHT WAY city: OAKLAND zip_code: '94704' state: CA latlng: - 37.868443 - -122.24374 geo_ids: address_id: asd8a8b19 city_id: KLais31 county_id: ALa2s33 jurisdiction_id: BLa2s33 - property_census_tract: '101' property_congressional_district: '1' property_type: residential property_type_detail: single_family_home property_legal_owner: OAKLAND HOUSING AUTHORITY property_owner_type: individual property_lot_size: 4000 property_building_area: 1000 property_story_count: 1 property_unit_count: 1 property_year_built: 1970 property_assess_market_value: 1050000 id: 71c02bd70f7ce1c9 number: E2304692 description: 'Install 27 kwh back-up batteries in cabinet ' description_derived: Battery storage installation jurisdiction: Berkeley type: E) - electrical - 3+ residential units or commercial fees: 61506 status: in_review file_date: '2023-11-29' start_date: '2022-11-29' end_date: '2023-11-29' total_duration: 0 construction_duration: 154 approval_duration: 204 tags: - solar address: street_no: '544' street: DWIGHT PL city: OAKLAND zip_code: '94704' state: CA latlng: - 37.8671 - -122.24461 geo_ids: address_id: 1sd8a8b19 city_id: KLais31 county_id: ALa2s33 jurisdiction_id: BLa2s33 - property_census_tract: '101' property_congressional_district: '1' property_type: residential property_type_detail: single_family_home property_legal_owner: OAKLAND HOUSING AUTHORITY property_owner_type: individual property_lot_size: 4000 property_building_area: 1000 property_story_count: 1 property_unit_count: 1 property_year_built: 1970 property_assess_market_value: 1050000 id: 9525a96a93e0cdb7 number: B2303829 description: Install 27 kwh back-up batteries in cabinet description_derived: Battery storage installation jurisdiction: Berkeley job_value: 500100 type: 'Building alteration: 3+ residential units or commercial' fees: 795300 status: in_review file_date: '2023-11-29' start_date: '2022-11-29' end_date: '2023-11-29' total_duration: 0 construction_duration: 154 approval_duration: 204 tags: - solar address: street_no: '544' street: DWIGHT PL city: OAKLAND zip_code: '94704' state: CA latlng: - 37.8671 - -122.24461 geo_ids: address_id: 1sd8a8b19 city_id: KLais31 county_id: ALa2s33 jurisdiction_id: BLa2s33 size: 3 '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /contractors/{id}/employees: get: tags: - Contractors - Contractors - Contractors summary: Get Contractor Employees description: Returns a paginated list of employees for a specific contractor. operationId: get_contractor_employees_contractors__id__employees_get security: - APIKeyHeader: [] parameters: - name: id in: path required: true schema: type: string title: Contractor ID description: Filter by the specified contractor ID. description: Filter by the specified contractor ID. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size responses: '200': description: A list of employees associated with the contractor. content: application/json: schema: $ref: '#/components/schemas/PaginatedEmployeesResponse' example: items: - id: aa145cd32c95f69b95e9233f6a957a32 contractor_id: 8wKHB2ZNf name: John Smith street_no: '123' street: Oak Avenue city: San Francisco zip_code: '94105' zip_code_ext: '1234' state: CA phone: (415) 555-0123 email: john.smith@personal.com business_email: j.smith@company.com linkedin_url: https://linkedin.com/in/johnsmith homeowner: Y gender: M age_range: 35-44 is_married: true has_children: true income_range: $120,000 to $149,999 net_worth: $150,000 to $249,999 job_title: Senior Solar Installation Technician seniority_level: Senior department: Installation - id: 73744cd32c95f69b95e9233f6a957d90 contractor_id: 8wKHB2ZNf name: Sarah Johnson street_no: '456' street: Pine Street city: Oakland zip_code: '94611' zip_code_ext: '5678' state: CA phone: (510) 555-0456 email: sarah.j@personal.com business_email: s.johnson@company.com linkedin_url: https://linkedin.com/in/sarahjohnson homeowner: N gender: F age_range: 25-34 is_married: false has_children: false income_range: $75,000 to $100,000 net_worth: $150,000 to $249,999 job_title: Project Manager seniority_level: Mid department: Operations size: 2 next_cursor: eyJjb250cmFjdG9yX2l '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /contractors/{id}/metrics: get: tags: - Contractors - Contractors - Contractors summary: Get Filtered Metrics By Contractor Id description: Returns contractor monthly metrics filtered by contractor ID, property type, and tags. Metrics include permit count, average duration, and average pass rate. operationId: get_filtered_metrics_by_contractor_id_contractors__id__metrics_get security: - APIKeyHeader: [] parameters: - name: id in: path required: true schema: type: string title: Contractor ID description: Filter by the specified contractor ID. description: Filter by the specified contractor ID. - name: metric_from in: query required: true schema: type: string format: date description: Start date for metrics (inclusive) title: Metric From description: Start date for metrics (inclusive) - name: metric_to in: query required: true schema: type: string format: date description: End date for metrics (inclusive) title: Metric To description: End date for metrics (inclusive) - name: property_type in: query required: true schema: type: string title: Property type description: Filter by property type description: Filter by property type - name: tag in: query required: true schema: type: string title: Tag description: Filter by tag description: Filter by tag - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size responses: '200': description: Contractor monthly metrics content: application/json: schema: $ref: '#/components/schemas/PaginatedContractorsMetrics' example: items: - property_type: residential date: '2022-01-01' tag: solar permit_count: 10 avg_job_value: 1000000 total_job_value: 10000000 avg_construction_duration: 100 avg_inspection_pass_rate: 95 - property_type: residential date: '2022-02-01' tag: solar permit_count: 4 avg_job_value: 1000000 total_job_value: 10000000 avg_construction_duration: 30 avg_inspection_pass_rate: 45 size: 2 next_cursor: eyJkYXRlIjoi '404': description: Contractor not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /addresses/search: get: tags: - Addresses summary: Search Addresses description: Searches addresses by their text fields (street number, street, city, state, and ZIP code) using prefix, full-text, and fuzzy matching. operationId: search_addresses_addresses_search_get security: - APIKeyHeader: [] parameters: - name: q in: query required: true schema: type: string title: Address Search Text description: The text to search for in the address fields. description: The text to search for in the address fields. responses: '200': description: A list of addresses that match the search text, ordered by relevance and in USPS notation. content: application/json: schema: $ref: '#/components/schemas/PaginatedAddressesResponse' example: items: - street_no: '1232' street: MARKET ST city: SAN FRANCISCO county: SAN FRANCISCO zip_code: '94103' zip_code_ext: '1234' state: CA jurisdiction: SAN FRANCISCO lat: 37.7749 long: -122.41 geo_id: '1' name: 123 Market St, San Francisco, CA - street_no: '1233' street: MARKET ST city: SAN FRANCISCO county: SAN FRANCISCO zip_code: '94103' zip_code_ext: '1234' state: CA jurisdiction: SAN FRANCISCO lat: 37.7749 long: -122.41 geo_id: '2' name: 1233 Market St, San Francisco, CA - street_no: '1234' street: MARKET ST city: SAN FRANCISCO county: SAN FRANCISCO zip_code: '94103' zip_code_ext: '1234' state: CA jurisdiction: SAN FRANCISCO lat: 37.7749 long: -122.41 geo_id: '3' name: 1234 Market St, San Francisco, CA size: 3 '404': description: The specified search query didn't match any addresses '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /cities/search: get: tags: - Cities summary: Search Cities description: Searches for cities based on the provided search term. operationId: search_cities_cities_search_get security: - APIKeyHeader: [] parameters: - name: q in: query required: true schema: type: string title: City Name Search description: The name to search for in the city fields. description: The name to search for in the city fields. responses: '200': description: A list of cities that match the search text. content: application/json: schema: $ref: '#/components/schemas/PaginatedGeoEntitiesResponse' example: items: - geo_id: Q2l0eV8xMjM0NQ name: SAN FRANCISCO, SAN FRANCISCO, CA state: CA - geo_id: A22eV8yMzQ1Ng name: SAN RAMON, CONTRA COSTA COUNTY, CA state: CA - geo_id: B2l0eV8yMzQ1rr name: SAN DIEGO, SAN DIEGO COUNTY, CA state: CA size: 3 '404': description: The specified search query didn't match any cities '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /counties/search: get: tags: - Counties summary: Search Counties description: Searches for counties based on the provided search term. operationId: search_counties_counties_search_get security: - APIKeyHeader: [] parameters: - name: q in: query required: true schema: type: string title: County Name Search description: The name to search for in the county fields. description: The name to search for in the county fields. responses: '200': description: A list of counties that match the search text. content: application/json: schema: $ref: '#/components/schemas/PaginatedGeoEntitiesResponse' example: items: - geo_id: Q291bnR5XzEyMzQ1 name: Los Angeles County, CA state: CA - geo_id: A291bnR5XzEyMzQ1 name: Harris County, TX state: TX - geo_id: B291bnR5XzEyMzQ1 name: Cook County, IL state: IL size: 3 '404': description: The specified search query didn't match any counties '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /jurisdictions/search: get: tags: - Jurisdictions summary: Search Jurisdictions description: Searches for jurisdictions based on the provided search term. operationId: search_jurisdictions_jurisdictions_search_get security: - APIKeyHeader: [] parameters: - name: q in: query required: true schema: type: string title: Jurisdiction Name Search description: The name to search for in the jurisdiction fields. description: The name to search for in the jurisdiction fields. responses: '200': description: A list of jurisdictions that match the search text. content: application/json: schema: $ref: '#/components/schemas/PaginatedGeoEntitiesResponse' example: items: - geo_id: Q2l0eV8xMjM0NQ name: Sanford, FL state: FL - geo_id: A2l0eV8xMjM0NQ name: Abilene, TX state: TX - geo_id: B2l0eV8xMjM0NQ name: Albany, CA state: CA size: 3 '404': description: The specified search query didn't match any jurisdictions '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /zipcodes/search: get: tags: - Zipcodes summary: Search Zipcodes description: Searches for zipcodes based on the provided search term. operationId: search_zipcodes_zipcodes_search_get security: - APIKeyHeader: [] parameters: - name: q in: query required: true schema: type: string title: ZIP Code Search description: The code to search for in the zipcodes fields. description: The code to search for in the zipcodes fields. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size responses: '200': description: A list of zipcodes that match the search code. content: application/json: schema: $ref: '#/components/schemas/PaginatedZipcodesResponse' example: items: - geo_id: '94705' state: CA - geo_id: '94704' state: CA - geo_id: 73301-5678 state: TX size: 3 '404': description: The specified search query didn't match any zipcodes '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /states/search: get: tags: - States summary: Search States description: Searches for US states based on the provided search term. operationId: search_states_states_search_get security: - APIKeyHeader: [] parameters: - name: q in: query required: true schema: type: string title: US State Search description: The name to search for in the state fields. description: The name to search for in the state fields. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size responses: '200': description: A list of states that match the search term. content: application/json: schema: $ref: '#/components/schemas/PaginatedStatesResponse' example: items: - geo_id: CA name: CALIFORNIA - geo_id: TX name: TEXAS - geo_id: MT name: MONTANA size: 3 '404': description: The specified search query didn't match any states '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /addresses/{geo_id}/metrics/monthly: get: tags: - Addresses summary: Get Address Metrics Monthly description: Returns monthly address metrics. operationId: get_address_metrics_monthly_addresses__geo_id__metrics_monthly_get security: - APIKeyHeader: [] parameters: - name: geo_id in: path required: true schema: type: string title: Address ID description: Filter by the specified geolocation ID. description: Filter by the specified geolocation ID. - name: metric_from in: query required: true schema: type: string format: date description: Start date for metrics (inclusive) title: Metric From description: Start date for metrics (inclusive) - name: metric_to in: query required: true schema: type: string format: date description: End date for metrics (inclusive) title: Metric To description: End date for metrics (inclusive) - name: tag in: query required: true schema: type: string description: Filter by tag title: Tag description: Filter by tag - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size responses: '200': description: Successfully retrieved monthly address metrics content: application/json: schema: $ref: '#/components/schemas/PaginatedAddressesMetricsMonthly' example: items: - geo_id: abc123 tag: all permit_count: 42 contractor_count: 15 avg_construction_duration: 60 avg_approval_duration: 14 total_job_value: 12500000 avg_inspection_pass_rate: 85 date: '2023-01-01' size: 1 next_cursor: c29tZS1jdXJzb3I '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /addresses/{geo_id}/metrics/current: get: tags: - Addresses summary: Get Address Metrics Current description: Returns current address metrics. operationId: get_address_metrics_current_addresses__geo_id__metrics_current_get security: - APIKeyHeader: [] parameters: - name: geo_id in: path required: true schema: type: string title: Address ID description: Filter by the specified geolocation ID. description: Filter by the specified geolocation ID. - name: tag in: query required: true schema: type: string description: Filter by tag title: Tag description: Filter by tag - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size responses: '200': description: Current metrics for the address content: application/json: schema: $ref: '#/components/schemas/PaginatedAddressesMetricsCurrent' example: items: - geo_id: MDEyMzQ1Njc4OWFiY2RlZg== tag: solar permit_count: 42 contractor_count: 15 avg_construction_duration: 60 avg_approval_duration: 14 total_job_value: 12500000 avg_inspection_pass_rate: 85 permit_active_count: 25 permit_in_review_count: 17 size: 1 '404': description: Address not found '422': description: Invalid address ID format /cities/{geo_id}/metrics/monthly: get: tags: - Cities summary: Get City Metrics Monthly description: Returns monthly city metrics. operationId: get_city_metrics_monthly_cities__geo_id__metrics_monthly_get security: - APIKeyHeader: [] parameters: - name: geo_id in: path required: true schema: type: string title: City ID description: Filter by the specified city ID. description: Filter by the specified city ID. - name: metric_from in: query required: true schema: type: string format: date description: Start date for metrics (inclusive) title: Metric From description: Start date for metrics (inclusive) - name: metric_to in: query required: true schema: type: string format: date description: End date for metrics (inclusive) title: Metric To description: End date for metrics (inclusive) - name: property_type in: query required: true schema: type: string description: Filter by property type title: Property Type description: Filter by property type - name: tag in: query required: true schema: type: string description: Filter by tag title: Tag description: Filter by tag - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size responses: '200': description: Monthly metrics for the city content: application/json: schema: $ref: '#/components/schemas/PaginatedCitiesMetricsMonthly' example: items: - geo_id: MDEyMzQ1Njc4OWFiY2RlZg== tag: solar permit_count: 120 contractor_count: 45 avg_construction_duration: 65 avg_approval_duration: 18 total_job_value: 35000000 avg_inspection_pass_rate: 80 date: '2023-01-01' property_type: residential size: 1 next_cursor: c29tZS1jdXJzb3I '404': description: City not found '422': description: Invalid city ID format /cities/{geo_id}/metrics/current: get: tags: - Cities summary: Get City Metrics Current description: Returns current city metrics. operationId: get_city_metrics_current_cities__geo_id__metrics_current_get security: - APIKeyHeader: [] parameters: - name: geo_id in: path required: true schema: type: string title: City ID description: Filter by the specified city ID. description: Filter by the specified city ID. - name: property_type in: query required: true schema: type: string title: Property type description: Filter by property type description: Filter by property type - name: tag in: query required: true schema: type: string description: Filter by tag title: Tag description: Filter by tag - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size responses: '200': description: Current metrics for the city content: application/json: schema: $ref: '#/components/schemas/PaginatedCitiesMetricsCurrent' example: items: - geo_id: MDEyMzQ1Njc4OWFiY2RlZg== tag: solar permit_count: 1234 contractor_count: 78 avg_construction_duration: 45 avg_approval_duration: 7 total_job_value: 987654321 avg_inspection_pass_rate: 90 permit_active_count: 345 permit_in_review_count: 56 property_type: residential size: 1 '404': description: City not found '422': description: Invalid city ID format /counties/{geo_id}/metrics/monthly: get: tags: - Counties summary: Get County Metrics Monthly description: Returns monthly county metrics. operationId: get_county_metrics_monthly_counties__geo_id__metrics_monthly_get security: - APIKeyHeader: [] parameters: - name: geo_id in: path required: true schema: type: string title: County ID description: Filter by the specified county ID. description: Filter by the specified county ID. - name: metric_from in: query required: true schema: type: string format: date description: Start date for metrics (inclusive) title: Metric From description: Start date for metrics (inclusive) - name: metric_to in: query required: true schema: type: string format: date description: End date for metrics (inclusive) title: Metric To description: End date for metrics (inclusive) - name: property_type in: query required: true schema: type: string title: Property type description: Filter by property type description: Filter by property type - name: tag in: query required: true schema: type: string description: Filter by tag title: Tag description: Filter by tag - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size responses: '200': description: Successfully retrieved monthly county metrics content: application/json: schema: $ref: '#/components/schemas/PaginatedCountiesMetricsMonthly' example: items: - geo_id: ghi789 tag: all permit_count: 250 contractor_count: 85 avg_construction_duration: 90 avg_approval_duration: 25 total_job_value: 125000000 avg_inspection_pass_rate: 78 date: '2023-01-01' property_type: commercial size: 1 '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /counties/{geo_id}/metrics/current: get: tags: - Counties summary: Get County Metrics Current description: Returns current county metrics. operationId: get_county_metrics_current_counties__geo_id__metrics_current_get security: - APIKeyHeader: [] parameters: - name: geo_id in: path required: true schema: type: string title: County ID description: Filter by the specified county ID. description: Filter by the specified county ID. - name: property_type in: query required: true schema: type: string title: Property type description: Filter by property type description: Filter by property type - name: tag in: query required: true schema: type: string description: Filter by tag title: Tag description: Filter by tag - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size responses: '200': description: Current metrics for the county content: application/json: schema: $ref: '#/components/schemas/PaginatedCountiesMetricsCurrent' example: items: - geo_id: MDEyMzQ1Njc4OWFiY2RlZg== tag: solar permit_count: 250 contractor_count: 85 avg_construction_duration: 90 avg_approval_duration: 25 total_job_value: 125000000 avg_inspection_pass_rate: 78 permit_active_count: 160 permit_in_review_count: 90 property_type: commercial size: 1 '404': description: County not found '422': description: Invalid county ID format /jurisdictions/{geo_id}/metrics/monthly: get: tags: - Jurisdictions summary: Get Jurisdiction Metrics Monthly description: Returns monthly jurisdiction metrics. operationId: get_jurisdiction_metrics_monthly_jurisdictions__geo_id__metrics_monthly_get security: - APIKeyHeader: [] parameters: - name: geo_id in: path required: true schema: type: string title: Jurisdiction ID description: Filter by the specified jurisdiction ID. description: Filter by the specified jurisdiction ID. - name: metric_from in: query required: true schema: type: string format: date description: Start date for metrics (inclusive) title: Metric From description: Start date for metrics (inclusive) - name: metric_to in: query required: true schema: type: string format: date description: End date for metrics (inclusive) title: Metric To description: End date for metrics (inclusive) - name: property_type in: query required: true schema: type: string title: Property type description: Filter by property type description: Filter by property type - name: tag in: query required: true schema: type: string description: Filter by tag title: Tag description: Filter by tag - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size responses: '200': description: Successfully retrieved monthly jurisdiction metrics content: application/json: schema: $ref: '#/components/schemas/PaginatedJurisdictionsMetricsMonthly' example: items: - geo_id: jkl012 tag: all permit_count: 180 contractor_count: 60 avg_construction_duration: 75 avg_approval_duration: 21 total_job_value: 75000000 avg_inspection_pass_rate: 82 date: '2023-01-01' property_type: residential size: 1 next_cursor: c29tZS1jdXJzb3I '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /jurisdictions/{geo_id}/metrics/current: get: tags: - Jurisdictions summary: Get Jurisdiction Metrics Current description: Returns current jurisdiction metrics. operationId: get_jurisdiction_metrics_current_jurisdictions__geo_id__metrics_current_get security: - APIKeyHeader: [] parameters: - name: geo_id in: path required: true schema: type: string title: Jurisdiction ID description: Filter by the specified jurisdiction ID. description: Filter by the specified jurisdiction ID. - name: property_type in: query required: true schema: type: string title: Property type description: Filter by property type description: Filter by property type - name: tag in: query required: true schema: type: string description: Filter by tag title: Tag description: Filter by tag - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size responses: '200': description: Current metrics for the jurisdiction content: application/json: schema: $ref: '#/components/schemas/PaginatedJurisdictionsMetricsCurrent' example: items: - geo_id: MDEyMzQ1Njc4OWFiY2RlZg== tag: solar permit_count: 180 contractor_count: 60 avg_construction_duration: 75 avg_approval_duration: 21 total_job_value: 75000000 avg_inspection_pass_rate: 82 permit_active_count: 120 permit_in_review_count: 60 property_type: residential size: 1 '404': description: Jurisdiction not found '422': description: Invalid jurisdiction ID format /cities: get: tags: - Cities summary: Get City Details description: Return city details and related location hierarchy. operationId: get_city_details_cities_get security: - APIKeyHeader: [] parameters: - name: geo_id in: query required: true schema: type: string description: Geolocation ID title: Geo Id description: Geolocation ID responses: '200': description: City details and related location hierarchy. content: application/json: schema: $ref: '#/components/schemas/CitiesDetailsRead' example: geo_id: Q2l0eV8xMjM0NQ name: SAN FRANCISCO, CA state: CA counties: SAN FRANCISCO: Q291bnR5XzEyMzQ jurisdictions: SAN FRANCISCO: SnVyaXNkaWN0aW9uXzEyMzQ zipcodes: - '94102' - '94103' - '94104' - '94105' '404': description: The given geo_id didn't match any cities '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /counties: get: tags: - Counties summary: Get County Details description: Return county details and related location hierarchy. operationId: get_county_details_counties_get security: - APIKeyHeader: [] parameters: - name: geo_id in: query required: true schema: type: string description: Geolocation ID title: Geo Id description: Geolocation ID responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CountiesDetailsRead' example: geo_id: Q291bnR5XzEyMzQ1 name: SAN FRANCISCO, CA state: CA cities: SAN FRANCISCO: Q2l0eV8xMjM0NQ SAN RAMON: Q2l0eV8yMzQ1Ng jurisdictions: SAN FRANCISCO: SnVyaXNkaWN0aW9uXzEyMzQ1 zipcodes: - '94102' - '94103' - '94104' '404': description: The given geo_id didn't match any counties '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /jurisdictions: get: tags: - Jurisdictions summary: Get Jurisdiction Details description: Return jurisdiction details and related location hierarchy. operationId: get_jurisdiction_details_jurisdictions_get security: - APIKeyHeader: [] parameters: - name: geo_id in: query required: true schema: type: string description: Geolocation ID title: Geo Id description: Geolocation ID responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JurisdictionsDetailsRead' example: geo_id: SnVyaXNkaWN0aW9uXzEyMzQ1 name: SAN FRANCISCO, CA state: CA cities: SAN FRANCISCO: Q2l0eV8xMjM0NQ SAN RAMON: Q2l0eV8yMzQ1Ng counties: SAN FRANCISCO: Q291bnR5XzEyMzQ1 zipcodes: - '94102' - '94103' - '94104' '404': description: The given geo_id didn't match any jurisdictions '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /addresses/{geo_id}/residents: get: tags: - Addresses summary: Get Residents description: Return residents for a given address geo ID. Results are paginated using cursor-based pagination. operationId: get_residents_addresses__geo_id__residents_get security: - APIKeyHeader: [] parameters: - name: geo_id in: path required: true schema: type: string description: Address geo ID title: Geo Id description: Address geo ID - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size responses: '200': description: Residents for a given address geo ID content: application/json: schema: $ref: '#/components/schemas/PaginatedResidentsResponse' example: items: - name: John Doe personal_emails: john.doe@example.com phone: (978) 314-5196 linkedin_url: https://www.linkedin.com/in/john-doe/ net_worth: $750,000 to $999,999 income_range: $150,000 to $299,999 is_homeowner: true street_no: '123' street: Main St city: New York state: NY zip_code: '10001' - name: Jane Doe personal_emails: jane.doe@example.com phone: (310) 555-7890 linkedin_url: https://www.linkedin.com/in/jane-doe/ net_worth: $500,000 to $749,999 income_range: $100,000 to $149,999 is_homeowner: false street_no: '456' street: Ocean Ave city: Los Angeles state: CA zip_code: '90001' zip_code_ext: '1234' size: 2 next_cursor: aGVsbG8ad77 '404': description: The given geo_id doesn't have residents information. '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /meta/release: get: tags: - Meta summary: Get Data Release Date description: Returns the release date of the current data served by the API. operationId: get_data_release_date_meta_release_get responses: '200': description: The data release date content: application/json: schema: $ref: '#/components/schemas/Metadata' example: released_at: '2020-01-01' security: - APIKeyHeader: [] /meta/coverage: get: tags: - Meta summary: Get Coverage description: Returns per-field data coverage tiers (partial or missing) for the specified geography and date range. Fields classified as reliable (fill rate >= 80%) are omitted. Empty windows return all 10 tracked fields as missing with permits_total=0. operationId: get_coverage_meta_coverage_get security: - APIKeyHeader: [] parameters: - name: geo_type in: query required: true schema: enum: - state - county - city - zipcode - jurisdiction type: string title: Geography Type description: One of 'state', 'county', 'city', 'zipcode', 'jurisdiction'. Determines how geo_id is parsed. description: One of 'state', 'county', 'city', 'zipcode', 'jurisdiction'. Determines how geo_id is parsed. - name: geo_id in: query required: true schema: type: string title: Geography ID description: 2-letter state code, 5-digit ZIP, or base64 geolocation ID for city/county/jurisdiction. description: 2-letter state code, 5-digit ZIP, or base64 geolocation ID for city/county/jurisdiction. - name: date_from in: query required: true schema: type: string format: date title: Date From description: 'Inclusive lower bound of the window. Format: YYYY-MM-DD. The coverage year set includes every year the range touches.' description: 'Inclusive lower bound of the window. Format: YYYY-MM-DD. The coverage year set includes every year the range touches.' - name: date_to in: query required: true schema: type: string format: date title: Date To description: 'Inclusive upper bound of the window. Format: YYYY-MM-DD. Must be >= date_from.' description: 'Inclusive upper bound of the window. Format: YYYY-MM-DD. Must be >= date_from.' responses: '200': description: Per-field coverage rows ordered by tier then field. content: application/json: schema: $ref: '#/components/schemas/CoverageResponse' example: items: - field: fees tier: missing fill_pct: 0.02 permits_total: 12034 - field: job_value tier: partial fill_pct: 0.41 permits_total: 12034 '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /list/zip: get: tags: - Lists summary: Get All Available Zip Codes description: Returns all available ZIP codes for which we have permit and contractor data. operationId: get_all_available_zip_codes_list_zip_get security: - APIKeyHeader: [] parameters: - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size responses: '200': description: A list of available ZIP codes content: application/json: schema: $ref: '#/components/schemas/PaginatedZipCodesResponse' example: items: - zip_code: '90001' - zip_code: '90002' - zip_code: '90003' - zip_code: '90004' - zip_code: '90005' - zip_code: '90006' - zip_code: '90007' - zip_code: '90008' - zip_code: '90009' - zip_code: '90010' size: 50 next_cursor: example_cursor '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /list/tags: get: tags: - Lists summary: Get All Available Tags description: Returns all available permit tags. operationId: get_all_available_tags_list_tags_get security: - APIKeyHeader: [] parameters: - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Cursor description: Cursor for pagination - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Size responses: '200': description: A list of available permit tags content: application/json: schema: $ref: '#/components/schemas/PaginatedTagsResponse' example: items: - id: new_dwelling description: New Dwelling - id: new_adu description: New Apartment Unit - id: accessory_structure description: Accessory Structure - id: pool_spa description: Pool or Spa - id: room_addition description: Room Addition - id: kitchen_remodel description: Kitchen Remodel - id: bath_remodel description: Bath Remodel - id: solar description: Solar Panels - id: reroof description: Reroofing - id: utilities description: Utility - id: window_door description: Window or Door Repair size: 50 next_cursor: example_cursor '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /properties: get: tags: - Properties - Properties summary: Get Properties By Id description: '**Beta.** Query parameters, response fields, and the absence-trust surface may still change in response to how the endpoint is used in practice. Treat the shape as unstable while it is in beta. Returns properties by their address id. Provide up to 50 `id` query parameters in one call; rows come back in request order and unknown ids are omitted (no per-id 404). A non-address geolocation id (city, county, or jurisdiction) is rejected.' operationId: get_properties_by_id_properties_get security: - APIKeyHeader: [] parameters: - name: id in: query required: true schema: type: array items: type: string minItems: 1 maxItems: 50 title: Property ID description: Address geolocation id. Up to 50 `id` params per request. description: Address geolocation id. Up to 50 `id` params per request. responses: '200': description: The requested properties, in request order. content: application/json: schema: $ref: '#/components/schemas/PaginatedPropertiesResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /properties/search: get: tags: - Properties - Properties summary: Search Properties description: "**Beta.** Query parameters, response fields, and the absence-trust\ \ surface may still change in response to how the endpoint is used in practice.\ \ Treat the shape as unstable while it is in beta. Returns properties within\ \ a geo scope (state, county, city, ZIP, ZIP+4, or address) and/or owned by\ \ named `legal_owner`s, most recently permitted first. At least one of `geo_id`\ \ and `legal_owner` is required; a `legal_owner` search needs no geo scope.\ \ Pass `cursor` from a page's `next_cursor` to page through results. Filter\ \ by `permit_tags` (presence and `-`-prefixed exclusion), `permit_status`,\ \ `permit_from`, and `property_type`. Properties with no attributed type are\ \ excluded; property attributes are available for 70.1% of properties. An\ \ absence filter (a `-`-prefixed tag) returns properties with no resolved\ \ permit of the excluded type in covered, arrived data: a permit that never\ \ linked to an address, or one that has not yet arrived within a jurisdiction's\ \ ingestion lag, is not counted against the claim. Every absence-class row\ \ carries a `trust` object stating three honesty terms \u2014 the jurisdiction's\ \ permit `coverage_tier`, its `unresolved_rate` (the share of its permits\ \ that never linked to an address), and the row's `data_horizon` \u2014 plus\ \ `horizon_basis` (whether that horizon is measured, pooled, or a state prior)\ \ and `footprint_basis` (whether suppression could resolve the row's geo);\ \ the response `trust_summary` row-weights them across the page. A presence-only\ \ search omits both. Freshness: /properties is served from a whole-table rebuild\ \ swapped in by a blue/green cutover \u2014 the rebuild is the unit of refresh,\ \ and the absence-trust metadata is rebuilt from the same data it describes.\ \ An absence claim's staleness bound is the rebuild cadence plus each jurisdiction's\ \ permit-ingestion lag: permits reach the data a median 84 days (p90 188 days)\ \ after their start_date, so a recent 'no permit since D' stays under-observed\ \ until that lag elapses. Each row's `data_horizon` is the per-row handle\ \ on that bound \u2014 the most recent start_date past which 'no X since D'\ \ is under-observed for that row. Not supported, each for one reason: `permit_to`\ \ or any upper date bound \u2014 a max-date rollup cannot bound a closed date\ \ window without dropping addresses whose latest permit postdates it (use\ \ /permits/search); 'before D' absence \u2014 a max-date cannot tell a history\ \ that also holds later permits from one that does not; closed-window absence\ \ within [D1, D2] \u2014 only 'ever' and 'since D' are expressible on max-date\ \ maps; 'has X since D and no Y since D' in one query \u2014 a mixed query\ \ binds an exclusion to 'ever', so per-predicate dates cannot be composed;\ \ and jurisdiction geo_ids as a scope." operationId: search_properties_properties_search_get security: - APIKeyHeader: [] parameters: - name: geo_id in: query required: false schema: anyOf: - type: string - type: 'null' title: Geolocation ID description: 'Scope: a 2-letter state, 5-digit ZIP, ZIP+4, or a Shovels state/county/city/address geolocation id. Jurisdiction ids are not accepted. Optional when `legal_owner` is given, required otherwise.' description: 'Scope: a 2-letter state, 5-digit ZIP, ZIP+4, or a Shovels state/county/city/address geolocation id. Jurisdiction ids are not accepted. Optional when `legal_owner` is given, required otherwise.' - name: legal_owner in: query required: false schema: anyOf: - type: array items: type: string maxItems: 10 - type: 'null' title: Legal Owner description: "Filter by the property's legal owner, matched on the owner's\ \ canonical form \u2014 case and spacing variants of one name return the\ \ same properties. Pass up to 10 `legal_owner` params to span several\ \ owners. Without a `geo_id` this searches an owner's properties nationwide;\ \ with one it narrows that scope to the owner. A name the data uses for\ \ an unidentified owner (for example 'RECORD OWNER') is rejected." description: "Filter by the property's legal owner, matched on the owner's\ \ canonical form \u2014 case and spacing variants of one name return the\ \ same properties. Pass up to 10 `legal_owner` params to span several owners.\ \ Without a `geo_id` this searches an owner's properties nationwide; with\ \ one it narrows that scope to the owner. A name the data uses for an unidentified\ \ owner (for example 'RECORD OWNER') is rejected." - name: permit_tags in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Permit Tags description: "Filter by canonical permit tags. Repeat the key for several\ \ tags (e.g. `?permit_tags=roofing&permit_tags=-solar`). A positive tag\ \ keeps properties with that tag on some permit; a `-` prefix excludes\ \ the tag (properties without it). Multiple positive tags require each\ \ tag (address grain \u2014 a documented divergence from /permits/search,\ \ where they must share one permit). With `permit_status`, each positive\ \ tag must be matched by a permit that also has one of the statuses. With\ \ `permit_from`: a positive tag matches since the date; an exclusion means\ \ 'no such tag since the date' in a pure-absence query, or 'never' when\ \ combined with any positive filter." description: "Filter by canonical permit tags. Repeat the key for several\ \ tags (e.g. `?permit_tags=roofing&permit_tags=-solar`). A positive tag\ \ keeps properties with that tag on some permit; a `-` prefix excludes the\ \ tag (properties without it). Multiple positive tags require each tag (address\ \ grain \u2014 a documented divergence from /permits/search, where they\ \ must share one permit). With `permit_status`, each positive tag must be\ \ matched by a permit that also has one of the statuses. With `permit_from`:\ \ a positive tag matches since the date; an exclusion means 'no such tag\ \ since the date' in a pure-absence query, or 'never' when combined with\ \ any positive filter." - name: permit_status in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Permit Status description: Filter by permit status; repeat the key for several (final, in_review, inactive, active). With positive `permit_tags` this is a same-permit conjunction; on its own it keeps properties with a permit of one of the statuses. 'unknown' is not a filterable status. description: Filter by permit status; repeat the key for several (final, in_review, inactive, active). With positive `permit_tags` this is a same-permit conjunction; on its own it keeps properties with a permit of one of the statuses. 'unknown' is not a filterable status. - name: permit_from in: query required: false schema: anyOf: - type: string format: date - type: 'null' title: Permit From description: 'Bind the tag/status/absence filters to this ISO date (YYYY-MM-DD): a positive filter matches since the date, a pure-absence exclusion means ''none since the date''. With no tag/status filter it keeps properties whose most recent permit is on or after the date.' description: 'Bind the tag/status/absence filters to this ISO date (YYYY-MM-DD): a positive filter matches since the date, a pure-absence exclusion means ''none since the date''. With no tag/status filter it keeps properties whose most recent permit is on or after the date.' - name: permit_to in: query required: false schema: anyOf: - type: string - type: 'null' title: Permit To description: "Not supported on /properties/search \u2014 use /permits/search\ \ for a date-window search." description: "Not supported on /properties/search \u2014 use /permits/search\ \ for a date-window search." - name: property_type in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: 'Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational. Repeat the key to match any of several types (e.g. `?property_type=residential&property_type=commercial`). Properties with no attributed type are excluded; property attributes are available for 70.1% of properties.' title: Property Type description: 'Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational. Repeat the key to match any of several types (e.g. `?property_type=residential&property_type=commercial`). Properties with no attributed type are excluded; property attributes are available for 70.1% of properties.' - name: permit_tags_unfinaled in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Permit Tags Unfinaled description: "Keep properties with an UNFINALED permit of each named canonical\ \ tag. Repeat the key for several (e.g. `?permit_tags_unfinaled=solar&permit_tags_unfinaled=roofing`).\ \ Permit status \u2014 not a permit's final_date \u2014 is the finaled\ \ flag: a final permit carries a NULL final_date 14.7% of the time, and\ \ ~41% of permits with a NULL final_date are in fact finaled by status,\ \ so a `final_date IS NULL` test over-counts unfinaled permits and is\ \ wrong ~41% of the time. A tag is unfinaled for an address only when\ \ its latest non-final permit of that tag is more recent than its latest\ \ final permit of that tag (equal dates count as finaled); this clear\ \ rule removes the false positives a plain 'any non-final permit of this\ \ tag' test would keep \u2014 for solar, 31.5% of them, though the share\ \ varies by tag (nearer 13-18% for tags such as roofing and hvac). A permit\ \ whose status is unknown (NULL) counts as neither final nor unfinaled.\ \ With `permit_from`, the tag's latest unfinaled permit must be on or\ \ after the date." description: "Keep properties with an UNFINALED permit of each named canonical\ \ tag. Repeat the key for several (e.g. `?permit_tags_unfinaled=solar&permit_tags_unfinaled=roofing`).\ \ Permit status \u2014 not a permit's final_date \u2014 is the finaled flag:\ \ a final permit carries a NULL final_date 14.7% of the time, and ~41% of\ \ permits with a NULL final_date are in fact finaled by status, so a `final_date\ \ IS NULL` test over-counts unfinaled permits and is wrong ~41% of the time.\ \ A tag is unfinaled for an address only when its latest non-final permit\ \ of that tag is more recent than its latest final permit of that tag (equal\ \ dates count as finaled); this clear rule removes the false positives a\ \ plain 'any non-final permit of this tag' test would keep \u2014 for solar,\ \ 31.5% of them, though the share varies by tag (nearer 13-18% for tags\ \ such as roofing and hvac). A permit whose status is unknown (NULL) counts\ \ as neither final nor unfinaled. With `permit_from`, the tag's latest unfinaled\ \ permit must be on or after the date." - name: property_min_market_value in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Property Market Value description: Minimum assessed market value in integer cents (dollars x 100). A property with no assessed market value never matches a range filter (a value is available for 61.0% of properties). description: Minimum assessed market value in integer cents (dollars x 100). A property with no assessed market value never matches a range filter (a value is available for 61.0% of properties). - name: property_max_market_value in: query required: false schema: anyOf: - type: integer - type: 'null' title: Maximum Property Market Value description: Maximum assessed market value in integer cents (dollars x 100). A property with no assessed market value never matches a range filter (a value is available for 61.0% of properties). description: Maximum assessed market value in integer cents (dollars x 100). A property with no assessed market value never matches a range filter (a value is available for 61.0% of properties). - name: property_min_lot_size in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Property Lot Size description: Minimum lot size in square feet. A property with no lot size never matches a range filter (a value is available for 68.7% of properties). description: Minimum lot size in square feet. A property with no lot size never matches a range filter (a value is available for 68.7% of properties). - name: property_max_lot_size in: query required: false schema: anyOf: - type: integer - type: 'null' title: Maximum Property Lot Size description: Maximum lot size in square feet. A property with no lot size never matches a range filter (a value is available for 68.7% of properties). description: Maximum lot size in square feet. A property with no lot size never matches a range filter (a value is available for 68.7% of properties). - name: property_min_building_area in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Property Building Area description: Minimum building area in square feet. A property with no building area never matches a range filter (a value is available for 60.8% of properties). description: Minimum building area in square feet. A property with no building area never matches a range filter (a value is available for 60.8% of properties). - name: property_max_building_area in: query required: false schema: anyOf: - type: integer - type: 'null' title: Maximum Property Building Area description: Maximum building area in square feet. A property with no building area never matches a range filter (a value is available for 60.8% of properties). description: Maximum building area in square feet. A property with no building area never matches a range filter (a value is available for 60.8% of properties). - name: property_min_unit_count in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Property Unit Count description: Minimum unit count. A property with no unit count never matches a range filter (a value is available for 70.1% of properties). description: Minimum unit count. A property with no unit count never matches a range filter (a value is available for 70.1% of properties). - name: property_max_unit_count in: query required: false schema: anyOf: - type: integer - type: 'null' title: Maximum Property Unit Count description: Maximum unit count. A property with no unit count never matches a range filter (a value is available for 70.1% of properties). description: Maximum unit count. A property with no unit count never matches a range filter (a value is available for 70.1% of properties). - name: property_min_year_built in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Property Year Built description: Minimum year built. A property with no year built never matches a range filter (a value is available for 61.1% of properties). description: Minimum year built. A property with no year built never matches a range filter (a value is available for 61.1% of properties). - name: property_max_year_built in: query required: false schema: anyOf: - type: integer - type: 'null' title: Maximum Property Year Built description: Maximum year built. A property with no year built never matches a range filter (a value is available for 61.1% of properties). description: Maximum year built. A property with no year built never matches a range filter (a value is available for 61.1% of properties). - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Opaque keyset cursor from a previous page's next_cursor. title: Cursor description: Opaque keyset cursor from a previous page's next_cursor. - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Page size (1-100). default: 50 title: Size description: Page size (1-100). - name: include_total_count in: query required: false schema: type: boolean description: When true and on the first page (no cursor), include a total_count capped at 10,000. default: false title: Include Total Count description: When true and on the first page (no cursor), include a total_count capped at 10,000. responses: '200': description: A page of properties in the scope. content: application/json: schema: $ref: '#/components/schemas/PaginatedPropertiesResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /usage: get: tags: - Usage summary: Get Usage description: Get your current credit usage for the rolling 30-day period. operationId: get_usage_usage_get responses: '200': description: Current credit usage and limit content: application/json: schema: $ref: '#/components/schemas/UsageResponse' security: - APIKeyHeader: [] components: schemas: AddressesEmbedded: properties: street_no: anyOf: - type: string - type: 'null' title: Street No description: The number of the street of the address. street: anyOf: - type: string - type: 'null' title: Street description: The name of the street of the address. city: anyOf: - type: string - type: 'null' title: City description: The city of the address. county: anyOf: - type: string - type: 'null' title: County description: The county of the address. zip_code: anyOf: - type: string - type: 'null' title: Zip Code description: The ZIP code of the address. zip_code_ext: anyOf: - type: string - type: 'null' title: Zip Code Ext description: The extension of the ZIP code of the address. state: anyOf: - type: string - type: 'null' title: State description: The state of the address. jurisdiction: anyOf: - type: string - type: 'null' title: Jurisdiction description: The jurisdiction the address belongs to. address_id: anyOf: - type: string - type: 'null' title: Address Id description: The address identifier. latlng: anyOf: - items: anyOf: - type: number - type: 'null' type: array - type: 'null' title: Latlng description: The latitude and longitude of the address. type: object title: AddressesEmbedded description: Schema for embedded address object with location data to be used as a nested JSON object. AddressesMetricsCurrentRead: properties: geo_id: type: string title: Geo Id description: Unique identifier for the entity tag: anyOf: - type: string - type: 'null' title: Tag description: Specific tag or category for the metrics permit_count: anyOf: - type: integer - type: 'null' title: Permit Count description: Total number of permits issued contractor_count: anyOf: - type: integer - type: 'null' title: Contractor Count description: Total number of unique contractors avg_construction_duration: anyOf: - type: integer - type: 'null' title: Avg Construction Duration description: Average duration of construction projects in days avg_approval_duration: anyOf: - type: integer - type: 'null' title: Avg Approval Duration description: Average duration of permit approval process in days total_job_value: anyOf: - type: integer - type: 'null' title: Total Job Value description: "Total value of all jobs/permits in cents (integer value representing\ \ dollars \xD7 100)" avg_inspection_pass_rate: anyOf: - type: integer - type: 'null' title: Avg Inspection Pass Rate description: Average pass rate for inspections (percentage in integer format 0-100) permit_active_count: anyOf: - type: integer - type: 'null' title: Permit Active Count description: Total number of permits in active status permit_in_review_count: anyOf: - type: integer - type: 'null' title: Permit In Review Count description: Total number of permits in review status type: object required: - geo_id - tag title: AddressesMetricsCurrentRead description: Read model for current address metrics. AddressesMetricsMonthlyRead: properties: geo_id: type: string title: Geo Id description: Unique identifier for the entity tag: anyOf: - type: string - type: 'null' title: Tag description: Specific tag or category for the metrics permit_count: anyOf: - type: integer - type: 'null' title: Permit Count description: Total number of permits issued contractor_count: anyOf: - type: integer - type: 'null' title: Contractor Count description: Total number of unique contractors avg_construction_duration: anyOf: - type: integer - type: 'null' title: Avg Construction Duration description: Average duration of construction projects in days avg_approval_duration: anyOf: - type: integer - type: 'null' title: Avg Approval Duration description: Average duration of permit approval process in days total_job_value: anyOf: - type: integer - type: 'null' title: Total Job Value description: "Total value of all jobs/permits in cents (integer value representing\ \ dollars \xD7 100)" avg_inspection_pass_rate: anyOf: - type: integer - type: 'null' title: Avg Inspection Pass Rate description: Average pass rate for inspections (percentage in integer format 0-100) date: type: string format: date title: Date description: The month for which the metrics are calculated type: object required: - geo_id - tag - date title: AddressesMetricsMonthlyRead description: Read model for monthly address metrics. CitiesDetailsRead: properties: geo_id: type: string title: Geo Id description: Geolocation ID name: type: string title: Name description: Formatted entity name state: type: string title: State description: State abbreviation counties: anyOf: - additionalProperties: anyOf: - type: string - type: 'null' type: object - type: 'null' title: Counties default: {} jurisdictions: anyOf: - additionalProperties: anyOf: - type: string - type: 'null' type: object - type: 'null' title: Jurisdictions default: {} zipcodes: anyOf: - items: anyOf: - type: string - type: 'null' type: array - type: 'null' title: Zipcodes type: object required: - geo_id - name - state title: CitiesDetailsRead description: City-specific details read model. CitiesMetricsCurrentRead: properties: geo_id: type: string title: Geo Id description: Unique identifier for the entity tag: anyOf: - type: string - type: 'null' title: Tag description: Specific tag or category for the metrics permit_count: anyOf: - type: integer - type: 'null' title: Permit Count description: Total number of permits issued contractor_count: anyOf: - type: integer - type: 'null' title: Contractor Count description: Total number of unique contractors avg_construction_duration: anyOf: - type: integer - type: 'null' title: Avg Construction Duration description: Average duration of construction projects in days avg_approval_duration: anyOf: - type: integer - type: 'null' title: Avg Approval Duration description: Average duration of permit approval process in days total_job_value: anyOf: - type: integer - type: 'null' title: Total Job Value description: "Total value of all jobs/permits in cents (integer value representing\ \ dollars \xD7 100)" avg_inspection_pass_rate: anyOf: - type: integer - type: 'null' title: Avg Inspection Pass Rate description: Average pass rate for inspections (percentage in integer format 0-100) permit_active_count: anyOf: - type: integer - type: 'null' title: Permit Active Count description: Total number of permits in active status permit_in_review_count: anyOf: - type: integer - type: 'null' title: Permit In Review Count description: Total number of permits in review status property_type: anyOf: - type: string - type: 'null' title: Property Type description: Type of property (e.g., residential, commercial) type: object required: - geo_id - tag title: CitiesMetricsCurrentRead description: Read model for current city metrics. CitiesMetricsMonthlyRead: properties: geo_id: type: string title: Geo Id description: Unique identifier for the entity tag: anyOf: - type: string - type: 'null' title: Tag description: Specific tag or category for the metrics permit_count: anyOf: - type: integer - type: 'null' title: Permit Count description: Total number of permits issued contractor_count: anyOf: - type: integer - type: 'null' title: Contractor Count description: Total number of unique contractors avg_construction_duration: anyOf: - type: integer - type: 'null' title: Avg Construction Duration description: Average duration of construction projects in days avg_approval_duration: anyOf: - type: integer - type: 'null' title: Avg Approval Duration description: Average duration of permit approval process in days total_job_value: anyOf: - type: integer - type: 'null' title: Total Job Value description: "Total value of all jobs/permits in cents (integer value representing\ \ dollars \xD7 100)" avg_inspection_pass_rate: anyOf: - type: integer - type: 'null' title: Avg Inspection Pass Rate description: Average pass rate for inspections (percentage in integer format 0-100) date: type: string format: date title: Date description: The month for which the metrics are calculated property_type: anyOf: - type: string - type: 'null' title: Property Type description: Type of property (e.g., residential, commercial) type: object required: - geo_id - tag - date title: CitiesMetricsMonthlyRead description: Read model for monthly city metrics. ContractorsMetricsMonthlyRead: properties: property_type: anyOf: - type: string - type: 'null' title: Property Type description: Type of property (e.g., residential, commercial) date: type: string format: date title: Date description: The month for which the metrics are calculated tag: anyOf: - type: string - type: 'null' title: Tag description: Specific tag or category for the metrics permit_count: anyOf: - type: integer - type: 'null' title: Permit Count description: Total number of permits issued avg_job_value: anyOf: - type: integer - type: 'null' title: Avg Job Value description: "The average job value of all permits in cents (integer value\ \ representing dollars \xD7 100)." total_job_value: anyOf: - type: integer - type: 'null' title: Total Job Value description: "Total value of all jobs/permits in cents (integer value representing\ \ dollars \xD7 100)" avg_construction_duration: anyOf: - type: integer - type: 'null' title: Avg Construction Duration description: Average duration of construction projects in days avg_inspection_pass_rate: anyOf: - type: integer - type: 'null' title: Avg Inspection Pass Rate description: Average pass rate for inspections (percentage in integer format 0-100) type: object required: - date - tag title: ContractorsMetricsMonthlyRead description: Schema for contractor's monthly metrics. ContractorsRead: properties: id: type: string title: Id description: The contractor ID. license: anyOf: - type: string - type: 'null' title: License description: The contractor license number. name: anyOf: - type: string - type: 'null' title: Name description: The contractor name. business_name: anyOf: - type: string - type: 'null' title: Business Name description: The contractor business name. business_type: anyOf: - type: string - type: 'null' title: Business Type description: 'The type of business: JointVenture, Corporation, Partnership, Limited Liability, Sole Owner.' classification: anyOf: - type: string - type: 'null' title: Classification description: The contractor's classification/certification. classification_derived: anyOf: - items: type: string type: array - type: 'null' title: Classification Derived description: Array of derived contractor classifications. license_issue_date: anyOf: - type: string format: date - type: 'null' title: License Issue Date description: The license issue date. license_exp_date: anyOf: - type: string format: date - type: 'null' title: License Exp Date description: The license expiration date. license_inact_date: anyOf: - type: string format: date - type: 'null' title: License Inact Date description: Date when the contractor's license became inactive. license_act_date: anyOf: - type: string format: date - type: 'null' title: License Act Date description: Date when the contractor's license became active. primary_phone: anyOf: - type: string - type: 'null' title: Primary Phone description: The contractor's primary phone number. primary_email: anyOf: - type: string - type: 'null' title: Primary Email description: The contractor's primary email. phone: anyOf: - type: string - type: 'null' title: Phone description: The contractor's phone number(s). email: anyOf: - type: string - type: 'null' title: Email description: The contractor's email(s). website: anyOf: - type: string - type: 'null' title: Website description: The contractor's website). dba: anyOf: - type: string - type: 'null' title: Dba description: Doing Business As name for the contractor. sic: anyOf: - type: string - type: 'null' title: Sic description: Standard Industrial Classification (SIC) code of the contractor. naics: anyOf: - type: string - type: 'null' title: Naics description: North American Industry Classification System (NAICS) code of the contractor. linkedin_url: anyOf: - type: string - type: 'null' title: Linkedin Url description: LinkedIn URL of the contractor. revenue: anyOf: - type: string - type: 'null' title: Revenue description: Annual revenue of the contractor's business. employee_count: anyOf: - type: string - type: 'null' title: Employee Count description: Number of employees working for the contractor. primary_industry: anyOf: - type: string - type: 'null' title: Primary Industry description: Primary industry in which the contractor operates. review_count: anyOf: - type: integer - type: 'null' title: Review Count description: Number of reviews the contractor has received. rating: anyOf: - type: number - type: 'null' title: Rating description: Rating of the contractor based on reviews. status_tally: anyOf: - additionalProperties: type: integer type: object - type: 'null' title: Status Tally description: 'Permit counts by status (active, final, unknown, inactive, in_review). On /contractors/search: filtered by geo and date range parameters. On /contractors (get by ID): unfiltered lifetime counts.' default: {} tag_tally: anyOf: - additionalProperties: type: integer type: object - type: 'null' title: Tag Tally description: "Permit counts by tag. Each permit is counted once under every\ \ tag it has \u2014 a permit tagged both 'solar' and 'electrical' adds\ \ 1 to each. On /contractors/search: filtered by geo and date range parameters.\ \ On /contractors (get by ID): unfiltered lifetime counts, so the values\ \ can add up to more than permit_count." default: {} permit_count: anyOf: - type: integer - type: 'null' title: Permit Count description: Contractor lifetime total permit count across all locations and dates. Not filtered by search parameters. avg_job_value: anyOf: - type: integer - type: 'null' title: Avg Job Value description: "The average job value of all permits in cents (integer value\ \ representing dollars \xD7 100)." total_job_value: anyOf: - type: integer - type: 'null' title: Total Job Value description: "The total job value of all permits in cents (integer value\ \ representing dollars \xD7 100)." avg_construction_duration: anyOf: - type: integer - type: 'null' title: Avg Construction Duration description: The average construction duration in days. avg_inspection_pass_rate: anyOf: - type: integer - type: 'null' title: Avg Inspection Pass Rate description: The average inspection pass rate as a percentage (0-100). first_seen_date: anyOf: - type: string format: date - type: 'null' title: First Seen Date description: Date when the contractor was first seen in the system. address: anyOf: - $ref: '#/components/schemas/AddressesEmbedded' - type: 'null' description: The contractor's address dictionary that contains street_no, street, city, jurisdiction, zip_code, zip_code_ext, state, and latlng fields. type: object required: - id - address title: ContractorsRead description: Schema for contractor response with embedded address. CountiesDetailsRead: properties: geo_id: type: string title: Geo Id description: Geolocation ID name: type: string title: Name description: Formatted entity name state: type: string title: State description: State abbreviation cities: anyOf: - additionalProperties: anyOf: - type: string - type: 'null' type: object - type: 'null' title: Cities default: {} jurisdictions: anyOf: - additionalProperties: anyOf: - type: string - type: 'null' type: object - type: 'null' title: Jurisdictions default: {} zipcodes: anyOf: - items: anyOf: - type: string - type: 'null' type: array - type: 'null' title: Zipcodes type: object required: - geo_id - name - state title: CountiesDetailsRead description: County-specific details read model. CountiesMetricsCurrentRead: properties: geo_id: type: string title: Geo Id description: Unique identifier for the entity tag: anyOf: - type: string - type: 'null' title: Tag description: Specific tag or category for the metrics permit_count: anyOf: - type: integer - type: 'null' title: Permit Count description: Total number of permits issued contractor_count: anyOf: - type: integer - type: 'null' title: Contractor Count description: Total number of unique contractors avg_construction_duration: anyOf: - type: integer - type: 'null' title: Avg Construction Duration description: Average duration of construction projects in days avg_approval_duration: anyOf: - type: integer - type: 'null' title: Avg Approval Duration description: Average duration of permit approval process in days total_job_value: anyOf: - type: integer - type: 'null' title: Total Job Value description: "Total value of all jobs/permits in cents (integer value representing\ \ dollars \xD7 100)" avg_inspection_pass_rate: anyOf: - type: integer - type: 'null' title: Avg Inspection Pass Rate description: Average pass rate for inspections (percentage in integer format 0-100) permit_active_count: anyOf: - type: integer - type: 'null' title: Permit Active Count description: Total number of permits in active status permit_in_review_count: anyOf: - type: integer - type: 'null' title: Permit In Review Count description: Total number of permits in review status property_type: anyOf: - type: string - type: 'null' title: Property Type description: Type of property (e.g., residential, commercial) type: object required: - geo_id - tag title: CountiesMetricsCurrentRead description: Read model for current county metrics. CountiesMetricsMonthlyRead: properties: geo_id: type: string title: Geo Id description: Unique identifier for the entity tag: anyOf: - type: string - type: 'null' title: Tag description: Specific tag or category for the metrics permit_count: anyOf: - type: integer - type: 'null' title: Permit Count description: Total number of permits issued contractor_count: anyOf: - type: integer - type: 'null' title: Contractor Count description: Total number of unique contractors avg_construction_duration: anyOf: - type: integer - type: 'null' title: Avg Construction Duration description: Average duration of construction projects in days avg_approval_duration: anyOf: - type: integer - type: 'null' title: Avg Approval Duration description: Average duration of permit approval process in days total_job_value: anyOf: - type: integer - type: 'null' title: Total Job Value description: "Total value of all jobs/permits in cents (integer value representing\ \ dollars \xD7 100)" avg_inspection_pass_rate: anyOf: - type: integer - type: 'null' title: Avg Inspection Pass Rate description: Average pass rate for inspections (percentage in integer format 0-100) date: type: string format: date title: Date description: The month for which the metrics are calculated property_type: anyOf: - type: string - type: 'null' title: Property Type description: Type of property (e.g., residential, commercial) type: object required: - geo_id - tag - date title: CountiesMetricsMonthlyRead description: Read model for monthly county metrics. CoverageItem: properties: field: type: string enum: - fees - job_value - description - contractor_id - owner_name - property_type - property_year_built - property_building_area - issue_date - file_date title: Field description: Tracked permit field name (without 'has_' prefix). tier: type: string enum: - missing - partial - reliable title: Tier description: 'Coverage classification: ''missing'' (fill_pct < 0.10), ''partial'' (0.10 <= fill_pct < 0.80), ''reliable'' (fill_pct >= 0.80). The endpoint omits ''reliable'' rows from the response.' fill_pct: type: number title: Fill Pct description: Fraction of permits in the window with a populated value for this field, rounded to 3 decimals. 0.0 when permits_total is 0. permits_total: type: integer title: Permits Total description: Total permits in the requested (geo, date range) window across all tracked years. type: object required: - field - tier - fill_pct - permits_total title: CoverageItem description: 'One per-field coverage row returned by `/v2/meta/coverage`. Only `partial` and `missing` tiers are emitted; `reliable` fields are omitted so clients infer them by absence.' CoverageResponse: properties: items: items: $ref: '#/components/schemas/CoverageItem' type: array title: Items description: Per-field coverage rows for fields in the partial or missing tier, ordered by tier then field. type: object required: - items title: CoverageResponse description: 'Response envelope for `/v2/meta/coverage`. Bounded to at most 10 items (one per tracked field); no pagination.' DailyUsage: properties: date: type: string format: date title: Date credits: type: integer title: Credits expires: type: string format: date title: Expires type: object required: - date - credits - expires title: DailyUsage description: Single day's credit consumption with expiry date. DecisionsRead: properties: address_id: anyOf: - type: string - type: 'null' title: Address Id description: The address identifier. city_id: anyOf: - type: string - type: 'null' title: City Id description: The city ID for the address. county_id: anyOf: - type: string - type: 'null' title: County Id description: The county ID for the address. jurisdiction_id: anyOf: - type: string - type: 'null' title: Jurisdiction Id description: The jurisdiction ID for the address. street: anyOf: - type: string - type: 'null' title: Street description: The street of the property. city: anyOf: - type: string - type: 'null' title: City description: The city of the property. state: anyOf: - type: string - type: 'null' title: State description: The state of the property. latitude: anyOf: - type: number - type: 'null' title: Latitude description: The latitude of the property. longitude: anyOf: - type: number - type: 'null' title: Longitude description: The longitude of the property. id: type: string title: Id description: The decision identifier. title: anyOf: - type: string - type: 'null' title: Title description: The title of the decision. decision_date: anyOf: - type: string format: date - type: 'null' title: Decision Date description: The date the decision was made. description: anyOf: - type: string - type: 'null' title: Description description: A free-form description of the decision. source_url: anyOf: - type: string - type: 'null' title: Source Url description: The URL of the source meeting record. asset_class: anyOf: - type: string - type: 'null' title: Asset Class description: The asset class of the decision (e.g. Residential, Commercial, Mixed-Use). category: anyOf: - type: string - type: 'null' title: Category description: The category of the decision (e.g. Rezoning, Variance). subcategory: anyOf: - type: string - type: 'null' title: Subcategory description: The subcategory of the decision. property_type: anyOf: - type: string - type: 'null' title: Property Type description: The type of property involved in the decision. why_it_matters: anyOf: - type: string - type: 'null' title: Why It Matters description: A short explanation of why the decision matters. applicant_name: anyOf: - type: string - type: 'null' title: Applicant Name description: The name of the applicant on the decision. owner_name: anyOf: - type: string - type: 'null' title: Owner Name description: The name of the property owner. representative_name: anyOf: - type: string - type: 'null' title: Representative Name description: The name of the representative on the decision. developer_name: anyOf: - type: string - type: 'null' title: Developer Name description: The name of the developer on the decision. zoning_previous: anyOf: - type: string - type: 'null' title: Zoning Previous description: The previous zoning designation. zoning_new: anyOf: - type: string - type: 'null' title: Zoning New description: The new zoning designation. allowed_uses: anyOf: - type: string - type: 'null' title: Allowed Uses description: The allowed uses under the decision. project_value: anyOf: - type: integer - type: 'null' title: Project Value description: "The project value in cents (integer value representing dollars\ \ \xD7 100)." lot_size: anyOf: - type: integer - type: 'null' title: Lot Size description: The lot size in square feet. type: object required: - id title: DecisionsRead description: Schema for complete decision details in API responses. Employees: properties: id: type: string title: Id description: Unique identifier for the person. contractor_id: type: string title: Contractor Id description: The contractor identifier this employee belongs to. name: anyOf: - type: string - type: 'null' title: Name description: Full name of the employee. street_no: anyOf: - type: string - type: 'null' title: Street No description: Street number of employee's address. street: anyOf: - type: string - type: 'null' title: Street description: Street name of employee's address. city: anyOf: - type: string - type: 'null' title: City description: City of employee's address. zip_code: anyOf: - type: string - type: 'null' title: Zip Code description: ZIP code of employee's address. zip_code_ext: anyOf: - type: string - type: 'null' title: Zip Code Ext description: ZIP code extension. state: anyOf: - type: string - type: 'null' title: State description: State of employee's address. phone: anyOf: - type: string - type: 'null' title: Phone description: Employee's phone number. email: anyOf: - type: string - type: 'null' title: Email description: Employee's personal email. business_email: anyOf: - type: string - type: 'null' title: Business Email description: Employee's business email. linkedin_url: anyOf: - type: string - type: 'null' title: Linkedin Url description: Employee's LinkedIn profile URL. homeowner: anyOf: - type: string - type: 'null' title: Homeowner description: Homeowner status. gender: anyOf: - type: string - type: 'null' title: Gender description: Gender of the employee. age_range: anyOf: - type: string - type: 'null' title: Age Range description: Age range of the employee. is_married: anyOf: - type: boolean - type: 'null' title: Is Married description: Marital status of the employee. has_children: anyOf: - type: boolean - type: 'null' title: Has Children description: Whether the employee has children. income_range: anyOf: - type: string - type: 'null' title: Income Range description: Income range of the employee. net_worth: anyOf: - type: string - type: 'null' title: Net Worth description: Net worth range of the employee. job_title: anyOf: - type: string - type: 'null' title: Job Title description: Current job title of the employee. seniority_level: anyOf: - type: string - type: 'null' title: Seniority Level description: Seniority level in the organization. department: anyOf: - type: string - type: 'null' title: Department description: Department the employee works in. type: object required: - id - contractor_id title: Employees description: Employees table. GeoEntitiesRead: properties: geo_id: type: string title: Geo Id description: Geolocation ID name: type: string title: Name description: Formatted entity name state: type: string title: State description: State abbreviation type: object required: - geo_id - name - state title: GeoEntitiesRead description: Base read model for geographic entities used in geo search API responses. GeoIdsRead: properties: address_id: anyOf: - type: string - type: 'null' title: Address Id description: The address identifier. city_id: anyOf: - type: string - type: 'null' title: City Id description: The city ID for the address. county_id: anyOf: - type: string - type: 'null' title: County Id description: The county ID for the address. jurisdiction_id: anyOf: - type: string - type: 'null' title: Jurisdiction Id description: The jurisdiction ID for the address. type: object title: GeoIdsRead description: Base64 encoded geographic identifiers embedded in response. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError JurisdictionsDetailsRead: properties: geo_id: type: string title: Geo Id description: Geolocation ID name: type: string title: Name description: Formatted entity name state: type: string title: State description: State abbreviation cities: anyOf: - additionalProperties: anyOf: - type: string - type: 'null' type: object - type: 'null' title: Cities default: {} counties: anyOf: - additionalProperties: anyOf: - type: string - type: 'null' type: object - type: 'null' title: Counties default: {} zipcodes: anyOf: - items: anyOf: - type: string - type: 'null' type: array - type: 'null' title: Zipcodes type: object required: - geo_id - name - state title: JurisdictionsDetailsRead description: Jurisdiction-specific details read model. JurisdictionsMetricsCurrentRead: properties: geo_id: type: string title: Geo Id description: Unique identifier for the entity tag: anyOf: - type: string - type: 'null' title: Tag description: Specific tag or category for the metrics permit_count: anyOf: - type: integer - type: 'null' title: Permit Count description: Total number of permits issued contractor_count: anyOf: - type: integer - type: 'null' title: Contractor Count description: Total number of unique contractors avg_construction_duration: anyOf: - type: integer - type: 'null' title: Avg Construction Duration description: Average duration of construction projects in days avg_approval_duration: anyOf: - type: integer - type: 'null' title: Avg Approval Duration description: Average duration of permit approval process in days total_job_value: anyOf: - type: integer - type: 'null' title: Total Job Value description: "Total value of all jobs/permits in cents (integer value representing\ \ dollars \xD7 100)" avg_inspection_pass_rate: anyOf: - type: integer - type: 'null' title: Avg Inspection Pass Rate description: Average pass rate for inspections (percentage in integer format 0-100) permit_active_count: anyOf: - type: integer - type: 'null' title: Permit Active Count description: Total number of permits in active status permit_in_review_count: anyOf: - type: integer - type: 'null' title: Permit In Review Count description: Total number of permits in review status property_type: anyOf: - type: string - type: 'null' title: Property Type description: Type of property (e.g., residential, commercial) type: object required: - geo_id - tag title: JurisdictionsMetricsCurrentRead description: Read model for current jurisdiction metrics. JurisdictionsMetricsMonthlyRead: properties: geo_id: type: string title: Geo Id description: Unique identifier for the entity tag: anyOf: - type: string - type: 'null' title: Tag description: Specific tag or category for the metrics permit_count: anyOf: - type: integer - type: 'null' title: Permit Count description: Total number of permits issued contractor_count: anyOf: - type: integer - type: 'null' title: Contractor Count description: Total number of unique contractors avg_construction_duration: anyOf: - type: integer - type: 'null' title: Avg Construction Duration description: Average duration of construction projects in days avg_approval_duration: anyOf: - type: integer - type: 'null' title: Avg Approval Duration description: Average duration of permit approval process in days total_job_value: anyOf: - type: integer - type: 'null' title: Total Job Value description: "Total value of all jobs/permits in cents (integer value representing\ \ dollars \xD7 100)" avg_inspection_pass_rate: anyOf: - type: integer - type: 'null' title: Avg Inspection Pass Rate description: Average pass rate for inspections (percentage in integer format 0-100) date: type: string format: date title: Date description: The month for which the metrics are calculated property_type: anyOf: - type: string - type: 'null' title: Property Type description: Type of property (e.g., residential, commercial) type: object required: - geo_id - tag - date title: JurisdictionsMetricsMonthlyRead description: Read model for monthly jurisdiction metrics. Metadata: properties: released_at: type: string format: date title: Released At description: The date of the current data release. type: object required: - released_at title: Metadata PaginatedAddressesMetricsCurrent: properties: items: items: $ref: '#/components/schemas/AddressesMetricsCurrentRead' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedAddressesMetricsCurrent description: Schema for cursor-paginated address current metrics response. PaginatedAddressesMetricsMonthly: properties: items: items: $ref: '#/components/schemas/AddressesMetricsMonthlyRead' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedAddressesMetricsMonthly description: Schema for cursor-paginated address monthly metrics response. PaginatedAddressesResponse: properties: items: items: $ref: '#/components/schemas/api__app__models__geo__AddressesRead' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedAddressesResponse description: Paginated response for addresses. PaginatedCitiesMetricsCurrent: properties: items: items: $ref: '#/components/schemas/CitiesMetricsCurrentRead' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedCitiesMetricsCurrent description: Schema for cursor-paginated city current metrics response. PaginatedCitiesMetricsMonthly: properties: items: items: $ref: '#/components/schemas/CitiesMetricsMonthlyRead' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedCitiesMetricsMonthly description: Schema for cursor-paginated city monthly metrics response. PaginatedContractorsMetrics: properties: items: items: $ref: '#/components/schemas/ContractorsMetricsMonthlyRead' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedContractorsMetrics description: Schema for cursor-paginated contractors metrics response. PaginatedContractorsResponse: properties: items: items: $ref: '#/components/schemas/ContractorsRead' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedContractorsResponse description: Schema for paginated contractors details response. PaginatedCountiesMetricsCurrent: properties: items: items: $ref: '#/components/schemas/CountiesMetricsCurrentRead' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedCountiesMetricsCurrent description: Schema for cursor-paginated county current metrics response. PaginatedCountiesMetricsMonthly: properties: items: items: $ref: '#/components/schemas/CountiesMetricsMonthlyRead' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedCountiesMetricsMonthly description: Schema for cursor-paginated county monthly metrics response. PaginatedDecisionsResponse: properties: items: items: $ref: '#/components/schemas/DecisionsRead' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedDecisionsResponse description: Schema for paginated decisions details response. PaginatedEmployeesResponse: properties: items: items: $ref: '#/components/schemas/Employees' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedEmployeesResponse description: Schema for paginated employees list response. PaginatedGeoEntitiesResponse: properties: items: items: $ref: '#/components/schemas/GeoEntitiesRead' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedGeoEntitiesResponse description: Paginated response for geographical entities. PaginatedJurisdictionsMetricsCurrent: properties: items: items: $ref: '#/components/schemas/JurisdictionsMetricsCurrentRead' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedJurisdictionsMetricsCurrent description: Schema for cursor-paginated jurisdiction current metrics response. PaginatedJurisdictionsMetricsMonthly: properties: items: items: $ref: '#/components/schemas/JurisdictionsMetricsMonthlyRead' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedJurisdictionsMetricsMonthly description: Schema for cursor-paginated jurisdiction monthly metrics response. PaginatedPermitsResponse: properties: items: items: $ref: '#/components/schemas/PermitsRead' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedPermitsResponse description: Schema for paginated permits details response. PaginatedPropertiesResponse: properties: items: items: $ref: '#/components/schemas/PropertiesRead' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. trust_summary: anyOf: - $ref: '#/components/schemas/TrustSummary' - type: 'null' description: Row-weighted trust summary; present only on absence-class responses. type: object required: - items - size - next_cursor title: PaginatedPropertiesResponse description: Paginated /properties response; carries the honesty summary on absence pages. PaginatedResidentsResponse: properties: items: items: $ref: '#/components/schemas/ResidentsRead' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedResidentsResponse description: Paginated response for residents. PaginatedStatesResponse: properties: items: items: $ref: '#/components/schemas/States' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedStatesResponse description: Paginated response for states. PaginatedTagsResponse: properties: items: items: $ref: '#/components/schemas/Tags' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedTagsResponse description: Paginated response for tags. PaginatedZipCodesResponse: properties: items: items: $ref: '#/components/schemas/ZipCodesView' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedZipCodesResponse description: Paginated response for ZIP codes view. PaginatedZipcodesResponse: properties: items: items: $ref: '#/components/schemas/Zipcodes' type: array title: Items description: The list of items returned in the response following given criteria. size: type: integer title: Size description: The number of items returned in the response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: The cursor for retrieving the next page of results. total_count: anyOf: - $ref: '#/components/schemas/TotalCount' - type: 'null' description: Total result count (capped at 10,000). Present on first-page responses when include_count=true. null if the count query timed out. type: object required: - items - size - next_cursor title: PaginatedZipcodesResponse description: Paginated response for zipcodes. PermitsRead: properties: property_census_tract: anyOf: - type: string - type: 'null' title: Property Census Tract description: The census tract identifier. property_congressional_district: anyOf: - type: string - type: 'null' title: Property Congressional District description: The congressional district identifier. property_type: anyOf: - type: string - type: 'null' title: Property Type description: The type of property. property_type_detail: anyOf: - type: string - type: 'null' title: Property Type Detail description: The detail type of property. property_legal_owner: anyOf: - type: string - type: 'null' title: Property Legal Owner description: The legal owner of the property. property_owner_type: anyOf: - type: string - type: 'null' title: Property Owner Type description: The type of property owner. property_lot_size: anyOf: - type: integer - type: 'null' title: Property Lot Size description: The lot size of the property. property_building_area: anyOf: - type: integer - type: 'null' title: Property Building Area description: The building area of the property. property_story_count: anyOf: - type: integer - type: 'null' title: Property Story Count description: The number of stories in the property. property_unit_count: anyOf: - type: integer - type: 'null' title: Property Unit Count description: The number of units in the property. property_year_built: anyOf: - type: integer - type: 'null' title: Property Year Built description: The year the property was built. property_assess_market_value: anyOf: - type: integer - type: 'null' title: Property Assess Market Value description: "The assessed market value of the property in cents (integer\ \ value representing dollars \xD7 100)." id: type: string title: Id description: The permit identifier. number: type: string title: Number description: The permit number provided by the jurisdiction. description: anyOf: - type: string - type: 'null' title: Description description: The description on the permit. This is a free-form text field that can contain any information about the permit. description_derived: anyOf: - type: string - type: 'null' title: Description Derived description: A normalized description inferred from the permit's free-form description, giving a consistent summary of the permitted work. jurisdiction: type: string title: Jurisdiction description: The jurisdiction where permit was filled. job_value: anyOf: - type: integer - type: 'null' title: Job Value description: "The reported job value on the permit in cents (integer value\ \ representing dollars \xD7 100)." type: anyOf: - type: string - type: 'null' title: Type description: The type of permit. subtype: anyOf: - type: string - type: 'null' title: Subtype description: The subtype of permit. fees: anyOf: - type: integer - type: 'null' title: Fees description: "The fees charged by the jurisdiction in cents (integer value\ \ representing dollars \xD7 100)." status: anyOf: - type: string - type: 'null' title: Status description: The status of the permit. file_date: anyOf: - type: string format: date - type: 'null' title: File Date description: The date the permit was filed. issue_date: anyOf: - type: string format: date - type: 'null' title: Issue Date description: The date the permit was issued. final_date: anyOf: - type: string format: date - type: 'null' title: Final Date description: The date the permit was finalized. start_date: anyOf: - type: string format: date - type: 'null' title: Start Date description: The earliest date out of `file_date`, `issue_date` and `final_date` that's found on the permit. end_date: anyOf: - type: string format: date - type: 'null' title: End Date description: The latest date out of `file_date`, `issue_date` and `final_date` that's found on the permit. total_duration: anyOf: - type: integer - type: 'null' title: Total Duration description: The number of days it took from `start_date` to `end_date`. construction_duration: anyOf: - type: integer - type: 'null' title: Construction Duration description: The number of days it took to complete the project. approval_duration: anyOf: - type: integer - type: 'null' title: Approval Duration description: The number of days it took to approve the permit. inspection_pass_rate: anyOf: - type: integer - type: 'null' title: Inspection Pass Rate description: The inspection pass rate as a percentage (0-100) contractor_id: anyOf: - type: string - type: 'null' title: Contractor Id description: The contractor identifier. tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: The tags associated with the permit. address: anyOf: - $ref: '#/components/schemas/api__app__models__permits__AddressesRead' - type: 'null' description: The address of the property. geo_ids: anyOf: - $ref: '#/components/schemas/GeoIdsRead' - type: 'null' description: Geographic identifiers. type: object required: - property_census_tract - property_congressional_district - property_type - property_type_detail - property_legal_owner - property_owner_type - property_lot_size - property_building_area - property_story_count - property_unit_count - property_year_built - property_assess_market_value - id - number - jurisdiction - address - geo_ids title: PermitsRead description: Schema for complete permit details in API responses. PropertiesRead: properties: id: type: string title: Id description: The base64 address handle; the property's public id. street_no: anyOf: - type: string - type: 'null' title: Street No description: Street number of the address. street: anyOf: - type: string - type: 'null' title: Street description: Street name of the address. city: anyOf: - type: string - type: 'null' title: City description: City of the address. city_id: anyOf: - type: string - type: 'null' title: City Id description: Base64 city handle. zip_code: anyOf: - type: string - type: 'null' title: Zip Code description: ZIP code of the address. zip_code_ext: anyOf: - type: string - type: 'null' title: Zip Code Ext description: ZIP+4 extension of the address. county: anyOf: - type: string - type: 'null' title: County description: County of the address. county_id: anyOf: - type: string - type: 'null' title: County Id description: Base64 county handle. state: anyOf: - type: string - type: 'null' title: State description: State of the address. lat: anyOf: - type: number - type: 'null' title: Lat description: Latitude of the address. long: anyOf: - type: number - type: 'null' title: Long description: Longitude of the address. permit_count: type: integer title: Permit Count description: Count of permits linked to the address. default: 0 untagged_permit_count: type: integer title: Untagged Permit Count description: Count of the address's permits carrying no canonical tag. default: 0 total_job_value: type: integer title: Total Job Value description: Sum of permit job values in integer cents (dollars x 100). default: 0 contractor_count: type: integer title: Contractor Count description: Distinct contractors across the address's permits. default: 0 tags: items: type: string type: array title: Tags description: Distinct canonical tags present on the address's permits. default: [] tag_status_pairs: items: type: string type: array title: Tag Status Pairs description: Distinct tag:status pairs (status folded to 'unknown' when NULL). default: [] statuses: items: type: string type: array title: Statuses description: Distinct permit statuses incl the 'unknown' NULL fold. default: [] tag_tally: additionalProperties: type: integer type: object title: Tag Tally description: Map tag -> permit count. default: {} last_date_by_tag: additionalProperties: type: string type: object title: Last Date By Tag description: Map tag -> latest permit start_date. default: {} last_unfinaled_date_by_tag: additionalProperties: type: string type: object title: Last Unfinaled Date By Tag description: Map tag -> latest non-final start_date under the clear rule. default: {} last_date_by_pair: additionalProperties: type: string type: object title: Last Date By Pair description: Map tag:status -> latest permit start_date. default: {} last_date_by_status: additionalProperties: type: string type: object title: Last Date By Status description: Map status -> latest permit start_date. default: {} last_permit_date: anyOf: - type: string format: date - type: 'null' title: Last Permit Date description: Latest permit start_date across all of the address's permits; null when never permitted. apn: anyOf: - type: string - type: 'null' title: Apn description: Assessor parcel number. property_type: anyOf: - type: string - type: 'null' title: Property Type description: Property type. property_type_detail: anyOf: - type: string - type: 'null' title: Property Type Detail description: Property type detail. year_built: anyOf: - type: integer - type: 'null' title: Year Built description: Year the property was built. lot_size: anyOf: - type: integer - type: 'null' title: Lot Size description: Lot size of the property. story_count: anyOf: - type: integer - type: 'null' title: Story Count description: Number of stories in the property. unit_count: anyOf: - type: integer - type: 'null' title: Unit Count description: Number of units in the property. building_area: anyOf: - type: integer - type: 'null' title: Building Area description: Building area of the property. assess_market_value: anyOf: - type: integer - type: 'null' title: Assess Market Value description: Assessed market value in integer cents (dollars x 100). owner_type: anyOf: - type: string - type: 'null' title: Owner Type description: Type of property owner. legal_owner: anyOf: - type: string - type: 'null' title: Legal Owner description: Legal owner of the property. trust: anyOf: - $ref: '#/components/schemas/PropertyTrust' - type: 'null' description: Per-row absence-honesty surface; present only on absence-class responses. type: object required: - id title: PropertiesRead description: 'Response schema for one property, served by both /properties endpoints. The public id is the base64 address handle. Presence arrays and the maps default to present-and-empty so a never-permitted row serializes zero counts and empty collections; attributes, dates, and trust are nullable. trust is None on non-absence responses and a PropertyTrust on absence responses (optional-by-polarity).' PropertyTrust: properties: unresolved_rate: type: number maximum: 1.0 minimum: 0.0 title: Unresolved Rate description: Share of the row jurisdiction's permits of the tag that never linked to an address. coverage_tier: type: string enum: - high - medium - low title: Coverage Tier description: Coverage bucket for the row's jurisdiction (90/50 cutoffs). data_horizon: type: string format: date title: Data Horizon description: Most recent start_date past which 'no X since D' is under-observed; never null. horizon_basis: type: string enum: - measured - pooled - prior title: Horizon Basis description: 'How data_horizon was estimated: a measured cohort, a pooled fallback, or the state prior.' trust_jurisdiction_basis: type: string enum: - own - dominant - unknown title: Trust Jurisdiction Basis description: Whether the trust join used the row's own jurisdiction, its ZIP's dominant one, or none. trust_jurisdiction_error_bar: type: number maximum: 1.0 minimum: 0.0 title: Trust Jurisdiction Error Bar description: 'Measured error rate of the trust jurisdiction: the 6.13% ZIP-dominant estimate error on a ''dominant'' basis, 0 on an ''own'' or ''unknown'' basis.' default: 0.0 footprint_basis: type: string enum: - matched - unknown title: Footprint Basis description: Whether footprint suppression could resolve the row's geo scope. flags: items: type: string type: array title: Flags description: Row-grain honesty flags, e.g. since_d_beyond_horizon or trust_row_missing. default: [] type: object required: - unresolved_rate - coverage_tier - data_horizon - horizon_basis - trust_jurisdiction_basis - footprint_basis title: PropertyTrust description: 'Per-row absence-honesty surface for one property in an absence-class response. Present and non-null on every row of an absence or mixed-exclusion response, absent on presence-only responses (optional-by-polarity, wired at the route). Every field is required: a row whose (jurisdiction, tag) trust lookup misses carries the conservative-fallback instance rather than a null object.' ResidentsRead: properties: name: anyOf: - type: string - type: 'null' title: Name personal_emails: anyOf: - type: string - type: 'null' title: Personal Emails phone: anyOf: - type: string - type: 'null' title: Phone linkedin_url: anyOf: - type: string - type: 'null' title: Linkedin Url net_worth: anyOf: - type: string - type: 'null' title: Net Worth income_range: anyOf: - type: string - type: 'null' title: Income Range is_homeowner: anyOf: - type: boolean - type: 'null' title: Is Homeowner street_no: anyOf: - type: string - type: 'null' title: Street No street: anyOf: - type: string - type: 'null' title: Street city: anyOf: - type: string - type: 'null' title: City state: anyOf: - type: string - type: 'null' title: State zip_code: anyOf: - type: string - type: 'null' title: Zip Code zip_code_ext: anyOf: - type: string - type: 'null' title: Zip Code Ext type: object title: ResidentsRead description: Read model for resident data. States: properties: geo_id: type: string title: Geo Id description: The state abbreviation. name: type: string title: Name description: The full name of the state. type: object required: - geo_id - name title: States description: Database model for the states table. Tags: properties: id: type: string title: Id description: The tag identifier. description: type: string title: Description description: The tag description. type: object required: - id - description title: Tags TotalCount: properties: value: type: integer minimum: 0.0 title: Value description: The count value; capped at the probe's cap (10,000 on the wire). relation: type: string enum: - eq - gte title: Relation description: '"eq" means value is the exact count. "gte" means the actual count is at least value (the cap).' type: object required: - value - relation title: TotalCount description: 'Capped result count with Elasticsearch-style {value, relation} shape. When the exact count is known and within the cap, relation is "eq" and value is that exact count. When the count exceeds the cap, relation is "gte" and value is the cap the count was probed against, meaning "the actual count is at least value". The cap is COUNT_CAP for every wire-facing endpoint; internal guard paths probe against their own cap, so value carries whatever cap produced it.' TrustSummary: properties: rows_flagged: type: integer minimum: 0.0 title: Rows Flagged description: Number of rows on the page carrying a trust flag. row_weighted_unresolved_rate: type: number maximum: 1.0 minimum: 0.0 title: Row Weighted Unresolved Rate description: Row-weighted mean unresolved_rate across the page. expected_miss_rate: type: number maximum: 1.0 minimum: 0.0 title: Expected Miss Rate description: Estimated share of true matches absent from arrived data due to ingestion lag. suppressed_scopes: type: integer minimum: 0.0 title: Suppressed Scopes description: Number of footprint scopes excluded from the result by suppression. type: object required: - rows_flagged - row_weighted_unresolved_rate - expected_miss_rate - suppressed_scopes title: TrustSummary description: Response-level, row-weighted absence-honesty summary for an absence-class page. UsageResponse: properties: credits_used: type: integer title: Credits Used description: Total credits used in the last 30 days. credit_limit: anyOf: - type: integer - type: 'null' title: Credit Limit description: Monthly credit limit. NULL means unlimited. is_over_limit: type: boolean title: Is Over Limit description: Whether the user has reached or exceeded their limit. available_at: anyOf: - type: string format: date - type: 'null' title: Available At description: Earliest date when expiring credits bring usage below limit. NULL if under limit or unlimited. daily_usage: items: $ref: '#/components/schemas/DailyUsage' type: array title: Daily Usage description: Daily credit consumption with expiry dates for the rolling 30-day window. type: object required: - credits_used - credit_limit - is_over_limit - available_at - daily_usage title: UsageResponse description: Response model for credit usage endpoint. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ZipCodesView: properties: zip_code: type: string title: Zip Code description: The ZIP code. type: object required: - zip_code title: ZipCodesView description: ZIP codes and ZIP code extensions that appear on permits. Zipcodes: properties: geo_id: type: string title: Geo Id description: The 5-digit ZIP code with optional 4-digit extension separated by -. state: type: string title: State description: The state of the ZIP code. type: object required: - geo_id - state title: Zipcodes description: Database model for the zipcodes table. api__app__models__geo__AddressesRead: properties: street_no: anyOf: - type: string - type: 'null' title: Street No description: The number of the street of the address. street: anyOf: - type: string - type: 'null' title: Street description: The name of the street of the address. city: anyOf: - type: string - type: 'null' title: City description: The city of the address. county: anyOf: - type: string - type: 'null' title: County description: The county of the address. zip_code: anyOf: - type: string - type: 'null' title: Zip Code description: The ZIP code of the address. zip_code_ext: anyOf: - type: string - type: 'null' title: Zip Code Ext description: The extension of the ZIP code of the address. state: anyOf: - type: string - type: 'null' title: State description: The state of the address. jurisdiction: anyOf: - type: string - type: 'null' title: Jurisdiction description: The jurisdiction the address belongs to. lat: anyOf: - type: number - type: 'null' title: Lat long: anyOf: - type: number - type: 'null' title: Long geo_id: type: string title: Geo Id description: Geolocation ID name: type: string title: Name description: Formatted address name type: object required: - geo_id - name title: AddressesRead description: Read model for address data with geolocation ID. api__app__models__permits__AddressesRead: properties: street_no: anyOf: - type: string - type: 'null' title: Street No description: The number of the street of the address. street: anyOf: - type: string - type: 'null' title: Street description: The name of the street of the address. city: anyOf: - type: string - type: 'null' title: City description: The city of the address. county: anyOf: - type: string - type: 'null' title: County description: The county of the address. zip_code: anyOf: - type: string - type: 'null' title: Zip Code description: The ZIP code of the address. zip_code_ext: anyOf: - type: string - type: 'null' title: Zip Code Ext description: The extension of the ZIP code of the address. state: anyOf: - type: string - type: 'null' title: State description: The state of the address. jurisdiction: anyOf: - type: string - type: 'null' title: Jurisdiction description: The jurisdiction the address belongs to. latlng: anyOf: - items: anyOf: - type: number - type: 'null' type: array - type: 'null' title: Latlng description: The latitude and longitude of the property. type: object title: AddressesRead description: Schema for embedded address object with coordinates. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key tags: - name: Meta description: Endpoints that provide information about the API and the data. - name: Lists description: Predefined lists of values and categories, such as tags and property types, which can be utilized as query parameters in other API interactions. - name: Permits description: Official documents issued by cities or counties before construction or alteration of a building can begin. - name: Decisions description: Zoning and land-use decisions extracted from city council and planning department meeting records. - name: Contractors description: Licensed professionals who do permitted work on residential and commercial buildings. - name: Properties description: "Addresses with their permit history, ownership and attributes, including\ \ absence queries \u2014 properties *without* a given kind of permit. **Beta.**\ \ Query parameters, response fields, and the absence-trust surface may still change\ \ in response to how the endpoint is used in practice. Treat the shape as unstable\ \ while it is in beta." - name: Addresses description: US address ID resolution, lookup and metrics endpoints. - name: Cities description: City ID resolution, lookup and metrics endpoints. - name: Counties description: County ID resolution, lookup and metrics endpoints. - name: Jurisdictions description: Jurisdiction ID resolution, lookup and metrics endpoints. - name: States description: State metrics endpoints. - name: Usage description: Credit usage tracking. servers: - url: https://api.shovels.ai/v2 description: Shovels API