openapi: 3.0.0
info:
  title: Home Depot Product API
  description: |
    The Home Depot Product API returns the details of one Home Depot product by its product ID. The response includes the title, brand, model number, price, rating, images, videos, specifications, categories, and the pickup and delivery options.

    The `store_id` parameter selects the Home Depot store for the price, pickup and stock. The `postal_code` parameter sets the ZIP code for delivery options.

    A product ID or store ID that Home Depot does not have or does not accept returns an `error` message in place of `product`.

    **Cross-linking**: The `product_id` parameter accepts a Home Depot product ID. It is the number at the end of a Home Depot product URL. For example, in `https://www.homedepot.com/p/Milwaukee-M18-FUEL-18V-Lithium-Ion-Brushless-Cordless-1-4-in-Hex-Impact-Driver-Tool-Only-2953-20/320326875` the product ID is `320326875`.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Home Depot Product Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Engine to use for the search
          schema:
            type: string
            enum: ["home_depot_product"]
            default: "home_depot_product"
        - name: product_id
          in: query
          required: true
          description: Home Depot product ID of the product to retrieve. It has 9 digits, such as `320326875`.
          schema:
            type: string
            pattern: '^0*[1-9]\d{8}$'
        - name: store_id
          in: query
          required: false
          description: Home Depot store ID, the store number of 3 or 4 digits, such as `1710`. The price, pickup and stock in the response are for this store. Without it, the pickup and stock are those of Home Depot's default store, `121`, and in-store-only products and some lumber come back with no price.
          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`. It does not change the pickup store or the price.
          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'
        product:
          $ref: '#/components/schemas/Product'
        error:
          type: string
          description: Error message for a product ID or store ID that Home Depot does not have 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 for this product
        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
        store_id:
          type: string
          description: Home Depot store ID used for the price, pickup and stock
        postal_code:
          type: string
          description: ZIP code used for delivery options
    Product:
      type: object
      required: [product_id]
      properties:
        product_id:
          type: string
          description: Home Depot product ID
        parent_product_id:
          type: string
          description: Home Depot's parent ID for this product, which does not work as a `product_id`.
        title:
          type: string
          description: Product title
        link:
          type: string
          description: URL of the product page on Home Depot
        brand:
          type: string
          description: Product brand
        brand_link:
          type: string
          description: URL of the brand page on Home Depot
        model_number:
          type: string
          description: Manufacturer model number
        sku:
          type: string
          description: Home Depot store SKU number
        upc:
          type: string
          description: Universal Product Code
        rating:
          type: number
          description: Average customer rating
        reviews:
          type: integer
          description: Total number of customer reviews
        favorite_count:
          type: integer
          description: Number of customers who saved the product as a favorite
        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
        badges:
          type: array
          items:
            type: string
          description: Product badge labels
        main_image:
          type: string
          description: URL of the main product image
        images:
          type: array
          items:
            $ref: '#/components/schemas/ProductImage'
          description: Product images
        videos:
          type: array
          items:
            $ref: '#/components/schemas/Video'
          description: Product videos
        collection:
          $ref: '#/components/schemas/Collection'
        availability_type:
          type: string
          description: Home Depot's availability type for the product, such as `Shared`, `Online` or `Store Only`
        is_buyable:
          type: boolean
          description: Whether the product can be bought at Home Depot
        is_discontinued:
          type: boolean
          description: Whether Home Depot has discontinued the product
        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
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
          description: Category path of the product, from the broadest category to the narrowest
        description:
          type: string
          description: Product description
        highlights:
          type: array
          items:
            type: string
          description: Product highlights
        specifications:
          type: array
          items:
            $ref: '#/components/schemas/SpecificationGroup'
          description: Product specifications grouped by section
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
          description: Key features of the product
    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
    Video:
      type: object
      required: [link]
      properties:
        title:
          type: string
          description: Video title
        link:
          type: string
          description: URL of the video file
        thumbnail:
          type: string
          description: URL of the video thumbnail image
        iso_date:
          type: string
          format: date-time
          description: Upload date of the video in ISO 8601 format
    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
      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
        start_date:
          type: string
          format: date
          description: Earliest estimated pickup date in YYYY-MM-DD format
        end_date:
          type: string
          format: date
          description: Latest estimated pickup date in YYYY-MM-DD format
        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
      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
    SpecificationGroup:
      type: object
      required: [specifications]
      properties:
        title:
          type: string
          description: Specification group title, such as `Details`
        specifications:
          type: array
          items:
            $ref: '#/components/schemas/Specification'
          description: Individual specifications in this group
    Specification:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Specification name, such as `Battery Amp Hours`
        value:
          type: string
          description: Specification value, such as `No Battery`
    Attribute:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Feature name
        value:
          type: string
          description: Feature value
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
