Leverage customer behavior data to surface relevant products through trending products, most viewed, also viewed, also bought, and viewed-ultimately-bought recommendation types. Supports queries by category ID or specific SKU.
openapi: 3.0.3
info:
title: Best Buy Recommendations API
description: >-
Leverage customer behavior data to surface relevant products through trending
products, most viewed, also viewed, also bought, and viewed-ultimately-bought
recommendation types. Supports queries by category ID or specific SKU.
version: 1.0.0
contact:
url: https://developer.bestbuy.com
x-generated-from: documentation
servers:
- url: https://api.bestbuy.com/v1
description: Best Buy API v1
security:
- apiKey: []
tags:
- name: Recommendations
description: Customer behavior-based product recommendations
paths:
/products/trendingViewed:
get:
operationId: getTrendingProducts
summary: Best Buy Get Trending Products
description: >-
Returns the top 10 products with the highest view velocity over a rolling
3-hour window. Requires a minimum of 50 page views per hour to qualify.
tags:
- Recommendations
parameters:
- name: apiKey
in: query
required: true
description: Your Best Buy developer API key.
schema:
type: string
example: YourAPIKey
- name: categoryId
in: query
required: false
description: Filter trending products to a specific category.
schema:
type: string
example: abcat0500000
- name: format
in: query
required: false
description: Response format - json only for recommendations.
schema:
type: string
default: json
example: json
responses:
'200':
description: Successful response with trending products.
content:
application/json:
schema:
$ref: '#/components/schemas/RecommendationsResponse'
examples:
GetTrendingProducts200Example:
summary: Default getTrendingProducts 200 response
x-microcks-default: true
value:
metadata:
resultSet:
count: 10
results:
- sku: 1234567
names:
title: Sample Laptop 15" 16GB RAM
images:
standard: https://pisces.bbystatic.com/image2/BestBuy_US/images/products/1234/1234567_sd.jpg
prices:
regular: 999.99
current: 849.99
links:
product: https://api.bestbuy.com/v1/products/1234567.json
web: https://www.bestbuy.com/site/sample-laptop/1234567.p
addToCart: https://www.bestbuy.com/cart/api/v1/addToCart
rank: 1
'401':
description: Unauthorized - missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/products/mostViewed:
get:
operationId: getMostViewedProducts
summary: Best Buy Get Most Viewed Products
description: >-
Returns the top 10 most frequently viewed products. Data is refreshed every
2 hours using a 48-hour accumulation window.
tags:
- Recommendations
parameters:
- name: apiKey
in: query
required: true
description: Your Best Buy developer API key.
schema:
type: string
example: YourAPIKey
- name: categoryId
in: query
required: false
description: Filter most viewed products to a specific category.
schema:
type: string
example: abcat0500000
- name: format
in: query
required: false
description: Response format - json only.
schema:
type: string
default: json
example: json
responses:
'200':
description: Successful response with most viewed products.
content:
application/json:
schema:
$ref: '#/components/schemas/RecommendationsResponse'
examples:
GetMostViewedProducts200Example:
summary: Default getMostViewedProducts 200 response
x-microcks-default: true
value:
metadata:
resultSet:
count: 10
results:
- sku: 2345678
names:
title: Sample Smartphone 128GB
images:
standard: https://pisces.bbystatic.com/image2/BestBuy_US/images/products/2345/2345678_sd.jpg
prices:
regular: 799.99
current: 699.99
links:
product: https://api.bestbuy.com/v1/products/2345678.json
web: https://www.bestbuy.com/site/sample-smartphone/2345678.p
addToCart: https://www.bestbuy.com/cart/api/v1/addToCart
rank: 1
'401':
description: Unauthorized - missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/products/{sku}/alsoViewed:
get:
operationId: getAlsoViewedProducts
summary: Best Buy Get Also Viewed Products
description: >-
Returns products browsed alongside a specific SKU, based on a 30-day
behavioral window of co-viewing patterns.
tags:
- Recommendations
parameters:
- name: sku
in: path
required: true
description: The SKU number to get also-viewed recommendations for.
schema:
type: integer
example: 1234567
- name: apiKey
in: query
required: true
description: Your Best Buy developer API key.
schema:
type: string
example: YourAPIKey
- name: format
in: query
required: false
description: Response format - json only.
schema:
type: string
default: json
example: json
responses:
'200':
description: Successful response with also-viewed products.
content:
application/json:
schema:
$ref: '#/components/schemas/RecommendationsResponse'
examples:
GetAlsoViewedProducts200Example:
summary: Default getAlsoViewedProducts 200 response
x-microcks-default: true
value:
metadata:
resultSet:
count: 5
results:
- sku: 3456789
names:
title: Sample Laptop Bag 15"
prices:
regular: 49.99
current: 39.99
rank: 1
'404':
description: No recommendations found for the given SKU.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized - missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/products/{sku}/alsoBought:
get:
operationId: getAlsoBoughtProducts
summary: Best Buy Get Also Bought Products
description: >-
Returns products purchased together with a specific SKU, based on a 30-day
purchase history window.
tags:
- Recommendations
parameters:
- name: sku
in: path
required: true
description: The SKU number to get also-bought recommendations for.
schema:
type: integer
example: 1234567
- name: apiKey
in: query
required: true
description: Your Best Buy developer API key.
schema:
type: string
example: YourAPIKey
- name: format
in: query
required: false
description: Response format - json only.
schema:
type: string
default: json
example: json
responses:
'200':
description: Successful response with also-bought products.
content:
application/json:
schema:
$ref: '#/components/schemas/RecommendationsResponse'
examples:
GetAlsoBoughtProducts200Example:
summary: Default getAlsoBoughtProducts 200 response
x-microcks-default: true
value:
metadata:
resultSet:
count: 5
results:
- sku: 4567890
names:
title: Sample Laptop Charger
prices:
regular: 79.99
current: 59.99
rank: 1
'404':
description: No recommendations found for the given SKU.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized - missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
apiKey:
type: apiKey
in: query
name: apiKey
description: API key obtained by registering at developer.bestbuy.com.
schemas:
RecommendationsResponse:
title: RecommendationsResponse
type: object
description: Response containing recommended product list.
properties:
metadata:
type: object
description: Metadata about the result set.
properties:
resultSet:
type: object
properties:
count:
type: integer
description: Number of results returned.
example: 10
results:
type: array
description: Array of recommended product objects.
items:
$ref: '#/components/schemas/RecommendedProduct'
RecommendedProduct:
title: RecommendedProduct
type: object
description: A recommended product with essential display attributes.
properties:
sku:
type: integer
description: Product SKU number.
example: 1234567
names:
type: object
description: Product name variations.
properties:
title:
type: string
description: Product display title.
example: Sample Laptop 15" 16GB RAM
images:
type: object
description: Product image URLs.
properties:
standard:
type: string
description: Standard product image URL.
example: https://pisces.bbystatic.com/image2/BestBuy_US/images/products/1234/1234567_sd.jpg
prices:
type: object
description: Product pricing information.
properties:
regular:
type: number
format: double
description: Regular price in USD.
example: 999.99
current:
type: number
format: double
description: Current (sale) price in USD.
example: 849.99
links:
type: object
description: Related URLs for the product.
properties:
product:
type: string
description: API URL for full product data.
example: https://api.bestbuy.com/v1/products/1234567.json
web:
type: string
description: URL of the product page on bestbuy.com.
example: https://www.bestbuy.com/site/sample-laptop/1234567.p
addToCart:
type: string
description: URL for adding to cart.
example: https://www.bestbuy.com/cart/api/v1/addToCart
rank:
type: integer
description: Rank position in the recommendation list.
example: 1
ErrorResponse:
title: ErrorResponse
type: object
description: Error response returned when a request fails.
properties:
status:
type: integer
description: HTTP status code.
example: 400
error:
type: string
description: Error type or code.
example: Bad Request
message:
type: string
description: Human-readable description of the error.
example: Invalid query parameter provided.