Core APIs
...
Results
Core Requests

Category

2min

Category Results

When making a request with the type parameter set to type=category BigBox API will return category results from Home Depot.

Category results are retrieved from the category results page on Home Depot.

Category Results Page
Category Results Page


An example of the JSON object returned from a Category request is shown below:

JSON


BigBox API returns the following properties for Category requests:

Property

Type

Description

category_results

array

An array of Category Result objects, containing each of the product results shown on the Category Results page. The Category Result object has the following properties:

  • position
  • number
  • The position of the result on the category results page.



Product Object The product object contains details about the product within the category result. The product object has the following properties:

  • title
  • string
  • The product title.



  • link
  • string
  • The URL to the product page.



  • brand
  • string
  • The brand name of the product, if shown.



  • item_id
  • string
  • The product item id. Pass the item_id into a type=product request to get product-level data about the product.



  • store_sku
  • string
  • The product store SKU ID.



  • model_number
  • string
  • The model number of the product, if shown.



  • is_bestseller
  • boolean
  • Set to true if the product is flagged as a Bestseller.



  • is_top_rated
  • boolean
  • Set to true if the product is flagged as a Top Rated product.



  • is_exclusive
  • boolean
  • Set to true if the product is flagged as an Exclusive product.



  • primary_image
  • string
  • The primary image URL associated with the product.



  • images
  • array
  • An array of image URLs for the product.



  • sponsored
  • boolean
  • Set to true when the search result is sponsored.



  • rating
  • number
  • The customer rating of this product, out of 5.



  • ratings_total
  • number
  • The total number of customer ratings this product has received.



  • favorite_count
  • number
  • The number of favorite ratings this product has received.



  • features
  • array
  • An array of objects contain objects with a name value pairs representing the product features.



  • collection
  • object
  • Present if the product is part of a collection. Contains id , name and link properties.



Offers Object The offers object contains details about the product offers. The offers object has the following properties:

  • primary
  • object
  • Primary Offer Object The primary offer object contains details about the primary offer for the product and has the following properties:
    • 
      1. price
      2. number
      3. The price of the primary offer.
    • 
      1. regular_price
      2. number
      3. The regular, non-discounted, price of the primary offer.
    • 
      1. currency
      2. string
      3. The currency of the primary offer, i.e. USD .
    • 
      1. symbol
      2. string
      3. The currency synbol of the primary offer.



Fulfillment Object The fulfillment object contains details about the product delivery and pickup options. The fulfillment object has the following properties:

  • pickup
  • boolean
  • Set to true if the pickup-from-store fulfillment channel is available ( pickup_info will be present with further details), false otherwise.



  • pickup_info
  • object
  • Populated when pickup=true . Contains a in_stock boolean set to true when the product is in stock in store for pickup, stock_level indicating the quantity available for pickup and further properties detailing the store address.



  • ship_to_home
  • boolean
  • Set to true if the ship-to-home fulfillment channel is available ( ship_to_home_info will be present with further details), false otherwise.



  • ship_to_home_info
  • object
  • Populated when ship_to_home=true . Contains a in_stock boolean set to true when the product is available for ship to home and stock_level indicating the quantity available for ship to home.



  • scheduled_delivery
  • boolean
  • Set to true if the scheduled-delivery fulfillment channel is available ( scheduled_delivery_info will be present with further details), false otherwise.



  • scheduled_delivery_info
  • object
  • Populated when scheduled_delivery=true . Contains a in_stock boolean set to true when the product is available for scheduled delivery and stock_level indicating the quantity available for schedule delivery.



  • ship_to_store
  • boolean
  • Set to true if the ship-to-store fulfillment channel is available ( ship_to_store_info will be present with further details), false otherwise.



  • ship_to_store_info
  • object
  • Populated when ship_to_store=true . Contains a in_stock boolean set to true when the product is available for ship-to-store and stock_level indicating the quantity available for ship-to-store and further properties detailing the store address.

facets

array

Facet Object An array containing details of any available search facets (refinements) shown on the category result page. You can use the facets returned here to refine your query by supplying link from a given facet value to the url request parameter (remember to URL-encode the link before passing it to the url request parameter). Each object in the facets array contains the following properties:

  • name
  • string
  • The name of the facet (can be used in the facets request parameter).



  • display_name
  • string
  • The display name of the facet (i.e. the user-facing name).



  • values
  • array
  • Facet Values Array The facet values array shows the values of the given facet, along with the number of products matching that facet value.
    • 
      1. value
      2. string
      3. The value of the facet (can be used in the facets request parameter).
    • 
      1. display_name
      2. string
      3. The display name of the facet value (i.e. the user-facing name of the facet value).
    • 
      1. count
      2. number
      3. The count of the number of products that match this facet value in the current search results.
    • 
      1. active
      2. boolean
      3. Set to true when this facet value is currently active in the current set of results. The URL to use to request results filtered to this facet.
    • 
      1. link
      2. string
      3. Note You can use the link to the url request parameter (remember to URL-encode the link before passing it to the url request parameter).

category_list

array

An array of Category List objects. This property is populated when an "intermediate" category URL is specified in the requests' url parameter (see example). "Intermediate" category URLs are category landing pages that typically show a branded list of sub-categories. Note that the categories returned in category_list are retrieved from the category listing page itself, rather than via the Categories API. The Category List object has the following properties:

  • title
  • string
  • The title of the sub-category linked-to from the intermediate category page.



  • link
  • string
  • link to the sub-category from the intermediate category page. Could we passed to a subsequent type=category request via the url request parameter to retrieve category listings from that page.

category_information

object

An object containing details of the current page of category results.

  • is_landing_page
  • boolean
  • Set to true when the current page is a category landing page (see example). A category landing page is a higher level summary page. If you encounter one you should iterate to a lower level category, or use the facets request parameter, to traverse down to a category listing page.



  • title
  • string
  • The title of the category page, if shown.

pagination

object

Pagination Object An object containing details of the current results page and the total number of pages that are available. To paginate you should specify the page number in your request's page parameter.

  • current
  • object
  • Current Page Object Contains details of the current page
    • 
      1. page
      2. number
      3. The current page number.
    • 
      1. link
      2. string
      3. The current page URL.



  • next
  • object
  • Next Page Object Contains details of the next page
    • 
      1. page
      2. number
      3. The next page number.
    • 
      1. link
      2. string
      3. The next page URL.



  • total_pages
  • number
  • The total number of pages shown as being available.



  • total_results
  • number
  • The total number of search results shown as being available.

location_info

object

Location Info Object An object containing details of the location in which the request was run. You can control the store used using the customer_zipcode request parameter.

  • store_id
  • string
  • The ID of the store the request was run.



  • store_name
  • string
  • The name of the store the request was run.



  • zipcode
  • string
  • The zipcode of the store the request was run.


Next Steps      Category Parameters

Updated 05 Aug 2024
Did this page help you?