NAV
shell javascript

Overview

Welcome to the Best Buy Developer API site! Whether you’re an API pro, a beginning developer or a Best Buy partner, our extensive API catalog is waiting for your imagination. Our API suite allows you to query Products, Stores and much more. Come on in to explore our data, browse descriptions of the available attributes and see examples of working requests and responses.

If this is your first time using our APIs, please check out our Getting Started guide. If you already have your API key, our Search and Response Formats can help you refine your results.

NOTE: Effective in early 2017, JSONP will be disabled in the interest of protecting user privacy. This will prevent developers making API calls from the client side and thus exposing API keys to the general public. If you have any questions or ideas on this issue, please contact us at developer@bestbuy.com.

Response Format

Responses can be returned in either JSON or XML.

Applies to: Products API • Stores API • Categories API

To request a single item, such as a specific product, indicate the desired response format with the extension added after the item’s identifier. For example, /products/8880044.json.

To request a collection of items, such as all the products in our catalog, the desired response format is specified in the format query parameter. An example of this can be seen in the Retrieving Collections section. If no format is specified then xml will be returned.

Applies to: Recommendations API

When using any of the endpoints in the Recommendations API the response format returned will be json. The XML format is not supported for the Recommendations API endpoints. You can specify the format using /6534009/alsoViewed.json or not specify a format like /6534009/alsoViewed.

Applies to: Products API

By agreeing to Best Buy’s terms of service, you also agree not to cache any content except on a temporary basis. As such, our response links will expire after seven days. Here are several examples of appropriately formatted response URLs:

url: https://api.bestbuy.com/click/5592e2b895800000/12345678/pdp

mobileUrl: https://api.bestbuy.com/click/5592e2b895800000/12345678/pdp

addToCartUrl: https://api.bestbuy.com/click/5592e2b895800000/12345678/cart

Returned Attributes

curl "https://api.bestbuy.com/v1/products/8880044.json?show=sku,name,salePrice&apiKey=YourAPIKey"
var bby = require('bestbuy')('YourAPIKey');
bby.products(8880044,{show:'sku,name,salePrice'}).then(function(data){
  console.log(data);
});

Only returns the sku, name and salePrice attributes for products.

{
  "sku": 8880044,
  "name": "Batman Begins (Blu-ray Disc)",
  "salePrice": 7.99
}

Applies to: Products API • Stores API • Categories API

The show attribute allows you to control which attributes are returned. You can return specific attributes by following the syntax below. To return all attributes, use show=all.

If you tried the example query in the Getting Started section, you probably noticed that our Products API returns a lot of attributes for each product. For convenience, we provide a show query parameter that allows you to specify just the attributes that you want returned in the response.

Show All

Applies to: Products API • Stores API

In order to make the API responses more manageable, we don’t return all available attributes for those items that contain many (e.g. Products and Stores). In the event that you want to get all of these hidden attributes, you can set show=all in the query parameters for the API

For example, the Stores API does not return the detailedHours attribute by default. By setting show=all you will receive detailedHours in the response.

Sort

curl 'https://api.bestbuy.com/v1/products(categoryPath.name="All%20Flat-Panel%20TVs")?format=json&show=sku,name,salePrice&sort=salesRankMediumTerm.asc&apiKey=YourAPIKey'
var bby = require('bestbuy')('YourAPIKey');
bby.products('categoryPath.name="All Flat-Panel TVs"',{show:'sku,name,salePrice',sort:'salesRankMediumTerm.asc'}).then(function(data){
  console.log(data);
});

Lists all flat-panel TVs with prices and sorts by the best-selling products over the last week.

{
  "from": 1,
  "to": 10,
  "total": 307,
  "currentPage": 1,
  "totalPages": 31,
  "queryTime": "0.005",
  "totalTime": "0.035",
  "partial": false,
  "canonicalUrl": "/v1/products(categoryPath.name=All Flat-Panel TVs)?show=sku,name,salePrice&sort=salesRankMediumTerm&format=json&apiKey=YourAPIKey",
  "products": [
    {
      "sku": 3356036,
      "name": "Insignia™ - 32\" Class (31-1/2\" Diag.) - LED - 720p - 60Hz - HDTV",
      "salePrice": 179.99
    },
    {
      "sku": 2563138,
      "name": "Insignia™ - 48\" Class (47-5/8\" Diag.) - LED - 1080p - 60Hz - HDTV",
      "salePrice": 399.99
    }

Applies to: Products API • Stores API • Categories API

You can specify the way in which you’d like to have the results sorted by one or more attribute value(s).

Sort by multiple attributes

To sort by multiple attributes, separate the sort terms with commas. The results will initially be sorted by the first attribute in the direction specified. Then, the results within each set will be sorted by the second attribute.

Child attribute sort limitation

The text after the period in the sort parameter is interpreted as the sort direction. Therefore, you cannot sort by a child attribute, as it inherently includes a period in its name.

Facets

curl 'https://api.bestbuy.com/v1/products(categoryPath.name="All%20Flat-Panel%20TVs")?format=json&show=sku,name,salePrice&facet=manufacturer,5&apiKey=YourAPIKey'
var bby = require('bestbuy')('YourAPIKey');
bby.products('categoryPath.name="All Flat-Panel TVs"',{show:'sku,name,salePrice',facet:'manufacturer,5'}).then(function(data){
  console.log(data);
});

Show the 5 manufacturers for which we have the most flat-panel TVs.

{
  "products": [
  ],
  "facets": {
    "manufacturer": {
      "samsung": 96,
      "lg": 46,
      "sharp": 24,
      "vizio": 23,
      "insignia™": 18
    }
  }
}

Applies to: Products API • Stores API • Categories API

You can retrieve summary information about the items that are returned by your query by using the facets query parameter.

Pagination

curl 'https://api.bestbuy.com/v1/products(type=Movie)?format=json&show=sku,name,salePrice&pageSize=3&page=10&apiKey=YourAPIKey'
var bby = require('bestbuy')('YourAPIKey');
bby.products('type=Movie',{show:'sku,name,salePrice',page:10,pageSize:3}).then(function(data){
  console.log(data);
});

In this example we ask for the 10th page of results and for each page to contain just 3 products.

{
  "from": 28,
  "to": 30,
  "total": 101727,
  "currentPage": 1000,
  "totalPages": 33909,
  "queryTime": "0.039",
  "totalTime": "0.048",
  "partial": false,
  "canonicalUrl": "/v1/products(type=\"Movie\")?show=sku,name,salePrice&format=json&pageSize=3&page=10&apiKey=YourAPIKey",
  "products": [
    {
      "sku": 17215997,
      "name": "AC/DC: Rock Power (DVD)",
      "salePrice": 11.99
    },
    {
      "sku": 23003222,
      "name": "AC/DC: Rocks Detroit (DVD)",
      "salePrice": 10.99
    }

Applies to: Products API • Stores API • Categories API • Recommendations API • Buying Options API

Even if you’ve trimmed down the number of products returned by making use of search, many of our APIs have the potential to return lots of results. To make these large responses more manageable, we break them into pages. By default, we include 10 results per page, but you can ask for up to 100 per page by making use of the pageSize parameter. Use the page parameter to choose which page of results you’d like returned.

Here is an explanation of the meta data when more than one page is available

Name Description Additional Details
canonicalURL the non-server part of the query
currentPage the page being returned referred to as “page.current” for the Recommendations and Buying Options APIs
from the index of the first item returned on the current page not available on the Recommendations and Buying Options APIs
size the number of results returned per page only available on the Recommendations and Buying Options APIs
to the index of the last item returned on the current page not available on the Recommendations and Buying Options APIs
total the total number of items returned by the query referred to as “resultSet.count” for the Recommendations and Buying Options APIs
totalPages the number of pages required to list all items referred to as “page.total” for the Recommendations and Buying Options APIs

Retrieving Collections

Applies to: Products API • Stores API • Categories API

To retrieve more than one item at a time (e.g. all Products in our catalog), use one of the following queries. By default the max page size is 100 (meaning 100 unique results). See Pagination for more information on returning results greater than 100.

Description Query Result
retrieve all products https://api.bestbuy.com/v1/products?apiKey=YourAPIKey returns a collection of products
retrieve all stores https://api.bestbuy.com/v1/stores?apiKey=YourAPIKey returns a collection of stores
retrieve all categories https://api.bestbuy.com/v1/categories?apiKey=YourAPIKey returns a collection of categories

Other sections in this documentation explain how to modify these queries to retrieve only the information that you need.

Collection Header

When a query results in a collection, the response includes an information header containing the following attributes:

Name Description
item the type of items returned and counted
current page the page being returned
totalPages the number of pages required to list all items
from the index of the first item returned on the current page
to the index of the last item returned on the current page
total the total number of items returned by the query
queryTime the time required to search the database
totalTime the time required to parse, search, format and return results
canonicalURL the non-server part of the query URL
partial flag indicating whether or not the query returned only partial results (in the event of a timeout)

Bulk Downloads

Although we recommend that you make live calls to our APIs whenever possible, users who require a larger dataset may be better served by our Bulk Download API. Files are regenerated daily by 9AM CST.

The following APIs offer bulk downloading capabilities:

Errors

Applies to: Products API • Stores API • Categories API • Recommendations API

Best Buy uses standard HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g., a required parameter was missing), and codes in the 5xx range indicate an error with Best Buy’s servers.

Status Code Explanation
200 It is all good.
400 The request is missing key information or is malformed.
403 The API key is not valid, or the allocated call limit has been exceeded.
404 The requested item cannot be found.
405 Particular method not allowed (error will be returned for methods like a POST).
500, 501, 503 There is a server error on the Best Buy side.

Postman

Here’s a collection of sample queries in Postman that’ll help you get up to speed with our APIs faster.

Run in Postman

Important Notes

Getting Started

Get a key

Before you can start using our APIs, you need an API key. It’s easy. Just visit GET API Key and sign up with your email address. We’ll send you an email with instructions on how to activate your new key. Once you’ve activated your key, you’re ready to roll.

Create your first query

After you activate your key, you can start accessing Best Buy’s data.

Try our Query Builder

This easy-to-use tool will have you running queries in no time. The Query Builder tool will guide you through the creation of custom queries using most of the Best Buy APIs. You can use these queries as a base for your own custom queries, or use them to access Best Buy API data. You can access the Query Builder from our top menu bar or by going to Query Builder.

curl "https://api.bestbuy.com/v1/products/8880044.json?apiKey=YourAPIKey"

Returns the product document for SKU 8880044

{
  "sku": 8880044,
  "productId": 1484301,
  "name": "Batman Begins (Blu-ray Disc)"

  ...
}

Try accessing one of our APIs directly

Use a basic GET request to get API data. For example, to find product information for a specific product, you can query our Products API using the SKU for that product. The SKU for Batman Begins (Blu-ray Disc) is 8880044, so you can retrieve it as shown below. The response will be returned as either JSON or XML depending on the extension specified in the URI.

HINT: Don’t forget to replace YourAPIKey with the API key that you received from us.

Stay Connected

Keep up with the latest changes in our APIs through our release notes and blog.

Have fun and please let us know what you think. Shoot us an email at developer@bestbuy.com, tweet us at @BestBuyAPI or hop on the StackOverflow support forum and share your ideas on how we can deliver the best product. Let’s develop the future of retail together.

Search Techniques

Applies to: Products API • Stores API • Categories API

Search consists of one or more terms that generally include an attribute, operator and value. Terms are combined with ampersands & or pipes |. Searches are implemented as part of an HTTP GET request to the deisred Best Buy API. term1&term2 - specifies term1 AND term2 term1|term2 - specifies term1 OR term2.

Attribute names are case sensitive; attribute values are not.

Available Operators

Search by a single attribute

curl "https://api.bestbuy.com/v1/stores(region=ut)?format=json&show=storeId,city,region&apiKey=YourAPIKey"
var bby = require('bestbuy')('YourAPIKey');
bby.stores('region=ut',{show:'storeId,city,region'}).then(function(data){
  console.log(data);
});
{
  "from": 1,
  "to": 10,
  "total": 10,
  "currentPage": 1,
  "totalPages": 1,
  "queryTime": "0.002",
  "totalTime": "0.007",
  "partial": false,
  "canonicalUrl": "/v1/stores(region=\"ut\")?format=json&show=storeId,city,region&apiKey=YourAPIKey",
  "stores": [
    {
      "storeId": 1402,
      "city": "American Fork",
      "region": "UT"
    },
    {
      "storeId": 773,
      "city": "Orem",
      "region": "UT"
    }

Our Products, Stores and Categories APIs can be searched by nearly all available attributes. For example, to find only the stores located in Utah, you can use the query shown to the right.

Search by all attributes (AND)

curl 'https://api.bestbuy.com/v1/products(manufacturer=canon&salePrice<1000)?format=json&show=sku,name,salePrice&apiKey=YourAPIKey'
var bby = require('bestbuy')('YourAPIKey');
bby.products('manufacturer=canon&salePrice<1000',{show:'sku,name,salePrice'}).then(function(data){
  console.log(data);
});
{
  "from": 1,
  "to": 10,
  "total": 210,
  "currentPage": 1,
  "totalPages": 21,
  "queryTime": "0.095",
  "totalTime": "0.115",
  "partial": false,
  "canonicalUrl": "/v1/products(manufacturer=\"canon\"&salePrice<1000)?show=sku,name,salePrice&format=json&apiKey=YourAPIKey",
  "products": [
    {
      "sku": 6101087,
      "name": "Canon - 1.9x Tele Converter Lens",
      "salePrice": 99.99
    },
    {
      "sku": 8795075,
      "name": "Canon - 100-Pack 4\" x 6\" Glossy Photo Paper",
      "salePrice": 17.49
    }

If you need to search for the values of more than one attribute and all of the attributes must be present, combine them with an ampersand &.

Search by any attributes (OR)

curl "https://api.bestbuy.com/v1/products(wifiReady=true|wifiBuiltIn=true)?format=json&show=sku,name,salePrice&apiKey=YourAPIKey"
var bby = require('bestbuy')('YourAPIKey');
bby.products('wifiReady=true|wifiBuiltIn=true',{show:'sku,name,salePrice'}).then(function(data){
  console.log(data);
});
{
  "from": 1,
  "to": 10,
  "total": 500,
  "currentPage": 1,
  "totalPages": 50,
  "queryTime": "0.005",
  "totalTime": "0.030",
  "partial": false,
  "canonicalUrl": "/v1/products(wifiReady=true|wifiBuiltIn=true)?show=sku,name,salePrice&format=json&apiKey=YourAPIKey",
  "products": [
    {
      "sku": 1012749,
      "name": "Acer - Aspire 11.6 inch Tablet with 120GB Memory",
      "salePrice": 661.98
    },
    {
      "sku": 4255007,
      "name": "Acer - B1-720 7\" Android Tablet - 16GB - Iron Gray",
      "salePrice": 128.98
    }

If you want items with any of the specified attributes, combine them with a pipe |

Complex Searches

curl "https://api.bestbuy.com/v1/products(platform=psp&(salePrice<=15|(salePrice<=20&tradeInValue>=10)))?format=json&show=sku,name,salePrice&apiKey=YourAPIKey"
var bby = require('bestbuy')('YourAPIKey');
bby.products('platform=psp&(salePrice<=15|(salePrice<=20&tradeInValue>=10))',{show:'sku,name,salePrice'}).then(function(data){
  console.log(data);
});
[
  {
    "sku": 7049721,
    "name": "Ape Escape: On the Loose Greatest Hits - PSP",
    "salePrice": 7.99,
    "tradeInValue": 0.00,
    "platform": "PSP"
  },
  {
    "sku": 9335436,
    "name": "Chessmaster: The Art of Learning - PSP",
    "salePrice": 9.99,
    "tradeInValue": 0.00,
    "platform": "PSP"
  },
  {
    "sku": 1450486,
    "name": "Megamind: The Blue Defender - PSP",
    "salePrice": 11.99,
    "tradeInValue": 0.00,
    "platform": "PSP"
  }
]

Complex searches can be performed by combining AND & and OR | operations with parantheses. For example: let’s say that you’re looking for a Play Station Portable video game (platform=psp). You don’t want to spend more than $15 (salePrice<=15). However, because you will trade in the game when you’re done, you could spend up to $20 (saleProce<=20) - but only if the game’s trade-in value is more than $10 (tradeInValue>10).

The search terms for this example can be combined as:

platform=psp & (salePrice<=15 | (salePrice<=20 & tradeInValue>10))

Search by date range

curl "https://api.bestbuy.com/v1/products(releaseDate>=2014-02-01&releaseDate<=2014-02-28)?format=json&show=sku,name,salePrice&apiKey=YourAPIKey"
var bby = require('bestbuy')('YourAPIKey');
bby.products('releaseDate>=2014-02-01&releaseDate<=2014-02-28',{show:'sku,name,salePrice'}).then(function(data){
  console.log(data);
});
{
  "from": 1,
  "to": 10,
  "total": 4407,
  "currentPage": 1,
  "totalPages": 441,
  "queryTime": "0.064",
  "totalTime": "0.226",
  "partial": false,
  "canonicalUrl": "/v1/products(releaseDate>=2014-02-01&releaseDate<=2014-02-28)?show=sku,name,salePrice&format=json&apiKey=YourAPIKey",
  "products": [
    {
      "sku": 24311154,
      "name": "#lovestrock-CD",
      "salePrice": 22.99
    },
    {
      "sku": 23374755,
      "name": "(Untitled) - CD",
      "salePrice": 39.99
    }

If you want to find all products that were released February 2014, use this query:

Search by date relative to today

curl "https://api.bestbuy.com/v1/products(releaseDate>today)?format=json&show=sku,name,salePrice&apiKey=YourAPIKey"
var bby = require('bestbuy')('YourAPIKey');
bby.products('releaseDate>today',{show:'sku,name,salePrice'}).then(function(data){
  console.log(data);
});
{
  "from": 1,
  "to": 10,
  "total": 7688,
  "currentPage": 1,
  "totalPages": 769,
  "queryTime": "0.007",
  "totalTime": "0.032",
  "partial": false,
  "canonicalUrl": "/v1/products(releaseDate>today)?show=sku,name,salePrice&format=json&apiKey=YourAPIKey",
  "products": [
    {
      "sku": 24987148,
      "name": "$Ellebrity (DVD)",
      "salePrice": 19.99
    },
    {
      "sku": 6121399,
      "name": "& Then You Shoot Your Cousin - CD",
      "salePrice": 12.99
    }

You can also use the value today to represent the current day. If you want to see all the products that were released today, use this query.

Search for multiple attribute values

curl "https://api.bestbuy.com/v1/products(categoryPath.id=abcat0901005&color%20in(white,bisque,stainless-steel))?format=json&show=sku,name,salePrice&apiKey=YourAPIKey"
var bby = require('bestbuy')('YourAPIKey');
bby.products('categoryPath.id=abcat0901005&color in(white,bisque,stainless-steel)',{show:'sku,name,salePrice'}).then(function(data){
  console.log(data);
});
{
  "from": 1,
  "to": 10,
  "total": 52,
  "currentPage": 1,
  "totalPages": 6,
  "queryTime": "0.007",
  "totalTime": "0.033",
  "partial": false,
  "canonicalUrl": "/v1/products(categoryPath.id=abcat0901005&color in(\"white\",\"bisque\",\"stainless-steel\"))?show=sku,name,salePrice&format=json&apiKey=YourAPIKey",
  "products": [
    {
      "sku": 1614013,
      "name": "Amana - 25.4 Cu. Ft. Side-by-Side Refrigerator with Thru-the-Door Ice and Water - Stainless-Steel",
      "salePrice": 1099.99
    },
    {
      "sku": 1609858,
      "name": "Amana - 25.4 Cu. Ft. Side-by-Side Refrigerator with Thru-the-Door Ice and Water - White",
      "salePrice": 999.99
    }

If you want multiple values of a single attribute, you can specify them individually. For example, if you want to see white, bisque, or stainless-steel side-by-side refrigerators, use this query.

NOTE: To search for products based on a list of attribute values, we recommend using the in operator. Most attributes can be used with the in operator. The most common attribute used is SKU. Using the in operator helps to avoid Query Per Second errors (QPS).

For example: http://api.bestbuy.com/v1/products(sku in(43900,2088495,7150065))?apiKey=YourAPIKey

Wildcards - Value is present

curl "https://api.bestbuy.com/v1/products(categoryPath.id=abcat0502000&driveCapacityGb=*)?format=json&show=sku,name,salePrice&apiKey=YourAPIKey"
var bby = require('bestbuy')('YourAPIKey');
bby.products('categoryPath.id=abcat0502000&driveCapacityGb=*',{show:'sku,name,salePrice'}).then(function(data){
  console.log(data);
});
{
  "from": 1,
  "to": 10,
  "total": 381,
  "currentPage": 1,
  "totalPages": 39,
  "queryTime": "0.008",
  "totalTime": "0.039",
  "partial": false,
  "canonicalUrl": "/v1/products(categoryPath.id=abcat0502000&driveCapacityGb=*)?show=sku,name,salePrice&format=json&apiKey=YourAPIKey",
  "products": [
    {
      "sku": 4591017,
      "name": "Acer - 11.6\" Touch-Screen Chromebook - Intel Celeron - 2GB Memory - 32GB Solid State Drive - Moonstone White",
      "salePrice": 299.00
    },
    {
      "sku": 5009309,
      "name": "Acer - 14\" Touch-Screen Laptop - Intel Core i5 - 6GB Memory - 500GB HDD + 20GB Solid State Drive - Silver",
      "salePrice": 740.98
    }

You can use the asterisk * as a wildcard character. The wildcard can be used to:

Some attributes apply only to specific items. Even then, because much of this attribute information comes from the manufacturer, not all items of a given type will have values set for that attribute. You can use the wildcard to specify items that have data for a specific attribute.

Wildcards - Value is NOT present

curl "https://api.bestbuy.com/v1/products(categoryPath.id=abcat0502000&driveCapacityGb!=*)?format=json&show=sku,name,salePrice&apiKey=YourAPIKey"
var bby = require('bestbuy')('YourAPIKey');
bby.products('categoryPath.id=abcat0502000&driveCapacityGb!=*',{show:'sku,name,salePrice'}).then(function(data){
  console.log(data);
});
{
  "from": 1,
  "to": 10,
  "total": 42,
  "currentPage": 1,
  "totalPages": 5,
  "queryTime": "0.007",
  "totalTime": "0.270",
  "partial": false,
  "canonicalUrl": "/v1/products(categoryPath.id=abcat0502000&driveCapacityGb!=*)?show=sku,name,salePrice&format=json&apiKey=YourAPIKey",
  "products": [
    {
      "sku": 6941496,
      "name": "Apple® - MacBook Pro with Retina display - 13.3\" Display - 4GB Memory - 128GB Flash Storage",
      "salePrice": 1299.99
    },
    {
      "sku": 6293168,
      "name": "Apple® - MacBook Pro with Retina display - 13.3\" Display - 8GB Memory - 256GB Flash Storage",
      "salePrice": 1499.99
    }

This will return results in which there is no value present. In the following example, with the addition of the !, the return result has shifted from Solid State Drive.

Wildcards - String

curl 'https://api.bestbuy.com/v1/products(longDescription=iPhone*|sku=7619002)?show=sku,name&pageSize=15&page=5&apiKey=YourAPIKey&format=json'
var bby = require('bestbuy')('YourAPIKey');
bby.products('longDescription=iPhone*|sku=7619002',{show:'sku,name',pageSize:15,page:5}).then(function(data){
  console.log(data);
});
{
  "from": 61,
  "to": 75,
  "total": 2753,
  "currentPage": 5,
  "totalPages": 184,
  "queryTime": "0.010",
  "totalTime": "0.045",
  "partial": false,
  "canonicalUrl": "/v1/products(longDescription=\"iPhone*\"|sku=7619002)?show=sku,name&page=5&format=json&apiKey=YourAPIKey",
  "products": [
    {
      "sku": 1752654,
      "name": "Apple - iPhone 4s 8GB Cell Phone - White (AT&T)"
    },
    {
      "sku": 1761045,
      "name": "Apple - iPhone 4s 8GB Cell Phone - White (Verizon Wireless)"
    },
    {
      "sku": 1729354,
      "name": "Apple - iPhone 5c 16GB  Cell Phone - Green (AT&T)"
    },
    {
      "sku": 1752291,
      "name": "Apple - iPhone 5c 16GB Cell Phone - Blue (AT&T)"
    }
  ]
}

When used as part of a string search, the wildcard performs two functions. First, it tokenizes the string, breaking it into words. Second, it operates as a standard wildcard, matching any set of characters in the tokenized string. The following example illustrates both functions. When searching for a string value, you may want to search for variations on a specific word.

There are several description attributes by which you can search, including longDescription, shortDescription, description or name. There is a single SKU attribute to search based on SKU.

In this example we are searching the longDescription for iPhone*. We have appended iPhone with a wildcard * so we can search for iPhones with any suffix. We are also looking for any products that have a SKU with a value of 7619002 - note the or |. Finally, in our example we have updated the number of results that can be returned per page to 15. Our search will return page 5 of the total 184 pages. Additional information on how to specify the number of results that should be returned per page and which page to return can be found in our Pagination section.

Wildcard - Limitations

Filtered product attribute

Certain attributes, such as active=true, digital=false or preowned=false inherently filter results.

If your search string is sku=*, you will only return active products, not all products. This is the same as specifying sku=*&active=true. If you want a list of all active and inactive products, you can specify sku=*&active=*.

Because active is a boolean attribute, active=* will return products for which active is either true or false. It’s the same as sku=*&(active=true|active=false).

If your search string goes to sku.xml or sku.json these filters are ignored.

Keyword Search Function

curl "https://api.bestbuy.com/v1/products(search=oven&search=stainless&search=steel)?format=json&show=sku,name,salePrice&apiKey=YourAPIKey"
var bby = require('bestbuy')('YourAPIKey');
bby.products('search=oven&search=stainless&search=steel',{show:'sku,name,salePrice'}).then(function(data){
  console.log(data);
});

This example looks for ‘stainless steel ovens’.

{
"products": [
    {
      "sku": 6916066,
      "name": "Amana - 30 Self-Cleaning Freestanding Electric Range - Stainless-Steel",
      "salePrice": 584.99
    },
    {
      "sku": 2267329,
      "name": "Applica - 4-Slice Toaster Oven - Stainless Steel",
      "salePrice": 39.99
    }

Applies to: Products API

Our Keyword Search function (search=searchterm) allows you to search text accross several common attributes. To search for a term that includes a space, include an & ampersand between the words or it will be treated as an | or. The Keyword Search includes the following attributes:

Search on Reviews

curl "https://api.bestbuy.com/v1/products(customerReviewAverage>=4&customerReviewCount>100)?show=customerReviewAverage,customerReviewCount,name,sku&format=json&apiKey=YourAPIKey"
var bby = require('bestbuy')('YourAPIKey');
bby.products('customerReviewAverage>=4&customerReviewCount>100',{show:'customerReviewAverage,customerReviewCount,name,sku'}).then(function(data){
  console.log(data);
});
{
 "products": [
    {
      "customerReviewAverage": "4.1",
      "customerReviewCount": 411,
      "name": "Insignia™ - Soundbar Home Theater Speaker System",
      "sku": 4841342
    },
    {
      "customerReviewAverage": "4.3",
      "customerReviewCount": 411,
      "name": "Sunpak - PlatinumPlus 6000PG 61\" Tripod",
      "sku": 1205204
    }
  ]
}

To search for products based on customer review criteria, you can use the customerReviewAverage and/or the customerReviewCount attributes. You can also limit the product information returned using our show functionality. HINT: You can specify additional attributes in your search or to be included in the response document for most attributes in the Products API.

In this example, we are searching for all products that have a customer review average greater than four and a customer review count greater than 100. In addition, we are limiting the product information returned to customer review average, customer review count, name and sku, and forcing a format of json (default is xml when using the Products API).

Products API

The Best Buy Product API provides a simple, REST-based interface for our entire product catalog, past and present. This includes pricing, availability, specifications, descriptions, and images for more than one million current and historical products. In addition, we offer full archives, updated daily, to make it easier to establish our full catalog locally. Most product information is updated near real-time, including product pricing.

PLEASE NOTE: Music and movie data may be used only where an ability to purchase the related music or movies from BESTBUY.COM is provided to end users. Developers using music and movie data to redirect to BESTBUY.COM must become members of the Best Buy Affiliate Program to allow the sale of music and movies through BESTBUY.COM under the terms of the Affiliate Program.

Detail

The Best Buy Detail attributes contain a wealth of knowledge about Best Buy products. The intention of these attributes is to provide product descriptions, dimensions, accessories and reviews.

Attribute List

Attribute Description Type
accessories.sku Collection of SKUs that could be an accessory to originating SKU long
color Product color string
condition Identifies if the product is new, refurbished or pre-owned string
customerReviewAverage Average “score” or ratings as submitted by reviewers float
customerReviewCount Number of customer reviews integer
customerTopRated Identifies if the product is top rated based on ratings from reviewers. If the Avg rating >= 4.5 and Qty of ratings >= 15, customerTopRated is set to be “true”, else is set to “false” boolean
depth Product depth (inches) string
description Product description string
details.name Collection of details about product (Example: whether a camera has a zoom) string
details.value Collection of values that support the product (Example: A camera’s number of Megapixels or amount of zoom) string
digital Identifies if product is available in a digital format boolean
features.feature Collection of product features string
format Identifies media product format string
frequentlyPurchasedWith.sku Collection of SKUs that are frequently purchased with originating SKU long
height Product height (inches) string
includedItemList.includedItem Collection of items included with product (Example: Canon EOS 60D Digital SLR Camera, EF-S 18-135mm IS lens, Battery pack, Battery charger) string
longDescription Detailed product description string
longDescriptionHtml Detailed product description with HTML formatting string
manufacturer Product manufacturer string
modelNumber Manufacturer product model number string
name Product name string
preowned Identifies if product has been previously owned (used) boolean
quantityLimit Maximum quantity of product that can be ordered integer
relatedProducts.sku Collection of SKUs that are similar to originating SKU long
releaseDate Date the product was released date
shortDescription Brief product description string
shortDescriptionHtml Brief product description (HTML formatting) string
sku Best Buy unique product identifier long
upc Universal Product Code (UPC) string
warrantyLabor Manufacture labor warranty description string
warrantyParts Manufacture parts warranty description string
weight Product weight string
width Product width (inches) string

Pricing and Sales Ranking

Best Buy’s Pricing attributes make it easy to identify the product price, if a product is on sale, how much you can save and even when we made our last pricing changes. We also provide sales ranking over given time periods so you can have an idea of the best-sellers.

Attribute Description
bestSellingRank Ranks products by number of units sold
dollarSavings Identifies amount saved
lowPriceGuarantee Identifies if a product qualifies for the Best Buy low price guarantee
onSale Identifies if sale price is less than regular price
percentSavings Identifies the percent saved between the regularPrice and salePrice
priceRestriction Identifies product sale price display restrictions (guidelines for displaying lowest salePrice are sent to developers with privileged keys):
  • MAP restriction identifies Minimum Advertised Price; actual selling price may not be shown until prodcut is added to cart
  • ICR restriction identifies In-Checkout Rebate Price; actual selling price may not be shown until checkout
  • priceUpdateDate Date and time product price was last updated
    priceWithPlan.newTwoYearPlan Mobile phone price when purchased with new 2-year plan
    priceWithPlan.upgradeTwoYearPlan Mobile phone price when purchased with 2-year upgrade plan
    priceWithPlan.newTwoYearPlanSalePrice Mobile phone sale price when purchased with 2-year plan
    priceWithPlan.upgradeTwoYearPlanSalePrice Mobile phone sale price when purchased with 2-year upgrade plan
    priceWithPlan.newTwoYearPlanRegularPrice Mobile phone price when purchased with new 2-year plan
    priceWithPlan.upgradeTwoYearPlanRegularPrice Mobile phone price when purchased with 2-year upgrade plan
    regularPrice Product’s regular selling price
    salePrice Current item selling price
    salesRankLongTerm Sales rank over past 5-21 days
    salesRankMediumTerm Sales rank over past 2-4 days
    salesRankShortTerm Sales rank over past day

    Availability

    The Availability attributes provide details into which products can be purchased online and which products can be picked up in stores.

    Attribute Description
    friendsAndFamilyPickup Identifies if a product is eligible for friends and family pickup
    homeDelivery Identifies if a product must be fulfilled using home delivery instead of shipping
    inStoreAvailability Identifies if a product is available for purchase in a Best Buy store
    inStoreAvailabilityText Additional information regarding inStoreAvailability
    inStoreAvailabilityTextHtml Additional information regarding inStoreAvailability (HTML formatting)
    inStoreAvailabilityUpdateDate Provides date and time inStoreAvailability last updated
    inStorePickup Identifies if a product can be purchased online and picked up in a store
    onlineAvailability Identifies if a product can be purchased online
    onlineAvailabilityText Additional information regarding online availability
    onlineAvailabilityTextHtml Additional information regarding online availability (HTML formatting)
    onlineAvailabilityUpdateDate Provides date and time onlineAvailability was last updated
    orderable Product ordering status
    specialOrder Identifies whether a product will require special handling for delivery

    Shipping and Delivery

    The Shipping and Delivery attributes provide details about the cost of shipping or delivery of a product. A product can be shippable or deliverable, but not both.

    Sample shippingLevelsOfService response

    {
      "shippingLevelsOfService":[
        {
          "serviceLevelId": 1,
          "serviceLevelName": "Standard",
          "unitShippingPrice": 2.99
        },
        {
          "serviceLevelId": 3,
          "serviceLevelName": "Expedited",
          "unitShippingPrice": 10.99
        },
        {
          "serviceLevelId": 5,
          "serviceLevelName": "Express",
          "unitShippingPrice": 14.99
        }
      ]
    }
    
    Attribute Description
    freeShipping Identifies if a product qualifies for free shipping
    shippingCost Provides product’s lowest shipping costs
    shippingWeight Identifies product’s shipping weight (pounds)
    shippingLevelsOfService An array of shipping options
    shippingLevelsOfService.serviceLevelId ID of the shipping level of service
    shippingLevelsOfService.serviceLevelName Name of the shipping level of service
    shippingLevelsOfService.unitShippingPrice Price of the shipping level of service

    Images

    The Images attributes provide multiple images for a product. These include large, small, and side images and even interactive 360 degree images.

    Attribute Description
    accessoriesImage URL of accessories image
    alternateViewsImage URL of alternate image
    angleImage URL of product’s angle image
    backViewImage URL of rear image
    energyGuideImage URL of product’s EnergyGuide image
    image URL of BESTBUY.COM product detail page image
    largeFrontImage URL of large front image
    largeImage URL of image
    leftViewImage URL of left image
    mediumImage URL of medium image
    remoteControlImage URL of remote control image
    rightViewImage URL of right image
    spin360Url URL of 360-degree image
    thumbnailImage URL of image used on BESTBUY.COM listing pages
    topViewImage URL of top image

    The Links attributes provide a way for you to direct customers to a BESTBUY.COM product detail page or create a BESTBUY.COM cart on their behalf while including the product in the cart.

    Attribute Description
    addToCartUrl URL to BESTBUY.COM with item in cart
    url URL to BESTBUY.COM product detail page


    For our affiliate partners we provide this same functionality but use a special link so you can get credit for your sale. Affiliates add their LinkShare Affiliate Tracking Code (LID) to their query request. The URL generated will direct the customer to BESTBUY.COM with this item in their cart and credit the affiliate with the sale. Additional information on the affiliate program can be found here.

    Attribute Description
    linkShareAffiliateAddToCartUrl URL to BESTBUY.COM with item in cart
    linkShareAffiliateUrl URL to BESTBUY.COM product detail page

    Categorizations

    Best Buy provides multiple ways to group products based on your needs.

    The department, class and subclass attributes provide categorization structure or groupings of products. These attributes are returned as separate attributes but are related. The department attribute provides the more general categorization while the class and subclass attributes narrow the focus to be more specific. The class and subclass attributes are less volatile than category attributes and are the recommended attributes for grouping products.

    Attribute Description Type
    class Class name string
    classId Class identifiers integer
    department Department name string
    departmentId Department identifiers integer
    subclass Subclass name string
    subclassId Subclass identifier integer

    The categoryPath attributes provide a hierarchal view of a product returned as a collection. The collections start with the most general categorization, while subsequent categories narrow to be more specific. The number of categories returned can be 3+ layers deep. The products within the categories also tend to be slightly more volatile than department, class and subclass groupings.

    Attribute Description Type
    categoryPath.id Category identifiers string
    categoryPath.name Category names string

    The list attributes are used for specific events such as Valentine’s Day. These lists are curated by Best Buy merchant teams for customer visibility for a specific event or purpose.

    Attribute Description Type
    lists.endDate End date shown in list string
    lists.listId Name shown in list string
    lists.startDate Start date shown in list string

    Offers and Deals

    The Best Buy offer attributes provide a comprehensive view into the deals at Best Buy. This includes what is in our Sunday circular (also available online), our “Deal of the Day” and other special offers like “Free Shipping on Orders $35 and Up.” Each offer will contain a description of the offer and a link to the offer on BESTBUY.COM where applicable. Offer information is grouped together in a collection. Each product can have one or more offers associated to it.

    NOTE: Offers are updated on a daily basis. Offers are subject to change and applicability will be determined at checkout.

    Attributes Description
    offers.endDate Offer end date
    offers.id Offer identifier
    offers.startDate Offer start date
    offers.text Description of offer
    offers.type Offer types can include the following:
  • special_offer: identified by Best Buy marketing managers
  • digital_insert: identifies products that are a part of weekly insert that can be found in a Sunday newspaper
  • deal_of_the_day: small group of products being promoted for one day only
  • offers.url URL of offer information on BESTBUY.COM

    Listing Products

    We offer various metadata to support you when listing Best Buy products. This includes information such as whether a product is active, if it is new or refurbished, the type of product (music, movie, hardgood, bundle, game, blacktie, or software) and more.

    Attribute Description Type
    active Identifies if product is currently supported in the BESTBUY.COM catalog boolean
    activeUpdateDate Date and time the active attribute was last changed date
    bundledIn.sku Returns SKUs of bundles that that include this product long
    itemUpdateDate Date and time any change was made to this product date
    members.sku Collection of skus within a bundle long
    new Identifies if the product was added within last 30 days boolean
    secondaryMarket Identifies if product is a secondary market product boolean
    startDate Date Best Buy began selling product date
    type Best Buy product type, see section below for more details string

    Product Type Details

    Value Description
    blackTie Extended warranty services provided by the Best Buy GeekSquad team
    bundle A group of products; group can include both material and digital products
    game Games; includes both material and digital (downloadable) game products
    hardgood Products that are not of type music, movie, game, blackTie, software or bundle
    movie Movies; inclues both material and digital (downloadable) movie products
    music Music; includes both material and digital (downloadable) music products
    software Software; includes material and digital (downloadable) software products

    Products Bulk Download

    There are two files generated for all products:

    There is one file generated for all available stores for Best Buy products:

    Product Subset Downloads

    If you are interested in only one type of product, you can make a bulk download of one of our subsets. Subsets are also available each day by 9:00 am(CST).

    Type Description
    productsActive Includes digital, preowned; excludes BlackTie plans
    productsInactive Includes all inactive products; includes digital, preowned, BlackTie plans
    productsMusic Active music
    productsMovie Active movies
    productsHardgood Active hardgoods; includes preowned
    productsBundle Active bundles
    productsGame Active games; includes preowned
    productsSoftware Active software
    productsBlackTie Active BlackTie
    productsDigital Active digital products

    Query Syntax

    https://api.bestbuy.com/v1/subsets/[subset].[format].zip?apiKey=YourAPIKey

    Sample Query For Digital Products

    http://api.bestbuy.com/v1/subsets/productsDigital.xml.zip?apiKey=YourAPIKey

    Buying Options (Open Box) API

    The Buying Options API helps you access some of our best deals. This is where you’ll find information about ship-from-store eligible Open Box products including availability, condition and special pricing, with more to come as we build out this API further. Our Open Box endpoints provide access to several categories of Best Buy merchandise, similar to the “Buying Options” tab on BESTBUY.COM product detail pages. We typically have multiple Open Box products for a single SKU. When a customer purchases an Open Box product on BESTBUY.COM we ship from the closest Best Buy store based on the customer shipping address. To assist in selecting the correct Open Box product we assign a condition of “excellent or certified” to the product in every Open Box offer.

    We have split Open Box into multiple endpoints:

    All responses returned will be in a json format. In addition, we only return results for available product. We check for newly available product every five minutes. If you are an affiliate partner please see the Affiliate FAQ for instructions on proper use.

    Common Attributes

    Attribute Description
    customerReviews.averageScore Provides an average of all the ratings submitted for a product by reviewers. The customer can rate the product on a scale of 1-5 where 5 is the highest. Ratings may be returned using decimals
    customerReviews.count The total number of reviews collected
    descriptions.short A brief description of a product
    images.standard URL of BESTBUY.COM product detail page image
    links.product Link to the specific product in the Products API using a product identifier (SKU)
    links.web Link to the BESTBUY.COM product detail page using the Buying Options tab
    names.title Name of the product
    offers.condition The condition attribute will either be “excellent” (products that look brand new in appearance,with no physical flaws, scratches or scuffs and include all original parts and accessories) or “certified” (products that have passed the Geek Squad Certification process)
    offers.prices.current, “Open box” product’s current selling price
    offers.prices.regular “Open box” product’s regular selling price
    prices.current “New” product’s current selling price
    prices.regular “New” product’s regular selling price
    sku Unique identifier for products sold by Best Buy

    Open Box Single SKU

    curl "https://api.bestbuy.com/beta/products/8610161/openBox?apiKey=YourAPIKey"
    
    var bby = require('bestbuy')('YourAPIKey');
    bby.openBox(8610161).then(function(data){
      console.log(data);
    });
    

    Search all open box offers for SKU 8610161. We can see there are at least two offers excellent and certified.

    {
      "results": [
        {
          "customerReviews": {
            "averageScore": "4.5",
            "count": 471
          },
          "descriptions": {
            "short": "Google Chrome 64-bitTechnical details: Intel&#174; Celeron&#174; processor; 11.6\" display; 2GB memory; 16GB eMMC flash memorySpecial features: Bluetooth; HDMI outputNote: DVD/CD drive not included"
          },
          "images": {
            "standard": "http://img.bbystatic.com/BestBuy_US/images/products/8610/8610161_rc.jpg"
          },
          "links": {
            "product": "http://api.bestbuy.com/v1/products/8610161.json?apiKey=YourAPIKey",
            "web": "http://www.bestbuy.com/site/acer-11-6-chromebook-intel-celeron-2gb-memory-16gb-emmc-flash-memory-moonstone-white/8610161.p?id=1219351773817&skuId=8610161&cmp=RMX&ky=2l9pmD3wUBb9cc0tkHo49KBFCMPCiIPY4#tab=buyingOptions"
          },
          "names": {
            "title": "Acer - 11.6\" Chromebook - Intel Celeron - 2GB Memory - 16GB eMMC Flash Memory - Moonstone White"
          },
          "offers": [
            {
              "condition": "excellent",
              "prices": {
                "current": 175.99,
                "regular": 199
              }
            },
            {
              "condition": "certified",
              "prices": {
                "current": 187.99,
                "regular": 199
              }
            }
          ],
          "prices": {
            "current": 199,
            "regular": 199
          },
          "sku": "8610161"
        }
    }
    

    The Open Box Single SKU endpoint allows you to query by SKU all Open Box offers associated with a SKU. If there are no Open Box offers available, the query will return a HTTP 200 response code with an empty result set.

    Open Box by List of SKUs

    curl "https://api.bestbuy.com/beta/products/openBox(sku%20in(5729048,7528703,4839357,8153056,8610161))?apiKey=YourAPIKey"
    
    var bby = require('bestbuy')('YourAPIKey');
    bby.openBox('sku in(5729048,7528703,4839357,8153056,8610161)').then(function(data){
      console.log(data);
    });
    

    Returns available Open Box offers for 5 different SKUs

    {
      "metadata": {
        "resultSet": {
          "count": 6
        },
        "context": {
          "canonicalUrl": "http://api.bestbuy.com/beta/products/openBox(sku%20in(5729048,7528703,4839357,8153056,8610161,4591017))?apiKey=YourAPIKey"
        }
      },
      "results": [
        {
          "customerReviews": {
            "averageScore": "4.5",
            "count": 471
          },
          "descriptions": {
            "short": "Google Chrome 64-bitTechnical details: Intel&#174; Celeron&#174; processor; 11.6\" display; 2GB memory; 16GB eMMC flash memorySpecial features: Bluetooth; HDMI outputNote: DVD/CD drive not included"
          },
          "images": {
            "standard": "http://img.bbystatic.com/BestBuy_US/images/products/8610/8610161_rc.jpg"
          },
          "links": {
            "product": "http://api.bestbuy.com/v1/products/8610161.json?apiKey=YourAPIKey",
            "web": "http://www.bestbuy.com/site/acer-11-6-chromebook-intel-celeron-2gb-memory-16gb-emmc-flash-memory-moonstone-white/8610161.p?id=1219351773817&skuId=8610161&cmp=RMX&ky=2l9pmD3wUBb9cc0tkHo49KBFCMPCiIPY4#tab=buyingOptions"
          },
          "names": {
            "title": "Acer - 11.6\" Chromebook - Intel Celeron - 2GB Memory - 16GB eMMC Flash Memory - Moonstone White"
          },
          "offers": [
            {
              "condition": "excellent",
              "prices": {
                "current": 175.99,
                "regular": 199
              }
            },
            {
              "condition": "certified",
              "prices": {
                "current": 187.99,
                "regular": 199
              }
            }
          ],
          "prices": {
            "current": 199,
            "regular": 199
          },
          "sku": "8610161"
        },
    

    The Open Box by List of SKUs endpoint allows you to query all Open Box offers associated with a list of SKUs. The endpoint will return any available Open Box offers. If there is not an offer for a particular SKU in the list, that SKU will not be represented in the results. If there are no offers for any of the SKUs in the list, the query will return an HTTP 200 (OK) response code with an empty result set.

    NOTE: This endpoint accepts and returns at most 100 SKUs. The results are not paginated. Expect an HTTP 400 (Bad Request) response if you submit more than 100 SKUs.

    Open Box by Category

    curl "https://api.bestbuy.com/beta/products/openBox(categoryId=abcat0400000)?apiKey=YourAPIKey"
    
    var bby = require('bestbuy')('YourAPIKey');
    bby.openBox('categoryId=abcat0400000)').then(function(data){
      console.log(data);
    });
    

    Search all Open Box offers for SKUs that are a part of category abcat0400000; our Cameras & Camcorders category

    {
      "results": [
        {
          "customerReviews": {
            "averageScore": "4.7",
            "count": 145
          },
          "descriptions": {
            "short": "Compatible with most Canon DSLR cameras; stepping motor; 52mm filter size; 11.8\" minimum focus distance"
          },
          "images": {
            "standard": "http://img.bbystatic.com/BestBuy_US/images/products/5729/5729048_sc.jpg"
          },
          "links": {
            "product": "http://api.bestbuy.com/v1/products/5729048.json?apiKey=YourAPIKey",
            "web": "http://www.bestbuy.com/site/canon-ef-40mm-f-2-8-stm-standard-lens-black/5729048.p?id=1218688218296&skuId=5729048&cmp=RMX&ky=2l9pmD3wUBb9cc0tkHo49KBFCMPCiIPY4#tab=buyingOptions"
          },
          "names": {
            "title": "Canon - EF 40mm f/2.8 STM Standard Lens - Black"
          },
          "offers": [
            {
              "condition": "excellent",
              "prices": {
                "current": 167.99,
                "regular": 199.99
              }
            }
          ],
          "prices": {
            "current": 199.99,
            "regular": 199.99
          },
          "sku": "5729048"
        },
    }
    

    The Open Box by Category endpoint allows you to query all Open Box offers associated with the SKUs in the requested category. If there are no Open Box offers available, the query will return a HTTP 200 response code with an empty result set. You will want to search by Category ID. It is not possible to search by Category Name at this time.

    We recommend using our Categories API to identify the desired category. You can also look at the Products API category attributes to help identify those categories that you want to use to search Open Box offers.

    Use Pagination to review or retrieve the entire result set. If additional product information is needed you can use the links.product attribute to go to the Products API for a wealth of product information.

    Categories API

    The Categories API allows you to traverse the many categories on BESTBUY.COM and perform product searches based on category names or identifiers. The Categories API also allows you to search for specific product attributes within a specific category (example: TVs less than $100), search using multiple product attributes within a specific category (example: TVs released in the last year that are less than $100) or look at Best Buy taxonomy to better search and present Best Buy product data (example: HD TVs released in the last year that are less than $100).

    Category and Subcategory Paths

    As part of the category details, we provide a flat hierarchical path for each category. The path is a collection of all the categories in the path, starting with the root.

    Similarly, the Subcategories path attributes provide a collection of subcategories for the parent category. Each category can have one or more subcategories associated to it, which are identified by subcategory ids and names.

    The Products API also includes the category path information for each product. For additional information on the category attributes in Products API, refer to Categorizations.

    Common Attributes

    Attribute Description
    name Used to find all subcategories (e.g., parents, siblings, children) within a specific category
    id Used to find all results within a specific category (e.g., abcat0100000)
    path.name Used to find all categories, starting with the root, within a particular path (e.g., electronics)
    path.id Used to find all categories, starting with the root, within a particular path (e.g., abcat0014001)
    subCategories.name Used to identify subcategories within a specific category (e.g., Kitchen Essentials within Gift Ideas)
    subCategories.id Used to identify subcategories within a specific category (e.g., abcat0011002)

    Get All Categories

    curl "https://api.bestbuy.com/v1/categories?format=json&show=id&apiKey=YourAPIKey"
    
    var bby = require('bestbuy')('YourAPIKey');
    bby.categories('',{show:'id'}).then(function(data){
      console.log(data);
    });
    
    {
      "from": 1,
      "to": 10,
      "total": 4328,
      "currentPage": 1,
      "totalPages": 433,
      "queryTime": "0.003",
      "totalTime": "0.025",
      "partial": false,
      "canonicalUrl": "/v1/categories?show=id&format=json&apiKey=YourAPIKey",
      "categories": [
        {
          "id": "abcat0010000"
        },
        {
          "id": "abcat0020001"
        },
        {
          "id": "abcat0020002"
        },
        {
          "id": "abcat0020004"
        },
        {
          "id": "abcat0100000"
        }]
    }
    

    The query to the right will return all the Best Buy product categories. Query is filtered to show only ids.

    Search for a Category

    curl "https://api.bestbuy.com/v1/categories(name=Sony%20DSLR%20Camera*)?format=json&show=path&apiKey=YourAPIKey"
    
    var bby = require('bestbuy')('YourAPIKey');
    bby.categories('name=Sony DSLR Camera*',{show:'path'}).then(function(data){
      // The util package is loaded to print the complete object structure
      console.log(require('util').inspect(data, false, null));
    });
    
    {
      "from": 1,
      "to": 1,
      "total": 1,
      "currentPage": 1,
      "totalPages": 1,
      "queryTime": "0.011",
      "totalTime": "0.014",
      "partial": false,
      "canonicalUrl": "/v1/categories(name=\"Sony DSLR Camera*\")?show=path&format=json&apiKey=YourAPIKey",
      "categories": [
        {
          "path": [
            {
              "id": "cat00000",
              "name": "Best Buy"
            },
            {
              "id": "pcmcat128500050004",
              "name": "Name Brands"
            },
            {
              "id": "cat15063",
              "name": "Sony"
            },
            {
              "id": "pcmcat97200050015",
              "name": "Sony DSLR Camera"
            }
          ]
        }
      ]
    }
    

    The following query will return the category path for the category name specified in the input. In the below example we are requesting the category path for a Sony DSLR Camera. The query results are shown in a flat hierarchical path starting from the root. In this case Best Buy is the root category which is the first in the path, followed by its child category Name Brands, whose child is Sony, and its child Sony DSLR Camera, which is also the last category in this path.

    Categories Bulk Download

    There are two files generated for all categories:

    Recommendations API

    The Recommendations API offers Trending, Most Viewed and Also Viewed information about Best Buy products based on customer behavior at BESTBUY.COM. We have also provided functionality to look up similar products based on a SKU.

    Shared Attributes

    Attribute Description
    customerReviews.averageScore An average of all the ratings submitted for a product by reviewers
    customerReviews.count Total number of reviews collected
    description.short Brief description of a product
    images.standard URL of the BESTBUY.COM product detail page image
    links.addToCart URL that will direct the customer to BESTBUY.COM with the item in their cart
    links.product Link to the specific sku in the Products API
    links.web Link to the BESTBUY.COM product detail page
    names.title Name of the product
    prices.current Current selling price
    prices.regular Regular selling price
    sku Unique identifier for products sold by Best Buy
    curl "http://api.bestbuy.com/beta/products/trendingViewed(categoryId=abcat0400000)?apiKey=YourAPIKey"
    
    var bby = require('bestbuy')('YourAPIKey');
    bby.recommendations('trendingViewed','abcat0400000').then(function(data){
      console.log(data);
    });
    

    In this example we request Trending products based on category abcat0400000 otherwise known as “Cameras & Camcorders”. When pulling by category you should always use the category id. It is not possible to query by category name. For more information about identifying category ids please refer to our Categories API documentation.

    {
      "results": [
        {
          "customerReviews": {
            "averageScore": "4.9",
            "count": 309
          },
          "descriptions": {
            "short": "20.2-megapixel APS-C CMOS sensorShooting speeds up to 7 fpsBuilt-in Wi-Fi"
          },
          "images": {
            "standard": "http://img.bbystatic.com/BestBuy_US/images/products/8896/8896132_sc.jpg"
          },
          "links": {
            "product": "http://api.bestbuy.com/v1/products/8896132.json?apiKey=YourAPIKey",
            "web": "http://www.bestbuy.com/site/canon-eos-70d-dslr-camera-with-18-135mm-is-stm-lens-black/8896132.p?id=1218941181224&skuId=8896132&cmp=RMX&ky=2l9pmD3wUBb9cc0tkHo49KBFCMPCiIPY4",
            "addToCart": "http://www.bestbuy.com/site/olspage.jsp?id=pcmcat152200050035&type=category&cmp=RMX&ky=2l9pmD3wUBb9cc0tkHo49KBFCMPCiIPY4&qvsids=8896132"
          },
          "names": {
            "title": "Canon - EOS 70D DSLR Camera with 18-135mm IS STM Lens - Black"
          },
          "prices": {
            "current": 1449.99,
            "regular": 1549.99
          },
          "rank": 6,
          "sku": "8896132"
        },
    

    The Trending Products endpoint returns top ten products, by rank, based on customer views of the BESTBUY.COM product detail page over a rolling three hour time period. Trending growth is based on a comparison against the previous three hour time period. You can also pull this same information by category or subcategory. For more information about identifying category ids please refer to our Categories API documentation.

    Note: Minimum of 50 page views/hr required for inclusion. In addition, deep subcategories may not have enough user traffic to generate trending data.

    Attribute Description
    rank The rank of a product as compared to the velocity of other trending products. The number rank 1 identifies the most highly trending product while a number 10 rank would identify the 10th trending product
    curl "https://api.bestbuy.com/beta/products/mostViewed(categoryId=abcat0107000)?apiKey=YourAPIKey"
    
    var bby = require('bestbuy')('YourAPIKey');
    bby.recommendations('mostViewed','abcat0107000').then(function(data){
      console.log(data);
    });
    

    Request Most Viewed products based on category abcat0107000 otherwise known as “TV & Home Theater Accessories.” When pulling by category you should always use the category id. It is not possible to query by category name.

    {
      "results": [
        {
          "customerReviews": {
            "averageScore": "4.6",
            "count": 15
          },
          "descriptions": {
            "short": "Lets you connect your Apple&#174; TV to a VGA-enabled projector; converts digital HDMI output to analog VGA signal; 3.5mm audio port; 6' cord"
          },
          "images": {
            "standard": "http://images.bestbuy.com/BestBuy_US/images/products/1740/1740039_sc.jpg"
          },
          "links": {
            "product": "http://api.bestbuy.com/v1/products/1740039.json",
            "addToCart": "http://www.bestbuy.com/site/olspage.jsp?id=pcmcat152200050035&type=category&cmp=RMX&ky=1xrtkOPXgHdxEmF4yQx1jGyxiihDiJ5c2&qvsids=1740039"
            "web": "http://www.bestbuy.com/site/belkin-hdmi-to-vga-adapter/1740039.p?id=1219062507184&skuId=1740039&cmp=RMX&ky=2dN2vg9ikE823Sb2cqFFchnSnf6JkvQna"
          },
          "names": {
            "title": "Belkin - HDMI-to-VGA Adapter"
          },
          "prices": {
            "current": 25.99,
            "regular": 49.99
          },
          "rank": 7,
          "sku": "1740039"
        },
    

    The Most Popular Viewed endpoint returns the top ten products, by rank, of the most frequently viewed products on BESTBUY.COM. You can also pull this same information by category or subcategory. To find out additional information about identifying category ids please refer to our Categories API documentation. This data for Most Popular Viewed is refreshed every two hours with a maximum accumulation time of 48 hours when determining the top ten products.

    Note: The difference between Trending Products and Most Popular Viewed Products is that Trending Products reflects change in velocity of product views while Most Popular Viewed reflects page views only.

    Attribute Description
    rank The rank of a product based on how frequently it is viewed on BESTBUY.COM product detailed page

    Also Viewed

    curl "https://api.bestbuy.com/beta/products/5747275/alsoViewed?apiKey=YourAPIKey"
    
    var bby = require('bestbuy')('YourAPIKey');
    bby.recommendations('alsoViewed',5747275).then(function(data){
      console.log(data);
    });
    
    {
      "results": [
        {
          "customerReviews": {
            "averageScore": null,
            "count": null
          },
          "descriptions": {
            "short": null
          },
          "images": {
            "standard": "http://images.bestbuy.com/BestBuy_US/images/products/nonsku/default_movies_l.jpg"
          },
          "links": {
            "product": "http://api.bestbuy.com/v1/products/5747275.json",
            "addToCart": "http://www.bestbuy.com/site/olspage.jsp?id=pcmcat152200050035&type=category&cmp=RMX&ky=1xrtkOPXgHdxEmF4yQx1jGyxiihDiJ5c2&qvsids=5747275"
            "web": "http://www.bestbuy.com/site/batman-begins-blu-ray-disc/8880044.p?id=1484301&skuId=8880044&cmp=RMX&ky=1xrtkOPXgHdxEmF4yQx1jGyxiihDiJ5c2"
          },
          "names": {
            "title": "Batman Begins (2 Disc) (Ultraviolet Digital Copy) (Blu-ray Disc)"
          },
          "prices": {
            "current": 9.99,
            "regular": 9.99
          },
          "rank": 3,
          "sku": "5747275"
        },
    }
    

    The Also Viewed Products endpoint can be used to identify top ten products that were viewed along with the originating product. These results are determined based on aggregated customer browsing behavior over the past thirty days on BESTBUY.COM.

    Also Viewed Product Specific Attributes

    Attribute Description
    rank The rank of the product based on how many views a product received after starting with originating SKU. The number 1 rank identifies the highest number of page views an associated product received while looking at originating SKU while the number 10 rank identifies the product with the 10th highest page views while look at same originating product

    Similar Products

    curl "http://api.bestbuy.com/beta/products/2874502/similar?apiKey=YourAPIKey"
    
    var bby = require('bestbuy')('YourAPIKey');
    bby.recommendations('similar',2874502).then(function(data){
      console.log(data);
    });
    
    {
      "results": [
        {
          "customerReviews": {
            "averageScore": "4.8",
            "count": 6957
          },
          "descriptions": {
            "short": "7.9\" LED-backlit displayA5 chip5.0MP iSight camera with 1080p HD video recordingFaceTime HD camera"
          },
          "images": {
            "standard": "http://images.bestbuy.com/BestBuy_US/images/products/2874/2874502_sc.jpg"
          },
          "links": {
            "product": "http://api.bestbuy.com/v1/products/2874502.json",
            "addToCart": "http://www.bestbuy.com/site/olspage.jsp?id=pcmcat152200050035&type=category&cmp=RMX&ky=1xrtkOPXgHdxEmF4yQx1jGyxiihDiJ5c2&qvsids=2874502"
            "web": "http://www.bestbuy.com/site/apple-ipad-mini-with-wi-fi-16gb-space-gray-black/2874502.p?id=1219080300496&skuId=2874502&cmp=RMX&ky=2dN2vg9ikE823Sb2cqFFchnSnf6JkvQna</url>"
          },
          "names": {
            "title": "Apple® - iPad® mini Wi-Fi - 16GB - Space Gray"
          },
          "prices": {
            "current": 299.99,
            "regular": 299.99
          },
          "rank": 2,
          "sku": "2874502"
        },
    

    The Similar Products endpoint can be used to identify similar SKUs based on a SKU. The algorithm used to identify similar SKUs uses attributes like brand, size, price, etc.

    Note: Music and Movies are currently excluded from this endpoint.

    Similar Products Specific Attributes

    Attribute Description
    rank The rank of the product based on how closely the return product matches the attributes of the original product

    Stores API

    curl "https://api.bestbuy.com/v1/stores?format=json&show=city,longName&pageSize=2&apiKey=YourAPIKey"
    
    var bby = require('bestbuy')('YourAPIKey');
    bby.stores('',{show:'city,longName',pageSize:2}).then(function(data){
      console.log(data);
    });
    

    Returns the city and store name of 2 stores

    {
      "from": 1,
      "to": 2,
      "total": 1587,
      "currentPage": 1,
      "totalPages": 794,
      "stores": [
        {
          "city": "San Juan",
          "longName": "Best Buy - Hato Rey"
        },
        {
          "city": "Bayamon",
          "longName": "Best Buy - Rio Hondo Mall"
        }
      ]
    }
    

    The Best Buy Stores API provides store information for all Best Buy stores in the United States and Puerto Rico. This information includes address, location, hours and services offered.

    In addition, store availability of a product can be determined by querying the Products API together with the Stores API. Refer to In Store Availability for more information on these type of queries.

    Common Attributes

    curl "https://api.bestbuy.com/v1/stores(postalCode=55423)?format=json&show=storeId,storeType,name,city,region&apiKey=YourAPIKey"
    
    var bby = require('bestbuy')('YourAPIKey');
    bby.stores('postalCode=55423', {show: 'storeId,storeType,name,city,region'}).then(function(data){
      console.log(data);
    });
    

    Returns all stores at the ZIP code 55423 (Richfield, MN)

    {
      "from": 1,
      "to": 3,
      "total": 3,
      "currentPage": 1,
      "totalPages": 1,
      "stores": [
        {
          "storeId": 2387,
          "storeType": "Mobile",
          "name": "Best Buy Mobile - Richfield",
          "city": "Richfield",
          "region": "MN"
        },
        {
          "storeId": 281,
          "storeType": "BigBox",
          "name": "Richfield",
          "city": "Richfield",
          "region": "MN"
        },
        {
          "storeId": 8001,
          "storeType": "Express",
          "name": "Best Buy HQ",
          "city": "Richfield",
          "region": "MN"
        }
      ]
    }
    

    The Stores API enables you to retrieve the basic store information for all Best Buy stores, a specific Best Buy store or those stores that match a set of search parameters.

    Attribute Description
    address Street address
    address2 Street address 2 provides additional street address information for the Best Buy store in the result set
    city City name
    country Country name
    distance Store distance from specified location in miles; attribute is not queryable; use with lat and long or postal code
    fullPostalCode 9-digit postal code if available for store location
    lat Latitude
    lng Longitude
    location Details about location of a store; primarily used for identifying Best Buy Express stores
    longName Full store name
    name Store name
    phone Store phone number; phone number for Express stores goes to Best Buy Customer Service
    postalCode 5-digit postal code
    region State, territory
    storeId Store number
    storeType Indicates the type of store
  • There are three types of Best Buy stores: “Big Box”, “Mobile” and “Express”
  • “Big Box” value represents large showroom stores featuring HDTVs, computers, gaming, appliances, cell phones, tablets, Geek Squad services and more
  • “Mobile” value represents specialty shops focused on smartphones, tablets, accessories, services and plans
  • “Express” value represents vending machine-style, self-checkout stores offering audio goods and accessories, found in airports, on college campuses and more
  • tradeIn Indicates the type of trade-ins accepted at stores
  • Possible trade in values include: “trade-in - no-receipt”, “trade-in - no receipt (biometric)”, “trade-in - best buy receipt required”, “trade-in - no receipt (2 ids required)”, “no trade-ins accepted”, “trade-in - no receipt (biometric with 2 ids)”, “trade-in - no receipt for video games. best buy receipt for other items”
  • For more information about trade-in policies, please visit the local store page
  • Area Function

    curl "https://api.bestbuy.com/v1/stores(area(55423,10))?format=json&show=storeId,storeType,name&pageSize=2&apiKey=YourAPIKey"
    
    var bby = require('bestbuy')('YourAPIKey');
    bby.stores('area(55423,10)',{show:'storeId,storeType,name', pageSize: 2}).then(function(data){
      console.log(data);
    });
    

    Returns stores within 10 miles of ZIP code 55423 (Richfield, MN)

    {
      "from": 1,
      "to": 2,
      "total": 22,
      "currentPage": 1,
      "totalPages": 11,
      "stores": [
        {
          "storeId": 2387,
          "storeType": "Mobile",
          "name": "Best Buy Mobile - Richfield"
        },
        {
          "storeId": 281,
          "storeType": "BigBox",
          "name": "Richfield"
        }
      ]
    }
    

    The Stores API includes a special function area(location,distance) enabling you to locate stores near a specified location.

    Use the postalCode attribute or a lat-long pair to search based on a location. When postal code is used the reference point in the postal code (zipcode) area is determined by a standard mapping service. If no distance is specified in the function, radius is defaulted to 10 miles. The location will be populated with the distance from the specified postal code or lat/long to the store in miles.

    Note: You may notice the stores returned are stated to be just over 10 miles from the ZIP code. This is due to the way return distance is calculated. The search area is defined as a square, bounded by location point +/- distance identified in request. All stores in that square are returned. Return distance is calculated linearly from the location point (creates a circle). Stores near the corner of the square might be listed as farther than the query distance specified.

    Hours

    curl "https://api.bestbuy.com/v1/stores(storeId=1118)?format=json&show=hours,hoursAmPm,gmtOffset,detailedHours&apiKey=YourAPIKey"
    
    var bby = require('bestbuy')('YourAPIKey');
    bby.stores('storeId=1118',{show:'hours,hoursAmPm,gmtOffset,detailedHours'})
       .then(function(data){
         // The util package is loaded to print the complete object structure
         console.log(require('util').inspect(data, false, null));
       });
    

    Shows all hours that store #1118 (San Juan, PR) is open

    {
      "from": 1,
      "to": 1,
      "total": 1,
      "currentPage": 1,
      "totalPages": 1,
      "stores": [
        {
          "hours": "Mon: 10-9; Tue: 10-9; Wed: 10-9; Fri: 12:01-10; Sat: 9-10; Sun: 11-8",
          "hoursAmPm": "Mon: 10am-9pm; Tue: 10am-9pm; Wed: 10am-9pm; Fri: 12:01am-10pm; Sat: 9am-10pm; Sun: 11am-8pm",
          "gmtOffset": -5,
          "detailedHours": [
            {
              "day": "Sunday",
              "date": "2015-11-22",
              "open": "11:00",
              "close": "20:00"
            },
            {
              "day": "Monday",
              "date": "2015-11-23",
              "open": "10:00",
              "close": "21:00"
            }
            // Typically returns 14 days, truncating from documentation
          ]
        }
      ]
    }
    

    The Hours attributes provide the days and times each Best Buy store is open for the following two weeks. We start our weeks on Sunday and provide hours in both a 12-hour and 24-hour clock. The times displayed are for the local time zones of the Best Buy store being returned. The Detailed Hours attributes provide the most accurate information of when stores will be opened or closed. This can be helpful during holidays as store hours may vary during this time.

    Hint: Detailed hours are filtered out from the search results by default. Query with show=all or show=detailedHours to see in the search results.

    Attribute Description
    detailedHours.day Days of the week store will be open
    detailedHours.date Dates store will be open
    detailedHours.open Time store will open (24-hour clock)
    detailedHours.close Time store will close (24-hour clock)
    gmtOffset Time difference from GMT
    hours Regular Best Buy store hours Monday through Friday for the calendar year; displayed in local time zone
    hoursAmPm Regular Best Buy store hours Monday through Friday for the calendar year with am and pm identifiers; displayed in local time zone

    Services Offered

    curl "https://api.bestbuy.com/v1/stores(storeId=1118)?format=json&show=services&apiKey=YourAPIKey"
    
    var bby = require('bestbuy')('YourAPIKey');
    bby.stores('storeId=1118',{show:'services'}).then(function(data){
      // The util package is loaded to print the complete object structure
      console.log(require('util').inspect(data, false, null));
    });
    

    Shows all services available at store #1118 (San Juan, PR)

    {
      "from": 1,
      "to": 1,
      "total": 1,
      "currentPage": 1,
      "totalPages": 1,
      "stores": [
        {
          "services": [
            {
              "service": "Windows Store"
            },
            {
              "service": "Geek Squad Services"
            },
            {
              "service": "Best Buy Mobile"
            },
            {
              "service": "Best Buy For Business"
            },
            {
              "service": "Apple Shop"
            },
            {
              "service": "Electronics Recycling"
            },
            {
              "service": "Best Buy Marine Powered by Geek Squad"
            },
            {
              "service": "Samsung Experience"
            },
            {
              "service": "LG Experience "
            },
            {
              "service": "Car & GPS Installation Services"
            }
          ]
        }
      ]
    }
    

    The Stores API includes information related to the services offered at each of the Best Buy stores. services is a collection of different services offered at a specified store.

    Attribute Description
    services.service Collection of services offered at each Best Buy store

    In-Store Availability

    curl "https://api.bestbuy.com/v1/stores(area(44.882942,-93.2775,3)&storeType=Express)+products(sku=5038019)?format=json&show=storeId,storeType,city,region,name,products.name,products.sku,products&pageSize=1&apiKey=YourAPIKey"
    
    //Not yet implemented
    

    Shows Express stores within 3 miles of 44.882942,-93.2775 (Richfield, MN) that carry SKU 5038019 (Insignia 5-Way Stereo Splitter).

    {
      "from": 1,
      "to": 1,
      "total": 3,
      "currentPage": 1,
      "totalPages": 3,
      "stores": [
        {
          "storeId": 8001,
          "storeType": "Express",
          "city": "Richfield",
          "region": "MN",
          "name": "Best Buy HQ",
          "products": [
            {
              "name": "Insignia™ - 6\" 5-Way Stereo Splitter - White",
              "sku": 5038019
            }
          ]
        }
      ]
    }
    

    The Stores API, in conjunction with the Products API, allows you to search stores for a product and identify if it is available. In-store availability searches will return only those stores that have a given product in stock. Stores not returned do not have that product in stock. When completing an in-store availability query you should limit the stores that are a part of the query.

    Availability in stores is calculated using counts and previous-day sales to determine if the product is likely to be available, might be available or is unlikely to be available. The algorithm errs on the side of caution, and anything that is not available defaults to “not available”.

    HINT: The Products API attribute inStoreAvailability will tell you if a product is sold in stores but not if it’s available at a particular store. Using the In-Store availability queries is equivalent to checking product availability in store.

    Stores Bulk Download

    There are two files generated for all available store information:

    There is one file generated for all available stores for Best Buy products:

    Commerce API

    The Best Buy Commerce API allows our partners to introduce a seamless cart experience to their customers, exposing the ability to select various fulfillment options including Store Pickup at one of our 1,400+ locations, Ship To Home and Home Delivery. If you have not yet been issued a Commerce API key, please contact developer@bestbuy.com.

    Within the Commerce APIs, partners can use:

    Functionality

    Full documentation supplied once you have a CAPI Key.

    Getting a Commerce API Key

    Please contact us at developer@bestbuy.com to request an invite to the Commerce API program and a corresponding API Key. Current CAPI partners can access reporting and documentation via the same address.