openapi: 3.0.0 info: title: Home Depot Reviews API description: | The Home Depot Reviews API returns customer reviews for a Home Depot product, along with the product's rating summary and pagination. By default Home Depot includes reviews written for the product's other versions, such as a kit and the tool-only item. Each review's `product` names the version it was written for, and `is_family_excluded=true` returns only reviews of the product itself. The `product` summary is left out when `rating`, `is_verified_purchase` or `q` narrows the reviews, because Home Depot's summary then covers only the matching reviews. Home Depot only returns pages that start within its first 501 reviews, so the last page is 17 at 30 reviews per page and 6 at 100. version: 1.0.0 servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: Home Depot Reviews Search security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true description: Engine to use for the search schema: type: string enum: ["home_depot_reviews"] default: "home_depot_reviews" - name: product_id in: query required: true description: Home Depot product ID, the 9-digit number at the end of a product page URL, such as 320326875 schema: type: string pattern: '^\d{9}$' - name: sort_by in: query required: false description: Sort order for the returned reviews. photo_reviews lists reviews with photos first, as homedepot.com does. schema: type: string enum: ["photo_reviews", "most_helpful", "newest", "oldest", "highest_rating", "lowest_rating"] default: "photo_reviews" - name: rating in: query required: false description: Star ratings to return, comma-separated for several, such as 1,2. The response then has no product summary. schema: type: string pattern: '^[1-5](,[1-5])*$' - name: is_verified_purchase in: query required: false description: Set to true to return only reviews from verified purchases. The response then has no product summary. schema: type: boolean - name: is_family_excluded in: query required: false description: Set to true to return only reviews written for this product, without its other versions schema: type: boolean - name: q in: query required: false description: Text to search for in the reviews, up to 128 characters, where an emoji counts as two. Cannot contain `&` or `+`, and must contain a letter or a digit. The response then has no product summary. schema: type: string maxLength: 128 - name: page in: query required: false description: Page number. Home Depot only returns pages that start within its first 501 reviews. schema: type: integer minimum: 1 default: 1 - name: num in: query required: false description: Number of reviews per page schema: type: integer minimum: 1 maximum: 100 default: 30 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication Error. The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server Error. Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Timeout. We could not retrieve results in 90 seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"' ApiKeyQuery: type: apiKey in: query name: api_key description: Pass API key as query parameter schemas: SearchResponse: type: object required: [search_metadata, search_parameters] properties: search_metadata: $ref: '#/components/schemas/SearchMetadata' search_parameters: $ref: '#/components/schemas/SearchParameters' search_information: $ref: '#/components/schemas/SearchInformation' product: $ref: '#/components/schemas/Product' reviews: type: array description: The reviews on the current page items: $ref: '#/components/schemas/Review' pagination: $ref: '#/components/schemas/Pagination' error: type: string description: Error message when no reviews are found, or when Home Depot refuses the text in q SearchMetadata: type: object required: [status, created_at] properties: id: type: string description: Unique identifier for the search request status: type: string description: Status of the search request created_at: type: string format: date-time description: Timestamp when the search was created request_time_taken: type: number description: Time taken to make the request in seconds parsing_time_taken: type: number description: Time taken to parse the results in seconds total_time_taken: type: number description: Total time taken for the search in seconds request_url: type: string description: Home Depot reviews page URL for this search html_url: type: string description: URL to view HTML results json_url: type: string description: URL to view JSON results SearchParameters: type: object properties: engine: type: string description: Engine used for the search product_id: type: string description: Home Depot product ID searched for sort_by: type: string description: Sort order applied rating: type: string description: Star rating filter applied is_verified_purchase: type: string description: Verified purchase filter applied is_family_excluded: type: string description: Product version filter applied q: type: string description: Review text search applied page: type: string description: Page number requested num: type: string description: Number of reviews per page requested SearchInformation: type: object required: [total_results] properties: total_results: type: integer description: Number of reviews matching the search Product: type: object description: Rating summary of the product's reviews required: [product_id, rating, reviews_histogram] properties: product_id: type: string description: Home Depot product ID rating: type: number description: Average star rating reviews: type: integer description: Number of reviews reviews_histogram: $ref: '#/components/schemas/ReviewsHistogram' recommended_percentage: type: integer description: Percentage of reviewers who answered the recommend question and recommend the product ReviewsHistogram: type: object description: Number of reviews per star rating required: ['1', '2', '3', '4', '5'] properties: '1': type: integer description: Number of 1-star reviews '2': type: integer description: Number of 2-star reviews '3': type: integer description: Number of 3-star reviews '4': type: integer description: Number of 4-star reviews '5': type: integer description: Number of 5-star reviews Review: type: object required: [position, id, rating, user, product] properties: position: type: integer description: Position of the review across all pages of the search id: type: string description: Review identifier title: type: string description: Review title text: type: string description: Review text rating: type: integer description: Star rating given in the review iso_date: type: string format: date-time description: Date and time the review was submitted, in ISO 8601 format user: $ref: '#/components/schemas/User' is_verified_purchase: type: boolean description: Whether the reviewer bought the product is_recommended: type: boolean description: Whether the reviewer recommends the product badges: type: array description: Badge codes shown on the review, such as verifiedPurchaser or earlyReviewerIncentive items: type: string positive_feedback: type: integer description: Number of readers who found the review helpful negative_feedback: type: integer description: Number of readers who did not find the review helpful images: type: array description: Photos attached to the review items: $ref: '#/components/schemas/Image' secondary_ratings: type: array description: Ratings the reviewer gave for specific qualities, such as Quality or Value items: $ref: '#/components/schemas/SecondaryRating' response: $ref: '#/components/schemas/Response' source: type: string description: Website the review was first published on, such as dewalt.com product: $ref: '#/components/schemas/ReviewedProduct' User: type: object required: [name] properties: id: type: string description: Reviewer identifier name: type: string description: Reviewer nickname location: type: string description: Location the reviewer entered Image: type: object required: [link] properties: link: type: string description: Full-size photo URL thumbnail: type: string description: Thumbnail photo URL SecondaryRating: type: object required: [name, rating] properties: name: type: string description: Quality being rated rating: type: integer description: Star rating for that quality Response: type: object description: Reply to the review from the brand or Home Depot required: [text] properties: text: type: string description: Reply text iso_date: type: string format: date-time description: Date and time of the reply, in ISO 8601 format user: type: object description: Team that wrote the reply properties: name: type: string description: Name of the team that wrote the reply ReviewedProduct: type: object description: Product version the review was written for required: [product_id] properties: product_id: type: string description: Home Depot product ID of the version title: type: string description: Product name shown when the review was written Pagination: type: object required: [current, total_pages] properties: current: type: integer description: Current page number next: type: string description: Home Depot reviews page URL for the next page total_pages: type: integer description: Number of pages this search can return ErrorResponse: type: object required: [error] properties: error: type: string description: Error message