Release Notes

2015 Jul (R15.7)

Remix Release 2015
The Products API Featured Offers has been RETIRED. The data within the Featured Offers has evolved to be landing pages on BESTBUY.COM instead of individual SKUs. We will continue to provide Special Offers, Deal of the Day Offers and Digital Insert Offers. If you have any concerns please reach out to us at developer@bestbuy.com.

Release (Remix-1.11)


2015 June (R15.6)

Remix Release 2015 R9

  • Updated postal codes to include any new postal codes. Queries that include the Stores API may now return additional stores.
  • Possible data outage: Throughout July and August, product-offer information within Best Buy is being adjusted. There may be sporadic times when endpoints containing promotion information (e.g. “This item has free shipping.”) will be negatively impacted. If your business relies on this information for critical needs, please contact developer@bestbuy.com so we can proactively inform you if side-effects become unavoidable.

Release (remix-1.0.172)


2015 May (R15.5)

Remix Release 2015 R8

  • Updated the Product Offers Deal of the Day source
  • No longer populating Deal of the Day offers.text field. Previously this provided a description of the product but upon further analysis this was determined to be repetitive given the other product description fields.
  • Will no longer publish a SKU with a rank of 1 for the following attributes. The SKU with a rank of 1 has caused confusion in the past and therefore is being suppressed.
    • bestSellingRank
    • salesRankShortTerm
    • salesRankMediumTerm
    • salesRankLongTerm
  • The Products API Featured Offers will be removed in the next couple of weeks. The data within the Featured Offers has evolved to be landing pages on BESTBUY.COM instead of individual SKUs. We will continue to provide Special Offers, Deal of the Day Offers and Digital Insert Offers.

Release (Remix-1.8)


2015 Apr (R15.4)

Remix Release 2015 R7

  • Added Address2 attribute to Stores API. This attribute will provide additional address information for Best Buy stores.

Release (Remix-1.0.7)


2015 Mar (R15.3)

New Addition to the SmartList API

The Active Adventurer Smart List endpoint gives access to suggested top rated products (average review equal or greater to 4.5 and at least 15 reviews) for the fitness and outdoor enthusiast.

URL Breakdown
- baseURL : http://api.bestbuy.com/beta/products
- connectedHome : activeAdventurer
- apiKey : ?apiKey=YourAPIKey
Full URL
http://api.bestbuy.com/beta/products/activeAdventurer?apiKey=YourAPIKey
Example Response

In this example we are calling the Active Adventurer endpoint. Notice this endpoint takes no parameters.

#request:
http://api.bestbuy.com/beta/products/activeAdventurer?apiKey=YourAPIKey

#response:
{ "metadata": { "resultSet": { "count": 23 }, "context": { "canonicalUrl": "http://api.bestbuy.com/beta/products/activeAdventurer?apiKey=YourAPIKey" } }, "results": [ { "customerReviews": { "averageScore": "4.8", "count": 798 }, "descriptions": { "short": "4K15, 2.7K30, 1440p48, 1080p60, 960p100 and 720p120 fps video capture; 12.0MP digital still resolution; touch-screen display; Protune; Auto Low Light mode; SuperView; QuikCapture; waterproof housing; Wi-Fi; Bluetooth" }, "images": { "standard": "http://img.bbystatic.com/BestBuy_US/images/products/8374/8374096_sc.jpg" }, "links": { "product": "http://api.remix.bestbuy.com/v1/products/8374096.json?apiKey=YourAPIKey", "web": "http://www.bestbuy.com/site/gopro-hero4-silver-action-camera/8374096.p?id=1219329115702&skuId=8374096&cmp=RMX&ky=28eiIkWRnU6kpSRaThWcSIdBYJmvGGbrI", "addToCart": "http://www.bestbuy.com/site/olspage.jsp?id=pcmcat152200050035&type=category&cmp=RMX&ky=28eiIkWRnU6kpSRaThWcSIdBYJmvGGbrI&qvsids=8374096" }, "names": { "title": "GoPro - HERO4 Silver Action Camera" }, "prices": { "current": 399.99, "regular": 399.99 }, "sku": "8374096" }, ...

Removal of Mock 404

We have made various improvements to our code and 404s should be a rare occurrence. Given these changes the mock 404 is extraneous and we are retiring it.

Addition of Categories to Query Builder

We have added support for our Categories API in the Query Builder tool. You can now do queries based on

  • All Categories
  • Top Level Categories
  • Search Categories by Name
  • Search Categories by Category Id

Now including pageSize and page in Canonical URL

Upon request we are now including the pageSize and page as part of the Canonical URL in our response document. If there is no pageSize or page requested they will not be a part of the response. This will impact the following endpoints

  • Open Box by Category
  • Open Box All SKUs
Example of Canonical URL with pageSize and page
canonicalUrl: "https://api.bestbuy.com/beta/products/openBox?apiKey=yourAPIKey&page=2&pageSize=15"

As a quick reminder the pageSize specifies the number of items that should be returned per page. The page specifies which page of the response should be returned. Additional documentation can be found in the Overview documentation.

Release (15.3)


2015 Feb (R15.2a)

Introduction of the SmartLists API

The SmartLists API provides access to a guided shopping experience. We are launching with Connected Home but intend to add additional lists to this API.

URL Breakdown
- baseURL : http://api.bestbuy.com/beta/products
- connectedHome : connectedHome
- apiKey : ?apiKey=YourAPIKey
Full URL
http://api.bestbuy.com/beta/products/connectedHome?apiKey=YourAPIKey
Example Response

In this example we are calling the Connected Home endpoint. Notice this endpoint takes no parameters.

#request:
http://api.bestbuy.com/beta/products/connectedHome?apiKey=YourAPIKey

#response:
{ "metadata": { "resultSet": { "count": 18 }, "context": { "canonicalUrl": "http://api.bestbuy.com/beta/products/connectedHome?apiKey=YourAPIKey" } }, "results": [ { "customerReviews": { "averageScore": "4.6", "count": 704 }, "descriptions": { "short": "Compatible with most 24V heating and cooling systems; works with PEQ; Airwave, Auto-Schedule and Auto-Away functions; System Match technology; Wi-Fi connectivity; 1.75\" LCD panel" }, "images": { "standard": "http://img.bbystatic.com/BestBuy_US/images/products/6913/6913825_sc.jpg" }, "links": { "product": "http://api.remix.bestbuy.com/v1/products/6913825.json?apiKey=YourAPIKey", "web": "http://www.bestbuy.com/site/nest-learning-thermostat-2nd-generation-stainless-steel/6913825.p?id=1218813789398&skuId=6913825&cmp=RMX&ky=28eiIkWRnU6kpSRaThWcSIdBYJmvGGbrI", "addToCart": "http://www.bestbuy.com/site/olspage.jsp?id=pcmcat152200050035&type=category&cmp=RMX&ky=28eiIkWRnU6kpSRaThWcSIdBYJmvGGbrI&qvsids=6913825" }, "names": { "title": "Nest - Learning Thermostat - 2nd Generation - Stainless-Steel" }, "prices": { "current": 249.99, "regular": 249.99 }, "sku": "6913825" }, ...

Replacement of API Console with Query Builder

We have replaced our IO Docs with Query Builder. This custom angular app guides the user through creation of queries for most of our APIs. You can access it in our top menu or by going to the Query Builder link.

Recommendations and Buying Options endpoints will now return results for inactive SKUs, Categories and SubCategories

For Recommendations and Buying Options we will no longer be validating that SKUs, Categories or SubCategories are active. We will now allow you to run queries using inactive SKUs, Categories or SubCategories. This was done to better support inquiries and standardized our responses.

Release (15.2a)


2015 Feb (R15.2)

Enhancement to Recommendations Trending Products Endpoint

We now have the ability to request Trending Products by category and sub-category. This was already in place for our Recommendations Most Popular Viewed. To complete the search just call the Trending Products endpoint with any category or sub-category id.

http://api.bestbuy.com/beta/products/trendingViewed(categoryId=abcat0400000)?apiKey=YourAPIKey

You can find additional information and examples of the Trending Products by Category in our Trending Products documentation. To identify additional categories or sub-categories please refer to our Categories documentation.

Enhancement to Buying Options API

We are adding an Open Box List of SKUs endpoint. 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.

To complete the search call the open box endpoint using the in operator.

http://api.bestbuy.com/beta/products/openBox(sku in(5729048,7528703,4839357,8153056,8610161))?apiKey=YourAPIKey

You can find additional information and examples of the Open Box by List of SKUs in our Open Box documentation.

New Value for condition attribute

The condition attribute will now contain pre-owned in addition to refurbished and new. The pre-owned value will represent products that were previously owned and Best Buy received as part of a trade-in before reselling. We are adding this value to better represent the status of our existing product data set. We are not adding additional products.

The Existing preowned attribute will represent broader data set

Previously we used the preowned attribute to identify games that had been previously owned. We are expanding the use of this attribute for any product with a type of hardgood in addition to game.

Release (15.2)


2015 Jan (R14.9)

Enhancement to Buying Options API (BETA)

We have further enhanced the Open Box endpoint in the Buying Options API to search by Category. This allows you to use any of our Categories or Subcategories to search for Open Box offers. Here is an example of how to search for categories. The response document will look identical to the Open Box Single SKU and is also included below. Please see our Buying Options API for additional information.

Open Box by Category Request:

http://api.bestbuy.com/beta/products/openBox(categoryId=abcat0400000)?apiKey=YourAPIKey

Open Box by Category Response Document:

{
  "metadata": {
    "resultSet": {
      "count": 63
    },
    "context": {
      "canonicalUrl": "http://api.bestbuy.com/beta/products/openBox(categoryId=abcat0400000)"
    },
    "page": {
      "current": 1,
      "size": 10,
      "total": 7
    }
  },
  "results": [
    {
      "customerReviews": {
        "averageScore": "4.7",
        "count": 170
      },
      "descriptions": {
        "short": "Compatible with Canon EOS cameras with an EF mount; UD (Ultra-low Dispersion) lens elements; optical image stabilizer technology; ultrasonic motor; accommodates 58mm filters"
      },
      "images": {
        "standard": "http://img.bbystatic.com/BestBuy_US/images/products/7528/7528703_sc.jpg"
      },
      "links": {
        "product": "http://api.remix.bestbuy.com/v1/products/7528703.json",
        "web": "http://www.bestbuy.com/site/canon-ef-70-300mm-f-4-5-6-is-usm-telephoto-zoom-lens-black/7528703.p?id=1127507945894&skuId=7528703&cmp=RMX&ky=2l9pmD3wUBb9cc0tkHo49KBFCMPCiIPY4#tab=buyingOptions"
      },
      "names": {
        "title": "Canon - EF 70–300mm f/4–5.6 IS USM Telephoto Zoom Lens - Black"
      },
      "offers": [
        {
          "condition": "excellent",
          "prices": {
            "current": 545.99,
            "regular": 649.99
          }
        }
      ],
      "prices": {
        "current": 649.99,
        "regular": 649.99
      },
      "sku": "7528703"
    },

Renamed Open Box Endpoint

We have renamed the Open Box endpoint Open Box Multi SKU to be Open Box All SKUs. This was done to better reflect the functionality provided by that endpoint.

Removal of "arg" from Buying Options and Recommendations endpoints

We have removed "args" from our Buying Options and Recommendations endpoints. This information is already available in the canonical URL and therefore deemed redundent. Here is an example of the data we removed:

  "args": {
        "LID": null,
        "apiKey": null,
        "callback": null,
        "id": null
      },

Release (14.9)


2014 Dec (R14.8)

NEW Buying Options API (BETA)

The Buying Options API gives you access to information about ship-from-store eligible Open Box products, including their availability, condition and special pricing. Please note the ship-from-store Open Box information is just the initial data we are exposing via this end-point. We will continue to build out our Buying Options data in future releases. Check out our documentation for detailed information about the Buying Options API.

Enhancements to the Recommendations API

We are releasing two enhancements to our Recommendations API:

  1. We are adding attributes to the Recommendations documents. Please see the Recommendations API documentation for a full list of new attributes. PLEASE NOTE: We have moved and renamed the productLink attribute. It is now in the new links section and called product.
  2. The Most Popular Viewed endpoint has been enhanced to allow you to pull the top products by category or subcategory.

NEW Best Buy Express Stores in the Stores API

The Stores API API will now contain Best Buy Express (kiosk) locations. The Best Buy Express Stores added approximately 200 new locations to the stores API. In order to identify the Best Buy Express stores we added a new value to the <storeType> attribute of "express". We also added a new <location> attribute that provides descriptive information about the location of a kiosk where existing address information is insufficient. The Store Availability API will also contain SKUs in the Best Buy Express kiosks.

Archive correction

The reference to " productsHardGood" in Archives was inaccurate. This should have listed " productHardgood" with a lower case g. You will need to use "productHardgood" to retreive this archive.

Release (14.8)


2014 Oct (R14.7)

Variable Attribute Changes Explained - Details

As we stated in our release notes for 2014 Oct (R14.6) Variable Attribute Changes Explained, Best Buy continues with our updating of variable attributes (product details).

Affected Attributes Here is a list of the attributes we know will be deprecated and/or altered in release R14.7:

  • analogAudioInputs - Deprecated
  • avOutputs - Deprecated
  • brightnessNits - New Int
  • brightnessCdPerSqM - New Int
  • builtInDigitalCamera - will continue, and will be further expressed as:
    • frontFacingCamera - New boolean
    • rearFacingCamera - New boolean
  • builtForBluRay - Deprecated
  • builtInPlayer - Deprecated
  • capacityCuFt - will be supplemented with:
    • capacityRefrigeratorCuFt - New Decimal
    • capacityFreshFoodCuFt - New Decimal
    • capacityFreezerCuFt - New Decimal
  • clock - Deprecated
  • combFilter - Deprecated
  • customSettings - Deprecated
  • cycleDescriptions - Deprecated
  • digitalAudioOutputs - Deprecated and replaced with:
    • numberOfOpticalDigitalAudioOutputs - New Int
    • numberOfCoaxialDigitalAudioOutputs - New Int
  • digitalOutputs - Deprecated
  • digitalTuner - Deprecated
  • dolbyDigitalDecoder - Deprecated
  • dynamicContrastRatio - Deprecated and replaced with:
    • maximumContrastRatioDynamic - New String
    • minimumContrastRatioDynamic - New String
  • estimatedYearlyOperatingCosts - Deprecated (was a list of values) and replaced with:
    • estimatedYearlyOperatingCostsUsd - New Int
  • fiveOneChannelInput - Deprecated
  • fiveOneChannelOutput - Deprecated
  • frontPanelAvInputs - Deprecated
  • frontSurroundPowerPerChannel - Deprecated
  • hdRadioCompatible - Deprecated
  • hdRadioReady - Deprecated
  • hdtvCompatibility - Deprecate
  • heightWithStandIn - Deprecated and replaced with:
    • productHeightIn - New Decimal
    • maximumStandHeightIn - New Decimal
    • minimumStandHeightIn - New Decimal
    • standHeightIn - New Decimal
  • ipodDock - Deprecated
  • iphoneAccessory - Deprecated
  • lcdScreenSizeIn - Deprecated, users should rely on screenSizeIn
  • ledButtons - Deprecated
  • maximumPowerHandling - Deprecated
  • maximumResolutionHorizontalPx - Deprecated
  • maximumResolutionVerticalPx - Deprecated
  • mediaPort - Deprecated
  • mms - Deprecated
  • mp3PlaybackCapability - Deprecated
  • pcInputs - Deprecated, replaced with: pcInput - New Boolean
  • phonoInputs - Deprecated
  • powerSourceRatings - Deprecated
  • preampOutputs - Deprecated
  • rearSurroundPowerPerChannel - Deprecated
  • rfAntennaInputs - Deprecated, replaced with: rfAntennaInput - New Boolean
  • sanitationAllergyCycle - Deprecated, replaced with:
    • sanitationCycle - New Boolean
    • allergyCycle - New Boolean
  • satelliteRadioReady - Deprecated
  • sdCardSlot - Deprecated
  • shelfSystemType - Deprecated
  • sixOneChannelInput - Deprecated
  • soundLeveler - Deprecated
  • soundType - Deprecated
  • speakerLocation - Deprecated
  • subwooferPowerWatts - Deprecated
  • subwooferSizeIn - Deprecated
  • surroundSoundDecoders - Deprecated
  • threeDPassThrough - Deprecated
  • thruTheDoorIceDispenser - Deprecated, replaced with: throughTheDoorDispenser
  • thruTheDoorWaterDispenser - Deprecated, replaced with: throughTheDoorDispenser
  • touchPadControls - Deprecated
  • waterFiltrationReplacementIndicatorLight - Deprecated
  • wattsPerChannel - Deprecated, replaced with wattsPerChannelRms

If additional attributes are marked for elimination, we will communicate those as they are identified.

Release (re14.6)


2014 Sept (R14.6)

Variable Attribute Changes Explained

As we noted in our blog a few weeks ago In Which We Prepare You for Something You May Not Need to Fret About, Best Buy is updating some aspects to how our product data is structured, particularly the variable attributes (product details). These changes will make our product data more consistent and easier to understand. Over time, some attributes will disappear from the API as the data changes flow into production.

What does this mean?

  • Direct searches on these attributes will no longer produce results.
  • These attributes will no longer appear as top-level attributes on product data returned by the Products API.
  • The data represented by these attributes may still be available in the details collection of relevant products - but the detail name and format and even structure of the detail value may be different than has appeared in the past.

Runtime responses from the Products API will continue to indicate that these attributes can be used​ for searching, even as the attributes slowly disappear from the product data. Please pay close attention to any attributes you are calling that are not explicitly documented in our Products API as these are the attributes that could be deleted or have changes to the data.

Example

The top level attribute clock is being retired. Over time, the results of a search on clock=* will diminish. Eventually, that search will return no results. However, in the details of some products, you may find a detail named clockDisplay with a value of "Yes" or "No". In other products, you may find details named with other variations indicating clock with a variety of possible values.

This will impact applications that provide filtering using the top level attributes. If an application provides filtering for whether products include a clock using the clock top level attribute, that filtering will cease to work as expected over time. This change should not cause such an application to produce an error or cease functioning.

The product data updates will also impact applications that display these attributes. In this example, the clock attribute will no longer display. If the application has hard-coded usage of the clock attribute, that application may produce errors or cease functioning.

Affected Attributes

Here is a current list of the attributes we know will gradually be removed as described above:

  • avOutputs
  • builtForBluRay
  • clock
  • customSettings
  • cycleDescriptions
  • digitalAudioInputs
  • digitalAudioOutputs
  • digitalOutputs
  • digitalTuner
  • dolbyDigitalDecoder
  • fiveOneChannelInput
  • fiveOneChannelOutput
  • hdtvCompatibility
  • sixOneChannelInput

If additional attributes are marked for elimination, we will communicate those out as they are identified.

Release (re14.5)


2014 July (R14.5)

Recommendations API Beta

We are adding a suite of new endpoints called RECOMMENDATIONS that provides insight into customer behavior on BESTBUY.COM. The Recommendations APIs include /similar, /trendingViewed, /mostPopular and /alsoViewed.

To get access to these new endpoints while they are in beta, please send your user name and key(s) to developer@bestbuy.com and we will enable them for your existing api key(s). If you don't have an api key, visit our registration page first.

The response returned from our Recommendations endpoints is similar to that of our Product API. We have included an example for our /similar endpoint below. You can see an example of the other responses in our Recommendations documentation.

#request:
http://api.bestbuy.com/beta/products/1741029/similar

#response:
{ "metadata": { "resultSet": { "count": 10, "limit": 10, "offset": 0 } }, "results": [ { "productLink": "http://api.remix.bestbuy.com/v1/products/1752305.json", "rank": 1, "sku": "1752305" }, { "productLink": "http://api.remix.bestbuy.com/v1/products/1755252.json", "rank": 2, "sku": "1755252" }, { "productLink": "http://api.remix.bestbuy.com/v1/products/1752122.json", "rank": 3, "sku": "1752122" }, ...
SIMILAR PRODUCTS

The /similar endpoint takes any hardgood or software SKU and returns the top products similar to it based on the number of product attributes that match.

TRENDING PRODUCTS

The /trendingViewed endpoint returns what is hot right now on BESTBUY.COM by returning the top ten trending products based on product page views over a specific timeframe.

MOST POPULAR VIEWED PRODUCTS

The /mostViewed endpoint returns the most frequently viewed products across all of BESTBUY.COM based on page views (versus Trending Products that shows change in velocity).

ALSO VIEWED PRODUCTS

The /alsoViewed endpoint returns the most frequently viewed products other customers viewed after the driver SKU.

Release (mi14.31, re14.4)


2014 June (R14.4)

New attributes

Products API

  • customerTopRated - We have added a new attribute called customerTopRated to our Products API. This attribute indicates if the product is top rated based on the customer reviews.Its a boolean set to be true/false. If Avg Rating >= 4.5 and Qty of reviews >= 15, customerTopRated is set to "true",else is set to "false".

Example

#request:
http://api.remix.bestbuy.com/v1/products(sku=1152566)?apiKey=YourAPIKey&show=sku,customerTopRated

#response:
<products currentPage="1" totalPages="1" from="1" to="1" total="1" queryTime="0.100" totalTime="0.106" canonicalUrl="/v1/products(sku=1152566)?show=sku,customerTopRated&amp;apiKey=YourAPIKey" partial="false"> <product> <sku>1152566</sku> <customerTopRated>true</customerTopRated> </product> </products>

Stores API

We have added two new attributes storeType and tradeIn to our Stores API.

  • storeType - This attribute will give additional store type information such as "Big Box" or "Mobile".
  • tradeIn - This attribute provides the store trade-in policy and conditions to trade-in products such as mobile phones and games.

Example

#request:
http://api.remix.bestbuy.com/v1/stores(storeId=768)?apiKey=YourAPIKey&show=storeID,storeType,tradeIn

#response:
<stores currentPage="1" totalPages="1" from="1" to="1" total="1" queryTime="0.004" totalTime="0.006" canonicalUrl="/v1/stores(storeId=1118)?show=storeID,storeType,tradeIn&amp;apiKey=YourAPIKey" partial="false"> <store> <storeId>768</storeId> <storeType>BigBox</storeType> <tradeIn>Trade-In - No-receipt</tradeIn> </store> </stores>

Enhancement

Products API

Related Products: The data source for relatedProducts attribute has been updated which will provide both more relevant related product information and data for more SKUs in our catalog than our old source.


2014 May (R14.3)

This is one of those invisible releases that actually includes a lot of updates, but all of them are operational - they make the API work more efficiently, improve the quality of data etc. With these updates you won't see any external attribute or functional changes.


2014 February (R14.2)

Remix has added a new set of attributes to the Products API called productFamilies. The product families will initially display just the alternate color product family when applicable. A product family will list associated SKUs based on the grouping specified (alternate color). This feature will give you the capability to list associated products to the parent SKU based on the grouping/family.

For instance, a yellow iPhone 5c will have options for other colors of that same phone.

Example
#request:
http://api.remix.bestbuy.com/v1/products/8830226.xml?apiKey=yourAPIKey&show=sku,productFamilies

#response:
<product> <sku>8830226</sku> <productFamilies> <productFamily> <name>alternateColors</name> <skus> <sku>8830235</sku> <sku>8830217</sku> </skus> </productFamily> </productFamilies> </product>

2014 January (R14.1)

In September 2013, we converted to LinkShare from Commission Junction for affiliate marketing commissions.With this release, the Commission Junction links are no longer active and will return an error page when used.This also means that we have removed the following attributes from the products API:

  • cjAffiliateUrl
  • cjAffiliateAddToCartUrl

When the old PID parameter associated with Commission Junction is passed to us in an API call we will now return the following error and message:

400 Bad Request

For information on using your Linkshare Id, see our Affiliate Program page.


2013 November (R13.8)

New attributes

Stores API – additional attributes for store hours.

The new attributes contain 24 hour time and two weeks of store hour data which can be used to display a rolling week. Please note that you must specify show=all for the new attributes to display in your query.

  • detailedHours.day - specific day of the week
  • detailedHours.date - provides the date of the day
  • detailedHours.open - store opening time for that day
  • detailedHours.close - store closing time for that day
  • gmtOffset
  • hoursAmPm - Store open hrs for the entire week in AM/PM format
Example
#request:
http://api.remix.bestbuy.com/v1/products(name=playstation*&digital=true&startDate%3E=2011-01-01)?show=sku,name,digital,inStoreAvailabilityText,onlineAvailabilityText,startDate&apiKey=yourAPIKey

#response:
<stores currentPage="1" totalPages="146" from="1" to="10" total="1459" queryTime="0.002" totalTime="0.019" canonicalUrl="/v1/stores?show=detailedHours,hoursAmPm&amp;apiKey=yourAPIKey" partial="false"> <store> <detailedHours> <detailedHour> <day>Sunday</day> <date>2014-04-13</date> <open>11:00</open> <close>19:00</close> </detailedHour> <detailedHour> <day>Monday</day> <date>2014-04-14</date> <open>10:00</open> <close>21:00</close> </detailedHour> <detailedHour> <day>Tuesday</day> <date>2014-04-15</date> <open>10:00</open> <close>21:00</close> </detailedHour> <detailedHour> <day>Wednesday</day> <date>2014-04-16</date> <open>10:00</open> <close>21:00</close> </detailedHour> <detailedHour> <day>Thursday</day> <date>2014-04-17</date> <open>10:00</open> <close>21:00</close> </detailedHour> <detailedHour> <day>Friday</day> <date>2014-04-18</date> <open>10:00</open> <close>21:00</close> </detailedHour> <detailedHour> <day>Saturday</day> <date>2014-04-19</date> <open>10:00</open> <close>21:00</close> </detailedHour> ...

2013 October (R13.7)

Enhanced Functionality

Faceting – facet function

We now support a facet=attribute,{number of facets} function for attributes which can be queried. The default number of facets returned is 10.

Refer to our Documentation page for details

Example
#request:
http://api.remix.bestbuy.com/v1/products?facet=categoryPath.Id,5&apiKey=yourAPIKey

#response:
<products currentPage="1" totalPages="71418" from="1" to="10" total="714180" queryTime="0.413" totalTime="0.449" canonicalUrl="/v1/products?facet=categoryPath.Id,5&amp;apiKey=yourAPIKey" partial="false"> <facets> <field>categoryPath.Id</field> <facet> <name>cat00000</name> <count>711452</count> <name>abcat0600000</name> <count>669580</count> <name>cat02001</name> <count>572076</count> <name>cat02009</name> <count>183757</count> <name>cat02015</name> <count>97497</count> </facet> </facets> ...

2013 September (R13.6)

Attributes for our new Affiliate Management Agency LinkShare

Affiliates need to include LID={LinkShare publisher ID} after the '?' in a query.

  • linkShareAffiliateUrl - should takes the visitor to the bestbuy.com PDP of the product and track referral credit.
  • linkShareAffiliateAddToCartUrl - should instantiate a bestbuy.com cart with the product in the cart and track referral/sales credit.

Enterprise free shipping promotion change

Best Buy introduced a new free shipping promotion on 9/12/13 which is cart based. Our new promotion has the following details: Free Shipping on orders $25 & up

Excludes: Marketplace (based on seller offer) and some scheduled delivery categories (there are some free schedule delivery offers in market based on category), and items displaying “In Store Only” message.

We added an attribute which indicates whether a SKU qualifies for this promotion and will count toward the $25 shopping cart value.

Example
#request:
http://api.remix.bestbuy.com/v1/products/16306454.xml?apiKey=yourAPIKey

#response:
<product> <sku>16306454</sku> <name>! (Bonus Track) (Japan) - CD</name> <freeShippingEligible>true</freeShippingEligible> <freeShipping>true</freeShipping> <salePrice>45.99</salePrice> <shipping> <ground>0.00</ground> <secondDay>8.99</secondDay> <nextDay>11.99</nextDay> <vendorDelivery/> </shipping> </product>

Enhanced Search functionality

Range function

We now support a range(lower,upper) function for numeric and date attributes only. Ranges will be inclusive (>=, <=). If upper is less than lower, results will be equivalent to attr>=upper&attr<=lower (search for values outside of a give range). When used with date attributes, offset will be in days.

Approximate searches on date/time attributes

We now support approximate searches on date-type and time attributes using tilde (~) operator. When used with these attribute types, ~ is the equivalent of ±. When used with date attributes, the value will be in days. Ranges will be inclusive (>=, <=).

Refer to the Documentation page for details on range and approximate searches.


2013 August (R13.5)

Enhanced Search Functionality

Approximate Search

We now support approximate searches on numeric attributes using the tilde (~) operator.

When used with numeric attribute types the ~ is the equivalent of ±. Ranges will be inclusive (>=,<=). Numeric-types include integer, float, double, dollar, etc.

Example
  • screenSizeIn=56~0.5 is equivalent to screenSizeIn>=55.5&screenSizeIn<=56.5
  • salePrice=180~10 is equivalent to salePrice>=170&salePrice<=190

2013 July (R13.4)

New attributes

Regular and Sale Price for Phones with Plans

We have added more clarity to the pricing for cell phones with plans by adding four new attributes. The new pricing attributes will show the regular and sale price for cell phones with plans for both new two year contracts and upgrades.

Example

#request:
http://api.remix.bestbuy.com/v1/products/2210015.xml?apiKey=yourAPIKey&show=priceWithPlan

#response:
<product> <priceWithPlan> <newTwoYearPlan>199.99</newTwoYearPlan> <upgradeTwoYearPlan/> <newTwoYearPlanSalePrice>199.99</newTwoYearPlanSalePrice> <upgradeTwoYearPlanSalePrice/> <newTwoYearPlanRegularPrice>299.99</newTwoYearPlanRegularPrice> <upgradeTwoYearPlanRegularPrice/> </priceWithPlan> </product>

Geek Squad Tech Support

Best Buy has added an attribute called <techSupportPlans> which will list associated SKUs for Geek Squad Technical Support to the parent SKU (typically laptops and tablets). Here is a sample of the new attribute with this information.

Example

#request:
http://api.remix.bestbuy.com/v1/products/9026045.xml?apiKey=yourAPIKey&show=sku,name,techSupportPlans

#response:
<product> <sku>9026045</sku> <name>Lenovo - Yoga Ultrabook 2-in-1 11.6&quot; Touch-Screen Laptop - 4GB Memory - 128GB Solid State Drive - Silver</name> <techSupportPlans> <sku>1853259</sku> </techSupportPlans> </product>

2013 May (R13.3)

New attributes

  • percentSavings - We are adding a new attribute, percentSavings, which does the calculation of percent savings between the regularPrice and salePrice attributes. This attribute will allow you to easily find SKUs with the highest percent savings in the catalog.
  • lowPriceGuarantee - This attribute will allow you to easily find SKUs that participate in the Best Buy Low Price Guarantee.
  • services.service - This attribute has been added to the Stores API so that you can easily find stores with specific store services.
Example
#request:
http://api.remix.bestbuy.com/v1/stores?apiKey=yourAPIKey&show=services

#response:
<stores currentPage="1" totalPages="146" from="1" to="10" total="1459" queryTime="0.002" totalTime="0.011" canonicalUrl="/v1/stores?show=services&amp;apiKey=yourAPIKey" partial="false"> <store> <services> <service>Windows Store</service> <service>Geek Squad Services</service> <service>Best Buy Mobile</service> <service>Best Buy For Business</service> <service>Apple Shop</service> <service>Electronics Recycling</service> <service>Car &amp; GPS Installation Services</service> </services> </store>

2013 April (R13.2)

Well, in addition to our usual under-the-covers improvements, we've got a lot in this release that will make your queries more comprehensive.

First, under the covers, we've upgraded some of our software to keep our tools up to date. We've also changed the way we calculate one value to make it more consistent. Both of these changes will be transparent to you, but will make your queries more efficient. On to the more visible improvements!

Shipping restrictions

As you know, marketplace products are those that are carried by Best Buy, but shipped by other companies. Some of these products have shipping restrictions. There may be locations these companies cannot ship to, or that may have shipping surcharges. Because these restrictions vary, in the near term we will simply use a new attribute, shippingRestrictions, to indicate marketplace products with restrictions. The restriction details will be available when you add the product to your cart.

  • shippingRestrictions - "This product may have destination restrictions or shipping surcharges. See details in cart."

Eventually, we will expose shipping restriction details in our new availability attributes. New availability attributes? Stay tuned - they're coming soon!

Broader attribute coverage

Because of data source limitations, we limited some of our attributes to certain product types. With this release, we are expanding coverage for these attributes.

  • dollarSavings - Now calculated for all products.
  • shippingWeight - Now populated for all shippable products.

New attributes

In order to more closely match the information provided on our website, this release expands our attributes for music and movies, and includes a new attribute for marketplace products and some movies.

Music

  • mediaCount - Number of discs
  • monoStereo - Mono or stereo recording
  • studioLive - Studio or live performance

Movies

  • additionalFeatures - Bonus tracks, interviews, trailers, etc.
  • videoChapters - The movie's scenes
  • videoLanguage - Main audio language
  • screenFormat - Enhanced Widescreen for 16x9 TV, Full Screen, Widescreen
  • subtitleLanguage - Subtitle language (obviously!)
  • fulfilledBy - Some movies sold by Best Buy are actually fulfilled by Cinema Now. To make sure you know where your movie is coming from, with this release we are adding a new attribute, fulfilledBy, to indicate if a given movie is from Cinema Now. (If fulfilledBy has no value, the movie is from Best Buy!)

2013 March (R13.1)

The freeze is over (we're even thawing out up here in Minnesota), and we're releasing code again. This month, many of our updates deal with infrastructure, but there are some that will enhance your queries. First, under the covers, we updated some of our software after security vulnerabilities were found (with the software in general, not with the API). Haven't heard of any problems, and we shouldn't have any in the future.

Also, our internal upstream data sources are changing some of the data they propagate, so we changed our data import processes to make sure you keep getting the information you expect.

Now for the more visible changes.

New Attribute

productTemplate

There are lots of ways to “categorize” products, and you’re probably familiar with categoryPath, department, class, and subclass. We now have another attribute you can use, productTemplate. That may sound like an odd name, but it relates to the product data-modeling template we use internally to store product information. We needed to expose this information to some internal API users, and decided to make it public, in case you or other partners might find it helpful. You can think of productTemplate as sort of a “subtype”. Some examples include: Digital_Camera_Accessory, Entertainment_Furniture,Printers, Video_Game_Software.

https support

Based on requests from many of you, you'll be happy to know that we now support https, as well as http. If your application is set up to use https, you can now send your queries with that protocol, as well. While the data will be returned via https, links within the data (images, cart, cjAffiliate links, etc.) will retain their original addresses, which are generally http.

New digital products

What's faster than next-day delivery or in-store pickup? Electronic delivery. Some products, such as music and software, can be delivered on line via email or through a download link. This is not new; we have offered digital products for a while. However, Best Buy is changing the way it catalogs digital products, and with this month's API release, we will be importing more digital products than we have previously. We modified the API software so that you don't have to change your queries to get these new products.

Subsets

Rather than send queries repeatedly for every last detail, many of you download our archives daily and use them for looking up standard product info. (We do hope you are doing real-time queries for price and availability information, of course.) Archives work well, except you might not need all the information on all of our products. If you're selling video games, you probably don’t need to know a particular refrigerator's capacity. In case you have to find information on products your customers’ bought a while ago, but that we no longer sell, you can specify active=false, but chances are you don’t need inactive product information on a regular basis. Up to now, even if you needed info on just a certain type of product, you had to download the complete product archives, – all types, active and inactive – which are quite large. With this release, we introduce subsets, which can be thought of as "focused archives". You can download one or more of our subset files to get just those products you need.

Example request

http://api.remix.bestbuy.com/v1/subsets/[SF].[FMT].zip?apiKey=yourAPIKey

[FMT] is one of {xml or json}

[SF] is the subset file name – one of the following:

  • productsActive - includes marketplace, digital, preowned; excludes BlackTie plans
  • productsInactive - all inactive products; includes marketplace, digital, preowned, BlackTie plans
  • productsMusic - active music
  • productsMovie - active movies
  • productsHardgood - active hardgoods; includes preowned; excludes marketplace
  • productsBundle - active bundles
  • productsGame - active games; includes marketplace and preowned
  • productsSoftware - active software; includes marketplace
  • productsBlackTie - active BlackTie and BuyBack plans
  • productsMarketplace - active marketplace products
  • productsDigital - active digital products

Example request

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

Subsets should be available each day by 9:00 am (Central Time).


2012 August (R12.5)

We know you're probably sweating through one of the hottest summers on record, so we've got some cool updates for you this month. Actually, one of the changes will help you during the upcoming holiday season, but you can use the others right away.

Pricing

While Best Buy always strives to have the lowest prices for the products we carry, we are sometimes restricted on what prices we can show. Why? Well, that's usually due to the agreements we have with our product manufacturers. Don't worry; we will be explaining this more in an upcoming report, but basically, there are times we cannot publicly display a product's actual selling price. You may have noticed that our website sometimes shows "See price in cart” where the price would normally be. It's kind of tough to do that in an API, so we are required to make changes to our pricing attributes.

How do you know if a product is subject to price-display restrictions? Up to now you might have noticed some products for which onSale=true, but dollarSavings=0.00, and salePrice=regularPrice. Confusing. Now we are giving you a new attribute, priceRestriction. Initially, priceRestriction will either have no value (the price is not restricted), or will be one of the following:

  • ICR - in-checkout rebate (actual selling price may not be shown until your customer is ready to check out)
  • MAP - minimum advertised price (actual selling price may not be shown until your customer puts the item in a cart)

Yes, this is a confusing topic, and we realize this doesn’t completely clear it up, but we will shortly release a report explaining price-display restrictions in more detail. For now, at least, you have the new attribute to look at!

Categories

To help organize the million or so products Best Buy sells, we put them into various categories. Today, we actually have over 4600 categories, in a hierarchical structure. That's a lot of categories, but some are used only part time, and some are old, but have not yet been removed from our category tree. Our back-end systems now have category-start and category-end dates, but to make thing simpler, we will just make categories active or inactive, much as we do for products. By default, inactive categories will not be displayed. That will bring down the number of categories dramatically, making it easier for you to find products. If, for some reason, you want to see inactive categories, simply include active=*.


2012 July (R12.4)

This month’s updates feature some under-the-covers updates, performance enhancements (reduced latency), and two new attributes.

Under the Covers

These enhancements aren't as flashy as some of the others, but they're all part of our commitment to keeping BBYOpen up to date, and focused on your needs. Recently, Best Buy announced we're closing some of our stores. We made sure these stores don't get returned if you're looking for stores in a given area.

We also updated the logic that sets the values in the Boolean (true/false) attributes onlineAvailability and inStoreAvailability. Some folks were confused if, say, onlineAvailability was true (indicating that you could order the product on line), but onlineAvailabilityText showed that the product could not be shipped right now (maybe it was backordered). We looked at our messages and mapping, listened to your comments, and tried to make the attributes clearer.

Reduced latency

You might remember our major release last February, where we changed the way we assemble the product data exposed through the API. Before February, we updated prices throughout the day, but had a once-daily feed for most other product data. With February’s release, we were able to update all product data four times a day. Well, we thought we could do better, and we have! With other improvements we’ve made along the line, the BBYOpen API now has fresh product data every 15 minutes. Most products don’t change that frequently, but if something happens, you’ll see the new info much sooner.

New attribute

We are adding a new attribute: reviews. Did you ever wonder why a product you love got some very low ratings? Well, anyone can review any product. Maybe someone who reviewed your favorite product didn’t really understand how to use it. When evaluating a review, it helps to know something about the reviewer. Now you can find out more about who wrote a review by looking at aboutMe.customerType. Reviewers can describe themselves, and we are now exposing that information within each review.

Here’s an example of two reviews for a new router

Example

#request:
http://api.remix.bestbuy.com/v1/reviews(sku=2204196)?&apiKey=yourAPIKey

#response:
<reviews currentPage="1" totalPages="91" from="1" to="10" total="910" queryTime="0.004" totalTime="0.010" canonicalUrl="/v1/reviews(sku=2204196)?apiKey=yourAPIKey" partial="false"> <review> <id>23771685</id> <sku>2204196</sku> <reviewer> <name>cowboy</name> </reviewer> <aboutMe/> <rating>3.0</rating> <title>too small for ears</title> <comment>I believe overall this is a good product. My issue is that the cushions are not large enough to cover the ears</comment> <submissionTime>2014-04-12T17:32:51</submissionTime> </review>

This router has an average rating of 3.0 – not so great. You notice that one user loved the router, and one didn’t like it. By looking at aboutMe.customerType, you see that the positive review came from a professional, who is self-described as a “Network Guru”. The negative review is from a “Casual User”. Who’s right? Quite possibly, both! If this is a high-function router, it might be too complicated for a new user, but may work very well for a more experienced one. Both reviews may be valid. With the new attribute, you can determine which review better fits yourself.

OK, we don’t have an attribute to state how accurate someone’s self-defined type is, but the new attribute gives you some additional information to help you get more out of your reviews.

New mobile phone attributes

One of our more confusing attributes (or so you’ve told us) is planPrice. Obviously, it’s the price of a plan (some plan; which plan?), right? Well, no. planPrice is actually the price of a mobile phone, when purchased with a new two-year plan. Obvious! Well, we will now also be displaying phone prices when purchased with two-year upgrade (not new) plans. We need a new attribute for that price, so we’ve taken the opportunity to fix the existing attribute name at the same time. With this release, we will now have priceWithPlan.newTwoYearPlan and priceWithPlan.upgradeTwoYearPlan.

This makes more sense when you see the return data

Example

#request:
http://api.remix.bestbuy.com/v1/products/2210015.xml?apiKey=yourAPIKey&show=sku,name,regularPrice,priceWithPlan

#response:
<product> <sku>2210015</sku> <name>Amazon - Kindle Fire HDX - 16GB (AT&amp;T) - Black</name> <regularPrice>329.99</regularPrice> <priceWithPlan> <newTwoYearPlan>199.99</newTwoYearPlan> <upgradeTwoYearPlan/> <newTwoYearPlanSalePrice>199.99</newTwoYearPlanSalePrice> <upgradeTwoYearPlanSalePrice/> <newTwoYearPlanRegularPrice>299.99</newTwoYearPlanRegularPrice> <upgradeTwoYearPlanRegularPrice/> </priceWithPlan> </product>

Much more descriptive! “But wait!”, we hear you say, “I’ve already got planPrice coded in my application!” No problem. We are deprecating planPrice, but won’t actually remove it from the API until next January, so you have ample time to change your app. In the meantime, planPrice will be the same as priceWithPlan.newTwoYearPlan


2012 May (R12.3)

This release has a number of under-the-cover changes that make the API better and more efficient. We also did a lot of work on handling displayed-price rules. Displayed-price rules? Sometimes, manufacturers have rules and restrictions about how we display prices for some of their products. Rather than passing all of this along to you and explaining what to do with it, we have done everything on our end. You can be assured that the prices we expose through the API are valid for display on your site, and meet any conditions the manufacturer may have put in place.

We also made a couple of changes dealing with archives:

We have a job that builds the archives daily (obviously!). If we were running a lot of other jobs on a particular day, or those jobs were updating an unusually large number of products, the archive build might end a little later than usual. If you downloaded the archives at a fixed time each day, it’s possible that you might, very rarely, have missed the daily build, and gotten “yesterday’s” archives. We have now set up a dedicated archives job queue, so that archive builds are not dependent on other jobs that might be running. The archives will therefore be generated at a more consistent time, approximately 9:00 am, Central Time.


2012 April (R12.2)

Ever heard of an invisible release? Well, this one might qualify! This release actually includes 19 updates, but all of them are operational – they make the API work more efficiently, improve the way we import data, fix a sorting issue with one specific attribute, etc. You might find the API working a bit faster, but you won’t see any external attribute or function changes this month.

We’ll try to make our next release a bit more exciting!


2012 February (R12.1)

This month’s release is like an iceberg (with one major exception). There’s a lot to it, but most of it is hidden (‘though probably not underwater). If you want to stretch the analogy (to the breaking point?), you might also say that we’ve made some pretty “cool” changes. The exception? You don’t have to steer clear of it, because it won’t make you sink.

Product data latency reduction

One of the biggest changes we made involves how we assemble the product data exposed through the API. We currently update prices every five minutes, and won’t be changing that. Product details don’t change much, however. If a TV has 50” screen today, it will probably have a 50” screen tomorrow (unless your kids knock it off its stand and it breaks into many smaller screens, in which case you’ll be glad you got an accidental protection plan, but that’s another story). Up to now, we’ve taken a daily snapshot of all product details – which come from many different sources –assembled them and sent them off site for processing, then compiled and processed the changes, before sending them to our API servers.

While screen size is fairly constant, some other details, such as special offers or availability do change, and we want to make sure we get you the most updated information possible. Instead of taking a full snapshot once a day, we will be capturing changes, every six hours. We will also do the processing in-house, so information should hit our servers less than 30 minutes after we capture it. Not only do you get new data updates four times a day, that data will be fresher.

What do you have to do to take advantage of this fresher data? Not a thing! As mentioned, this is a major change, but is internal – the interface doesn’t change

Attribute removal

There are some changes in this release that affect your queries. As we’ve told you in prior communications, we're retiring a number of attributes that you rarely used. As a reminder, here are the attributes you won't be seeing again:

  • albumVersion - no longer maintained in upstream data source
  • appleConnectivity - already replaced by various iPod attributes: iPodConnection, iPodDock,iPodReady
  • brand - Canada-only product attribute
  • cellPhoneBrand - no longer maintained in upstream data source; can be replaced by manufacturer in most cases
  • copyright – no longer populated
  • napsterAlbumId - not valid since Napster sale
  • nationalFeatured - not used since summer 2011
  • navigability - no longer maintained in upstream data preferredRelatedBestBuySku;
  • preferredRelatedNapsterSku - not valid since Napster sale
  • printOnly - name and meaning confusing; will be replaced with a future attribute with better clarity
  • related.active, related.sku, related.type, related.title - no longer actively maintained in upstream data source
  • saleEndDate - no longer maintained in upstream data source
  • savings - Canada-only product attribute
  • skuSourceIndicator – used internally to identify marketplace products; was not exposed
  • smartPhone - no longer maintained in upstream data source
  • softwareMultiplayerInternet, softwareOnlinePlay, softwareNumberOfPlayers - being consolidated; replaced by new attributes onlinePlay and numberOfPlayers
  • softwareReleaseDate - no longer maintained in upstream data source - replaced by releaseDate
  • tinyMobileUrl - not used since spring 2011 - replaced by mobileUrl

New attributes

If you read the last section carefully, you saw that two of our new attributes replaced some of the retirees.

  • onlinePlay - A Boolean (true/false) attribute indicating a game that can be played on line. This attribute applies to Games and Software.
  • numberOfPlayers - Indicates the number of players (obviously!) for the Game or Software product.

These will be joined by two brand-new attributes:

  • collection - Indicates the collection to which the product is assigned. The collection? Next time you visit bestbuy.com, look in the Narrow Your Results box on the left side of the page. On most pages, you will see collections, such as In-Store & Online, Magnolia Home Theater, Microsoft Premium Collection, Refurbished, and Small Business. More collections will be added (and some will be taken away). This attribute is part of our ongoing effort to attain greater similarity between our API and bestbuy.com.
  • bestSellingRank - This is a weighted average of legacy attributes salesRankShortTerm, salesRankMediumTerm, and salesRankLongTerm. We're keeping the legacy attributes because you use them a lot, and because they can indicate sales trends.

Updated attributes

Two attributes are getting a makeover. While these attributes have been around for a while, we're updating them to better match the information on bestbuy.com.

  • albumLabel - Obviously, indicates the album label for music products
  • genre - Applies to both Music and Movies. One major change, especially for albums and movies that are assigned multiple genres, is that the attribute will now contain a list of genres. For example, for the movie 'Neath the Brooklyn Bridge, genre is "Childrens and Family, Comedy, Sci-Fi, Action and Adventure, Drama".

We hope these changes help. Please let us know if you have any comments, or if you find any issues you’d like us to know about.


2011 June (R11.2)

June is busting out all over, and so is the Products API! There are only four new attributes (for shipping costs), but we’re also making your life (well, at least your work life) easier by improving the way the API works. This month we give you access to new shipping info, better floating-point handling, more consistent searching, and more up-to-the-minute trade-in prices (along with a few puzzles for your summer enjoyment). Here’s a summary of what’s new and improved:

  • Shipping costs – New attributes that return shipping costs
  • Floating-point enhancement – Improved floating point searching, and a new data type
  • Search improvement – Easier and more consistent searching
  • Game trade-in values – Reduced latency, for more current and more accurate prices

Shipping Costs

Congratulations! You’ve just made another sale, and your customer wants to get the product. Of course,digital products are simply downloaded, and some other products may be picked up in a store, but usually products will be shipped to the customer’s home. You may have used shippingCost in the past, but that represented only one of the possible shipping charges. With this release, we are introducing four new shipping cost attributes:

Attribute NameDefinitionExampleType
shipping.groundGround shipping charge (standard)14.99dollar
shipping.secondDaySecond-day shipping charge (expedited)26.99dollar
shipping.nextDayNext-day shipping charge (express)49.99dollar
shipping.vendorDeliverySpecial home-delivery shipping charge134.9dollar

*“What in the world is a dollar data type?”. That’s a new data type, and is part of our Floating-point enhancement (discussed below)

Puzzle 1: Which of these new attributes is not like the others? That would be shipping.vendorDelivery(well, OK, it’s not completely different). Some products, such as home appliances, large televisions, and fitness equipment, cannot be shipped by standard couriers; they have to be delivered individually. If you see a value for shipping.vendorDelivery, you should not see any of the others (and vice versa).

Puzzle 2: When is shipping cost not shipping cost? When we offer free shipping, of course! “Free shipping” is a special offer, but is valid only in certain areas. Therefore, when free shipping is available, it does not change the shipping.x values. If you want to present all possible charges, you should search for this offer freeShipping=true. See Scenario 2, below, for an example of why this is helpful. So what about good old shippingCost that you already have in your queries? Don’t worry; we’re not getting rid of it. shippingCost will now be the lowest of the shipping.x costs. Usually, that will be shipping.ground; if the item is vendor-delivered, it will be shipping.vendorDelivery. shippingCost is helpful as an estimated shipping charge to help you present a realistic “total price”. The customer can change this from the cart.

Scenario 1:

Your customer just heard a song by Eddie Vedder, and was hooked. Now he wants Eddie’s most popular CD (as measured by sales in the last week), and wants to know just how much it will cost to get the CD in house as quickly as possible.

Example

#request:
http://api.remix.bestbuy.com/v1/products(artistName=eddie%20vedder)?show=sku,name,artistName,regularPrice,shippingCost,shipping,freeShipping,salesRankMediumTerm&sort=salesRankMediumTerm.asc&apiKey=yourAPIKey

#response:
<products currentPage="1" totalPages="1" from="1" to="5" total="5" queryTime="0.546" totalTime="0.557" canonicalUrl="/v1/products(artistName=&quot;eddie vedder&quot;)?show=sku,name,artistName,regularPrice,shippingCost,shipping,freeShipping,salesRankMediumTerm&amp;sort=salesRankMediumTerm&amp;apiKey=yourAPIKey" partial="false"> <product> <sku>2619361</sku> <name>Ukulele Songs - CD</name> <artistName>Eddie Vedder</artistName> <regularPrice>13.99</regularPrice> <shippingCost>1.99</shippingCost> <shipping> <ground>1.99</ground> <secondDay>8.99</secondDay> <nextDay>11.99</nextDay> <vendorDelivery/> </shipping> <freeShipping>false</freeShipping> <salesRankMediumTerm>47984</salesRankMediumTerm> </product>

Query Notes

  • artistName=eddie vedder – Remember that the text part of the search parameter is not case dependent.
  • show=shippingCost – The lowest of the shipping values below.
  • shipping – This is the “parent” attribute for shipping.ground, shipping.secondDay, shipping.nextDay,and shipping.vendorDelivery.

Specifying the parent attribute in the show= part of the query displays all of the children. You cannot search on a parent attribute (e.g., shipping<20 will generate an error).

  • freeShipping – Check to see if this product qualifies for free shipping.
  • sort=salesRankMediumTerm.asc – Sort the results in order of the most Best Buy sales in the past week (lower number = higher sales). From the results below, you can see that “Ukulele Songs” was Best Buy’s 153rd best selling product for the week before the query was run. (Not just music, mind you, but 153rd overall!)

Scenario 2:

Your customer has been looking for a treadmill, and has narrowed her choices to the Pro-Form 705 CST, and the Pro-Form Power 995. Knowing these are big, heavy products, she wants to make sure she knows how much these treadmills will really cost, including delivery.

Example

#request:
http://api.remix.bestbuy.com/v1/products(sku%20in(16306454,6664013))?show=sku,name,regularPrice,shippingCost,shipping,freeShipping&apiKey=yourAPIKey

#response:
<products currentPage="1" totalPages="1" from="1" to="2" total="2" queryTime="0.003" totalTime="0.010" canonicalUrl="/v1/products(sku in(16306454,6664013))?show=sku,name,regularPrice,shippingCost,shipping,freeShipping&amp;apiKey=yourAPIKey" partial="false"> <product> <sku>16306454</sku> <name>! (Bonus Track) (Japan) - CD</name> <regularPrice>45.99</regularPrice> <shippingCost>0.00</shippingCost> <shipping> <ground>0.00</ground> <secondDay>8.99</secondDay> <nextDay>11.99</nextDay> <vendorDelivery/> </shipping> <freeShipping>true</freeShipping> </product> <product> <sku>6664013</sku> <name>!!! - CD</name> <regularPrice>12.99</regularPrice> <shippingCost>1.99</shippingCost> <shipping> <ground>1.99</ground> <secondDay>8.99</secondDay> <nextDay>11.99</nextDay> <vendorDelivery/> </shipping> <freeShipping>false</freeShipping> </product> </products>

Query Notes

  • sku in(1293146,2084074) – These are the skus for the two treadmills mentioned above.
  • show=shippingCost – Included here as an example. Because these treadmills have vendor delivery, shipping.vendorDeliveryshould be the only shipping cost listed. You wouldn’t really need to include shippingCost in your query.

As mentioned, shippingCost, shipping.vendorDelivery, because that is the only shipping option for these treadmills. Also, when you calculate the “total” cost of each treadmill, you’ll find that the costs are actually only a penny apart, because the more expensive treadmill has free shipping. Don’t forget to check!

Floating-point enhancement

This month’s release includes two floating-point enhancements: better searching, and a new data type.

First, you may have encountered a surprising, er, feature, of searching for prices ending in zero. If your query included something like dollarSavings>=10.0, or shippingCost<42.50, for example, the API would return an error. No more!

Second, as mentioned above, we are announcing a new data type, dollar. While dollar functions like a floating-point number, it is designed to return two decimal places, even if the last digit is “0”. As you might guess, dollar will be used for price attributes. Previously, salePrice might have returned 30.0. Now, it will return 30.00. Not the most earth shattering change, perhaps, but we’re always looking for ways to make your life a little easier!

By the way, other floating-point fields, such as screenSizeIn and capacityCuFt are still float (any number of decimal places is acceptable).

Search Improvement

If you’re a Joe Friday type that wants “Just the facts, ma’am,” here they are: To see if an attribute has a value, specify attribute=*. To find products that do not have a specific attribute value, use attribute!=*. If you want to know a bit more, read on.

Puzzle 3: What do Joe Friday and the Products API have in common? (Answer below) Usually, when querying on an attribute, you’re looking for a specific value. For example, to make sure a refrigerator fits under 70-inch high built-in cabinets, you might include heightToTopOfRefrigeratorIn<70. Sometimes, though, you might be interested in just knowing if the attribute has a value at all. Product descriptions come from manufacturers, and manufacturers differ in what measurements they supply. For example, we currently have 966 refrigerators with values for heightToTopOfRefrigeratorIn. We have only 725 refrigerators that specify heightToTopOfDoorHingeIn (and 718 that specify both).

Let’s say your site caters to contractors, and they’re interested only in refrigerators that specify both heights. (They don’t care what the heights are, but they don’t want to be bothered with incompletely-specified fridges.) You want to write a query that returns products that have values for both attributes.

Because both of these attributes are floating-point numbers, before this release you would have had to specify heightToTopOfRefrigeratorIn>=0&heightToTopOfDoorHingeIn>=0. If you were searching for string attributes with values, you would have used stringAttribute=*. Integers? integerAttribute>=0. Longs, like sku, would be longAttribute>=1. Boolean and date attributes were really tough:booleanAttribute in(true,false) and dateAttribute>1910-01-01. Real easy to remember, huh?

Well, with this release we’ve simplified things. To see if an attribute has a value, you need use onlyattribute=*. That’s right; this now works for all attribute types. Of course, if you want to find products that do not have a specific attribute value, use attribute!=*. Oh, yes, your contractor query? heightToTopOfRefrigeratorIn=*&heightToTopOfDoorHingeIn=*

(Puzzle 3 answer: The Products API is accessed over the World Wide Web. Joe Friday was portrayed by Jack Webb. Hey, I didn’t say it was a great puzzle!)

Game Trade-in Values

This is really an internal change: we’ve changed the way we pull in game trade-in values. So, what does this mean for you and your customers? As we reduce latency, prices returned for tradeInValue will be more current and more accurate. No, you don’t have to do anything different; we just thought you might like to know!


2011 May (R11.1)

The April and May releases feature three new Products API attributes:

  • tradeInValue – Amount Best Buy pays on product trade in. It pays to recycle, especially if your customers are recycling games they don’t want to play any more. Best Buy will buy back certain games from customers; tradeInValue shows how much they will get.
  • preowned – “Used” products Your customers can also save money by buying games other folks have traded in. Search for preowned to find “used” games, which cost less than their new counterparts.
  • digital – Products available via download (not available in stores)

You don’t have to go to a store to get some games, subscriptions, or services; products with the digital attribute set are available by download.

Attribute: tradeInValue

Query Scenario Your customers want to buy PlayStation games that they can sell back when done playing. You generate the following query, which will find all PlayStation games that have trade-in values, sorted to show the highest trade-in values first

#request:
http://api.remix.bestbuy.com/v1/products(name=playstation*&tradeInValue%3E0)?show=sku,name,tradeInValue&sort=tradeInValue.desc&apiKey=yourAPIKey

#response:
<products currentPage="1" totalPages="41" from="1" to="10" total="406" queryTime="0.011" totalTime="0.031" canonicalUrl="/v1/products(name=&quot;playstation*&quot;&amp;tradeInValue&gt;0)?show=sku,name,tradeInValue&amp;sort=tradeInValue.desc&amp;apiKey=yourAPIKey" partial="false"> <product> <sku>8677151</sku> <name>Infamous: Second Son - PlayStation 4</name> <tradeInValue>38.00</tradeInValue> </product> <product> <sku>5027006</sku> <name>2014 FIFA World Cup Brazil - PlayStation 3</name> <tradeInValue>34.00</tradeInValue> </product> <product> <sku>9503119</sku> <name>Assassin&apos;s Creed IV: Black Flag - PlayStation 4</name> <tradeInValue>32.00</tradeInValue> </product> <product> <sku>3852053</sku> <name>Dynasty Warriors 8: Xtreme Legends Complete Edition - PlayStation 4</name> <tradeInValue>32.00</tradeInValue> </product>

Query Notes

  • name=playstation* – Find all products with “playstation” in the name field. This search is case insensitive. Note that this syntax will find “playstation” anywhere in the name field. You cannot use a wildcard character at the beginning of the search string; name=*playstation* will generate an error (400 Bad Request).
  • tradeInValue>0 – Find all products that have trade-in values.
  • tradeInValue>=2.5 - would return products with trade-in values of $2.50 or more.
  • sort=tradeInValue.desc – Sort results by trade-in value, in descending order (highest values first).

Attribute: preowned

Query Scenario Your customers want to play FIFA games on their PlayStations, but they want to save money by buying games others have used and turned in. To show them how much they save by buying pre-owned games, you generate a query that returns all FIFA PlayStation games, both new and used, and sorts the list to pair the new and used versions. (You still have to extract the prices, but that’s for your app, not for the query!)

#request:
http://api.remix.bestbuy.com/v1/products(name=playstation*&name=fifa*&preowned%20in(true,false))?show=sku,name,regularPrice,preowned&sort=name.asc&apiKey=yourAPIKey

#response:
<products currentPage="1" totalPages="2" from="1" to="10" total="20" queryTime="0.205" totalTime="0.226" canonicalUrl="/v1/products(name=&quot;playstation*&quot;&amp;name=&quot;fifa*&quot;&amp;preowned in(true,false))?show=sku,name,regularPrice,preowned&amp;apiKey=yourAPIKey" partial="false"> <product> <sku>9800886</sku> <name>2010 FIFA World Cup: South Africa - PlayStation 3</name> <regularPrice>39.99</regularPrice> <preowned>false</preowned> </product> <product> <sku>1577573</sku> <name>2010 FIFA World Cup: South Africa — PRE-OWNED - PlayStation 3</name> <regularPrice>4.99</regularPrice> <preowned>true</preowned> </product>

Query Notes

  • name=playstation*&name=fifa* – Find all products with both “playstation” and “fifa” in the name field.
  • preowned%20in(true,false) or preowned in(true,false) – OK, this is tricky! Because preowned is a filtered attribute, if you leave it out of your query you will not see any pre-owned products. For example, name=playstation*&name=fifa* will return new products only. Specifying name=playstation*&name=fifa*&preowned=true will show only pre-owned products. In this scenario, however, you want all FIFA PlayStation games (pre-owned and new) so you can compare prices. To do that, you must request both values (true and false). The easiest way to do this is preowned in(true,false).
  • sort=name.asc – Because of the ASCII values in the name, this will show pre-owned products before new products; pre-owned products include &#151; PRE-OWNED between the game name and platform. (You do know that &#151; is an em-dash, right? (Neither did I.)) Note that this isn’t a perfect solution, because you will get some new products that don’t have pre-owned versions, but, hey, we’ve got to leave something for you to do!

Attribute: digital

Query Scenario Your customers want new PlayStation games they can get very quickly, without having to go to a store. You generate a query showing downloadable PlayStation games released this year:

#request:
http://api.remix.bestbuy.com/v1/products(name=playstation*&digital=true&startDate%3E=2011-01-01)?show=sku,name,digital,inStoreAvailabilityText,onlineAvailabilityText,startDate&apiKey=yourAPIKey

#response:
<products currentPage="1" totalPages="3" from="1" to="10" total="28" queryTime="0.296" totalTime="0.319" canonicalUrl="/v1/products(name=&quot;playstation*&quot;&amp;digital=true&amp;startDate&gt;=2011-01-01)?show=sku,name,digital,inStoreAvailabilityText,onlineAvailabilityText,startDate&amp;apiKey=yourAPIKey" partial="false"> <product> <sku>1000004251</sku> <name>$10 PlayStation Promo Code - PlayStation [Digital Download Add-On]</name> <digital>true</digital> <inStoreAvailabilityText/> <onlineAvailabilityText>Backordered: Expected to ship within 1-2 weeks.</onlineAvailabilityText> <startDate>2013-10-23</startDate> </product> <product> <sku>1000004121</sku> <name>1 Month Playstation Plus Bonus Code - PS3 [Digital Download Add-On]</name> <digital>true</digital> <inStoreAvailabilityText/> <onlineAvailabilityText>Backordered: Expected to ship within 1-2 weeks.</onlineAvailabilityText> <startDate>2013-09-01</startDate> </product>

Query Notes

  • name=playstation* – Find all products with “playstation” in the name field.
  • digital=true – Show downloadable products only.
  • startDate>=2011-01-01 – Find products released on or after January 1, 2011.
Best Buy logo

We do not support your browser. Neither does Microsoft.

We're glad that you're excited about Best Buy's APIs. However, you're using a browser that's too old to view our new developer site. We encourage you to switch to a newer browser, preferably a recent version of Chrome, Firefox, or Internet Explorer.