BBYOpen API Data Dictionary

The BBYOpen APIs expose Best Buy products, stores, reviews, and categories. Approximately 400 attributes provide access to these items' details and specifications. The BBYOpen API Data Dictionary provides general attribute information, as well as links to lists of Products, Stores, Reviews, and Categories attributes. The lists themselves can be found on the API > Attributes pages, or can be accessed from the links below. Products API attributes are grouped into several tables. Click on a link below to see the appropriate data dictionary table.

General Attribute Information:

Attribute Types:

The Products API includes two types of attributes:

  • Common attributes - defined for all products of a given type. If common attribute for a given product has no value, a "null tag" is returned: <staticAttributeName/>
  • Product-specific attributes - return specific products' details. If a product-specific attribute for a given product has no value, no tag is returned.

Case:

  • Attribute names are case sensitive when used in queries. Use the data dictionary to ensure correct attribute name case.
  • If you use incorrect case (or incorrect spelling), the API will return a 400 Bad Request error, and will list the incorrect attributes. A list of valid attributes is included with the error message.
  • Attribute values are not case sensitive when used in queries. Each of the following will return the same results: manufacturer=Canon, manufacturer=canon, manufacturer=CANON.

Type:

The product attribute pages list the data type for each attribute. The data type reflects how the information is stored in the BBYOpen database, and used by the API. Information actually passed by HTML is, of course, a string.

Filtered Attributes:

Some attributes have values that are used by default in queries, even if you do not specifically use them. For example, preowned is a filtered attribute whose default value is “false”.  Not specifying preowned in your query is the same as specifying preowned=false.  If you want used products returned, you must specify preowned=true.  If you want used and new products returned, specify preowned=*.

If an attribute is filtered, its field is highlighted in the Data Dictionary, and its default value is shown.

Click on the link to see a list of filtered attributes.

Child Attributes:

In order to accommodate multiple attribute returns per item or to show relationships between attributes, some attributes have a parent-child relationship, of the form, parentAttribute.childAttribute.

  • Multiple returns examples:
    <accessories>
        <sku>6813362</sku>
        <sku>7191004</sku>
        <sku>7956599</sku>
      </accessories>
      <relatedProducts>
        <sku>1980124</sku>
        <sku>9778635</sku>
        <sku>1987075</sku>
      </relatedProducts>
    In this format, the attributes are specified: accessories.sku and relatedProducts.sku.

  • Relationship examples:
    <categoryPath>
        <category>
          <id>cat00000</id>
          <name>Best Buy</name>
        </category>
        <category>
          <id>abcat0400000</id>
          <name>Cameras & Camcorders</name>
        </category>
        <category>
          <id>abcat0401000</id>
          <name>Digital Cameras</name>
        </category>
        <category>
          <id>abcat0401005</id>
          <name>Digital SLR Cameras</name>
        </category>
        <category>
          <id>pcmcat180400050000</id>
          <name>DSLR Body & Lens</name>
        </category>
      </categoryPath>
    When relationships are shown, the attribute parent name is the top-level tag, and the child name is the lowest-level tag. The intermediate tag is used by XML for grouping, and is not accessible. In this example, the attributes are categoryPath.id and categoryPath.name.

When used in the request part of a query, both parent and child must be specified. Example: categoryPath.name="digital cameras". In the display part of a query (show=), specifying parent.child causes only the child attribute to be shown. Specifying just the parent name causes all children to be returned. For example, ...?show=shipping.ground returns:

  <shipping>
    <ground>20.34</ground>
  </shipping>

...?show=shipping returns

  <shipping>
    <ground>20.34</ground>
    <secondDay>41.04</secondDay>
    <nextDay>51.16</nextDay>
    <vendorDelivery/>
  </shipping>

Unlisted attributes:

In returned data, you may occasionally find an attribute that is not listed in the Data Dictionary.  Usually, this is a deprecated attribute that will be removed from the API at some point.  We are currently developing a deprecation policy, so you will be notified of attributes that will be removed, and when they will be removed.  Deprecated attributes might no longer have valid data, and should not be used.

Other attributes may be reserved for future use.  They may be supported by the API, but might not yet have any valid data.  Again, these attributes should not be used.

In general, we support only those attributes that are listed in the Data Dictionary.  If there is an attribute that you use regularly, but is not in the Data Dictionary, please let us know: http://www.bbyopen.com/contact.

Attribute Table Links:

Products API Attributes (click on one of the following table links)

Stores API Attributes

Reviews API Attributes

Categories API Attributes