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** | You will get this error if your reach your trial API call limit.\ \ |\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:\n\n```json\n\ {\n \"detail\": {\n \"error\": \"Monthly credit limit exceeded.\",\n \"\ limit\": 1000000\n }\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 by the geolocation ID: address, city, zip code, county, etc.' description: 'Filter by the geolocation ID: address, city, zip code, county, etc.' - name: permit_has_contractor in: query required: false schema: anyOf: - type: boolean - type: 'null' title: Has Contractor description: Return only records that have a contractor ID. description: Return only records that have a 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'. - 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. description: Filter by the minimum job value. - name: permit_min_fees in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Permit Fees description: Filter by minimum permit fees. description: Filter by minimum permit fees. - name: property_type in: query required: false schema: anyOf: - type: string - type: 'null' title: Property Type description: 'Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational.' description: 'Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational.' - 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. description: Minimum assessed market value of the property. - 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 - type: 'null' title: Contractor Name description: Filter by contractor's name or part of their name. description: Filter by contractor's name or part of their name. - 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. description: Minimum lifetime job value of the contractor. - 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 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 ' 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 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 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 ' 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 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' /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. 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. 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. description: Filter by the minimum job value. - name: permit_min_fees in: query required: false schema: anyOf: - type: integer - type: 'null' title: Minimum Permit Fees description: Filter by minimum permit fees. description: Filter by minimum permit fees. - 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 by the geolocation ID: address, city, zip code, county, etc.' description: 'Filter by the geolocation ID: address, city, zip code, county, etc.' - name: property_type in: query required: false schema: anyOf: - type: string - type: 'null' title: Property Type description: 'Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational.' description: 'Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational.' - 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. description: Minimum assessed market value of the property. - 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 - type: 'null' title: Contractor Name description: Filter by contractor's name or part of their name. description: Filter by contractor's name or part of their name. - 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. description: Minimum lifetime job value of the contractor. - 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 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 ' 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 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 for addresses that have at least one associated permit based on the provided text. 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: [] /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' /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: 'The summary of all status counts for contractors'' work. Available statuses: active, final, unknown, inactive, in_review.' default: {} tag_tally: anyOf: - additionalProperties: type: integer type: object - type: 'null' title: Tag Tally description: The summary of all tag counts for contractors' work. default: {} permit_count: anyOf: - type: integer - type: 'null' title: Permit Count description: The total number of permits. 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. 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. 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. 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. 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. 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. 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 10,000. relation: type: string enum: - eq - gte title: Relation description: '"eq" means value is the exact count. "gte" means the actual count is at least 10,000 (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 COUNT_CAP, relation is "eq". When the count exceeds COUNT_CAP, value is COUNT_CAP and relation is "gte", meaning "greater than or equal to COUNT_CAP".' 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 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: Contractors description: Licensed professionals who do permitted work on residential and commercial buildings. - 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