openapi: 3.0.0 info: title: Home Depot Search API description: | The Home Depot Search API returns the products Home Depot shows for a keyword or a category. Each result includes the product ID, title, brand, model number, price, rating, images and the pickup and delivery options. The response also includes the filters, categories, related searches and pages of the results. Home Depot shows a category page for some keywords, such as `garden hose`. The response then lists the products of that category, and `search_information.category_id` holds its ID. The `store_id` parameter selects the Home Depot store for the pickup store and its stock. The `postal_code` parameter sets the ZIP code for delivery options. A search Home Depot answers with no products, or a keyword, category or store it does not accept, returns an `error` message in place of the results. **Cross-linking**: The `category_id` parameter accepts the `category_id` of an entry in `categories`, of a Category option in `filters`, or of `search_information`. The `filters` parameter accepts the `filter_value` of the other options in `filters`. version: 1.0.0 servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: Home Depot Search security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true description: Engine to use for the search schema: type: string enum: ["home_depot_search"] default: "home_depot_search" - name: q in: query required: false description: Search query, such as `paint roller`. Either `q` or `category_id` is required. Home Depot refuses keywords with `À`, `Á`, `Ã`, `Ä`, `Å`, `Ø`, `Ü`, `à`, `á`, `ã`, `ä`, `å`, `ø`, `ü`, `¡` or `¼`. schema: type: string maxLength: 150 pattern: '^[^ÀÁÃÄÅØÜàáãäåøü¡¼]*$' - name: category_id in: query required: false description: Home Depot category ID, such as `5yc1vZbm79` for LED Light Bulbs. Alone it browses the category, and with `q` it searches inside it. schema: type: string pattern: '^5yc1v(Z[0-9a-z]{1,12}){1,20}$' - name: filters in: query required: false description: Comma-separated `filter_value` tokens from `filters`, such as `zv,qy9`, up to 20. Two values of one filter return products that match either. schema: type: string - name: sort_by in: query required: false description: Sort order of the results. Defaults to `best_match` with `q` and to `best_selling` with `category_id` alone. schema: type: string enum: [best_match, best_selling, most_popular, customer_rating, price_low_to_high, price_high_to_low, new_arrivals] - name: price_min in: query required: false description: Minimum price in US dollars. Home Depot filters prices in whole dollars, so the value is rounded down. schema: type: number minimum: 0 maximum: 2147483647 - name: price_max in: query required: false description: Maximum price in US dollars. Home Depot filters prices in whole dollars, so the value is rounded up. schema: type: number minimum: 0 maximum: 2147483647 - name: page in: query required: false description: Results page number. Each page holds 24 products, plus sponsored products on some pages. schema: type: integer minimum: 1 maximum: 31 default: 1 - name: store_id in: query required: false description: Home Depot store ID, the store number of 3 or 4 digits, such as `121`. The pickup store and its stock in the results are for this store. Without it, results have no pickup details. schema: type: string pattern: '^0*[1-9]\d{2,3}$' - name: postal_code in: query required: false description: 5-digit US ZIP code used for delivery options, such as `30339`. schema: type: string pattern: '^\d{5}$' 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 properties: search_metadata: $ref: '#/components/schemas/SearchMetadata' search_parameters: $ref: '#/components/schemas/SearchParameters' search_information: $ref: '#/components/schemas/SearchInformation' organic_results: type: array items: $ref: '#/components/schemas/OrganicResult' description: Products on the results page, in the order Home Depot shows them filters: type: array items: $ref: '#/components/schemas/Filter' description: Filters Home Depot offers for the results categories: type: array items: $ref: '#/components/schemas/Category' description: Category path of the results, from the broadest category to the narrowest related_searches: type: array items: $ref: '#/components/schemas/RelatedSearch' description: Searches Home Depot suggests as related pagination: $ref: '#/components/schemas/Pagination' error: type: string description: Error message for a search Home Depot answers with no products or does not accept 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 URL of the results page 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 q: type: string description: Search query category_id: type: string description: Home Depot category ID searched in filters: type: string description: Filter tokens applied sort_by: type: string description: Sort order applied price_min: type: string description: Minimum price applied price_max: type: string description: Maximum price applied page: type: string description: Results page number store_id: type: string description: Home Depot store ID used for the pickup store and its stock postal_code: type: string description: ZIP code used for delivery options SearchInformation: type: object properties: total_results: type: integer description: Home Depot's estimate of the number of products for the search query_displayed: type: string description: Search query as Home Depot shows it showing_results_for: type: string description: Query Home Depot searched instead, such as a corrected spelling category_id: type: string description: ID of the category page Home Depot showed for the keyword store_id: type: string description: Home Depot store ID the results are for store_name: type: string description: Name of the Home Depot store the results are for OrganicResult: type: object required: [position, product_id] properties: position: type: integer description: Position of the product on the page product_id: type: string description: Home Depot product ID parent_product_id: type: string description: Home Depot ID of the parent product title: type: string description: Product title link: type: string description: URL of the product page on Home Depot brand: type: string description: Product brand model_number: type: string description: Manufacturer model number sku: type: string description: Home Depot store SKU number rating: type: number description: Average customer rating reviews: type: integer description: Total number of customer reviews price: type: string description: Current price as displayed extracted_price: type: number description: Current price as a numeric value original_price: type: string description: Original price before discount extracted_original_price: type: number description: Original price as a numeric value unit_price: type: string description: Price per unit with the unit it is measured in extracted_unit_price: type: number description: Price per unit as a numeric value unit_of_measure: type: string description: Unit the price applies to, such as `each` bulk_savings: type: array items: $ref: '#/components/schemas/BulkSaving' description: Lower prices per unit for buying in quantity clearance_price: type: string description: Clearance price as displayed extracted_clearance_price: type: number description: Clearance price as a numeric value is_starting_price: type: boolean description: Whether Home Depot shows the price as a starting price is_price_hidden: type: boolean description: Whether Home Depot shows the price only in the cart is_sponsored: type: boolean description: Whether the product is a sponsored placement badges: type: array items: type: string description: Product badge labels thumbnail: type: string description: URL of the main product image images: type: array items: $ref: '#/components/schemas/ProductImage' description: Product images variants: type: array items: $ref: '#/components/schemas/Variant' description: Other colors or styles of the product collection: $ref: '#/components/schemas/Collection' fulfillment: $ref: '#/components/schemas/Fulfillment' return_policy: type: string description: Return policy of the product, such as `90-Day` max_quantity: type: integer description: Maximum quantity Home Depot allows in one purchase Variant: type: object required: [product_id] properties: product_id: type: string description: Home Depot product ID of the variant title: type: string description: Variant name, such as a color link: type: string description: URL of the variant's product page on Home Depot swatch_thumbnail: type: string description: URL of the variant's swatch image Filter: type: object required: [options] properties: type: type: string description: Filter name, such as `Brand` options: type: array items: $ref: '#/components/schemas/FilterOption' description: Values of the filter FilterOption: type: object properties: text: type: string description: Option name items: type: integer description: Number of products Home Depot reports for the option filter_value: type: string description: Token to pass in the `filters` parameter category_id: type: string description: Category ID to pass in the `category_id` parameter link: type: string description: URL of the filtered results on Home Depot is_selected: type: boolean description: Whether the option is applied to the search RelatedSearch: type: object required: [query, link] properties: query: type: string description: Related search query link: type: string description: URL of the related search on Home Depot Pagination: type: object required: [current] properties: current: type: integer description: Current page number previous: type: string description: URL of the previous page on Home Depot next: type: string description: URL of the next page on Home Depot other_pages: type: object additionalProperties: type: string description: Page numbers mapped to their URLs on Home Depot BulkSaving: type: object properties: extracted_quantity: type: integer description: Minimum quantity for the bulk price extracted_price: type: number description: Bulk price per unit as a numeric value ProductImage: type: object required: [link] properties: link: type: string description: URL of the image Collection: type: object description: Home Depot collection the product belongs to properties: title: type: string description: Collection name link: type: string description: URL of the collection page on Home Depot Fulfillment: type: object description: Pickup and delivery options for the product properties: pickup: $ref: '#/components/schemas/Pickup' delivery: $ref: '#/components/schemas/Delivery' express_delivery: $ref: '#/components/schemas/ExpressDelivery' Pickup: type: object description: Pickup at a Home Depot store required: [store_id] properties: store_id: type: string description: Home Depot store ID of the pickup store store_name: type: string description: Name of the pickup store stock: type: integer description: Quantity in stock at the pickup store is_ship_to_store: type: boolean description: Whether Home Depot ships the product to the store for pickup Delivery: type: object description: Shipping to the customer properties: start_date: type: string format: date description: Earliest estimated delivery date in YYYY-MM-DD format end_date: type: string format: date description: Latest estimated delivery date in YYYY-MM-DD format price: type: number description: Shipping charge in US dollars is_free_shipping: type: boolean description: Whether Home Depot ships the product for free stock: type: integer description: Quantity in stock for shipping ExpressDelivery: type: object description: Express delivery from a Home Depot store properties: store_id: type: string description: Home Depot store ID of the store that delivers the product start_date: type: string format: date description: Earliest estimated delivery date in YYYY-MM-DD format end_date: type: string format: date description: Latest estimated delivery date in YYYY-MM-DD format price: type: number description: Express delivery charge in US dollars Category: type: object required: [category_id, link] properties: title: type: string description: Category name category_id: type: string description: Home Depot category ID link: type: string description: URL of the category page on Home Depot ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong