> ## Documentation Index > Fetch the complete documentation index at: https://docs.shovels.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get Permits By Id > Returns a list of permits records for given IDs. Results are paginated using cursor-based pagination for efficient navigation. ## OpenAPI ````yaml https://api.shovels.ai/spec/v2/openapi.production.yaml get /permits openapi: 3.1.0 info: title: The Shovels API v2 description: > The Shovels REST API makes it easy for technology developers in the property, climate, and construction industries to access detailed information about building permits, contractors and construction activity. Our API is designed to be intuitive and fast. We look forward to seeing what you build with it: [let us know](https://docs.google.com/forms/d/e/1FAIpQLSfs5Z6NZyPdnRpL96bMduH95OhfFZgLz9Hkc0-Y7pukUxSLxQ/viewform) and we'll check it out! ## Key Features The API offers access to two primary objects: **Permits** and **Contractors**. - **Permits**: Official documents issued by city or county authorities required before commencing construction or alterations to a building. - **Contractors**: Skilled professionals in the building trades who undertake permitted construction projects on various properties. And some additional resources: - **Lists**: Endpoints for predefined values like tags and property types for query parameters. - **Addresses**: Endpoint for searching and resolving valid US addresses. - **Meta**: Endpoints for metadata about the API and the data behind it. ## Getting started To begin using the API, please contact our sales team at [sales@shovels.ai](mailto:sales@shovels.ai) or grab a [free API key](https://app.shovels.ai/create-account/). > **Info**: The free API key has a limited number of calls. If you hit the limit and need more, please reach out to [sales@shovels.ai](mailto:sales@shovels.ai) or call us at [1-800-511-7457](tel:+18005117457). ### Authentication Our API uses a straightforward header-based authentication method: ``` X-API-Key: YOUR_API_KEY_HERE ``` Example Request: ```sh curl -X GET "https://api.shovels.ai/v2/meta/release" \ -H "X-API-Key: YOUR_API_KEY_HERE" ``` ## API Details ### Quick Overview A few quick details about our API: | Type | Description | |---------------------|----------------------------------------------------------------------------| | SSL only | We require that all requests are done over SSL. | | UTF-8 encoding | We use UTF-8 everywhere. | | Method | GET for all read calls. | | Date format | All dates in the API are strings in the following format: YYYY-MM-DD. | ### Response Types The API supports the following response codes: | Code | Description | |------|-------------| | **200 OK** | Everything worked as expected. | | **400 Bad Request** | There was something wrong with your request. Double-check your input. | | **401 Unauthorized** | You need to log in to access this. Make sure your API key is correct. | | **402 Payment Required** | You will get this error if your reach your trial API call limit. | | **403 Forbidden** | You don't have permission to access this. | | **404 Not Found** | We couldn't find what you're looking for. Check the URL or resource ID. | | **422 Unprocessable Entity** | There's an issue with the data you sent. Check [Error Handling](#error-handling) if you get this error. | | **429 Too Many Requests** | You're sending requests too quickly. Slow down and try again later. | | **500 Internal Server Error** | Yikes, something went wrong on our end. Please let us know at [support@shovels.ai](support@shovels.ai) | ### Data Format The API returns data in JSON format, either as pages or single objects. Paginated responses have the following structure: ```json { "items": [...], "size": 50, "next_cursor": "eyJkYXR..." | null } ``` Where objects are returned as an array in the 'items' field. ### Cursor-Based Pagination The API uses cursor-based pagination for all paginated endpoints. This method uses an opaque cursor token to maintain your position in the result set, offering better performance, consistency, and stability, especially for large datasets. ```json { "items": [...], "size": 50, "next_cursor": "eyJkYXR.lIjoiMjA.yMy0" } ``` To use cursor-based pagination: - For the first page: Simply make a request without any pagination parameters (or optionally specify `size` to control page size) - For subsequent pages: Include the `next_cursor` value from the previous response using the `cursor` parameter Example: ``` GET /v2/permits/search?size=10 GET /v2/permits/search?size=10&cursor=eyJkYXR.lIjoiMjA.yMy0 ``` When there are no more results, the `next_cursor` value will be `null`. ### Versioning The current version of the API is v2, which is reflected in the endpoints URL structure: `/v2/`. We plan to evolve our API by releasing new versions to ensure backward compatibility while maintaining a steady pace of continuous improvements. ### Error Handling Proper error messages and HTTP codes are provided to help you troubleshoot issues effectively. Refer to the [Response Types](#response-types) section for an overview of HTTP error codes and how to handle them. Below we describe how to interpret HTTP 422 code. #### 422 Unprocessable Entity A 422 Unprocessable Entity response occurs when the server understands the request but cannot process it due to invalid data. This helps you identify issues with your input. The response includes: - **loc**: The location of the error. The first value indicates the location and the second specifies the problematic field. Common values for the first value include: - **body**: The error is in the request body. - **query**: The error is in the query parameters. - **path**: The error is in the URL path. - **header**: The error is in the request headers. - **msg**: A message describing the error. - **type**: The type of error. This information helps you correct your request by pinpointing the exact issue. Here are some examples: **Request Body Error** ```json { "detail": [ { "loc": ["body", "first_name"], "msg": "Field is required", "type": "value_error.missing" } ] } ``` **Query Parameter Error** ```json { "detail": [ { "loc": ["query", "page"], "msg": "Page must be a positive integer", "type": "type_error.integer" } ] } ``` **Path Parameter Error** ```json { "detail": [ { "loc": ["path", "id"], "msg": "Invalid ID format", "type": "value_error.id" } ] } ``` **Header Error** ```json { "detail": [ { "loc": ["header", "X-API-Key"], "msg": "API key is missing", "type": "value_error.missing" } ] } ``` These examples show how different types of errors are reported, helping you to diagnose and fix issues in your API requests. ## Credit Limits API usage is tracked using credits. Each record returned counts as one credit. ### Response Headers Successful JSON responses that return records include credit headers: - `X-Credits-Request`: Credits consumed by this request - `X-Credits-Limit`: Your monthly credit limit (omitted if unlimited) - `X-Credits-Remaining`: Credits remaining in your limit (omitted if unlimited) ### Checking Usage Use `GET /v2/usage` to check your current credit usage: ```json { "credits_used": 847293, "credit_limit": 1000000 } ``` ### Exceeding Limits When you exceed your credit limit, the API returns HTTP 402: ```json { "detail": { "error": "Monthly credit limit exceeded.", "limit": 1000000 } } ``` Credits are calculated on a rolling 30-day window. Usage older than 30 days automatically falls off. version: 2.0.0 servers: - url: https://api.shovels.ai/v2 description: Shovels API security: [] 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. paths: /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 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' security: - APIKeyHeader: [] components: schemas: 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. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError 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 × 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 × 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 × 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. TotalCount: properties: value: type: integer minimum: 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". 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 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. 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. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ````