API: Search API

All API calls require the key parameter. That is not shown in the below examples.

Overview

/Search?term=<SEARCH_TERM> or /Search/term/<SEARCH_TERM>

  • Returns a list of styles that matches the search term. A search "term" can be keywords, a Zappos SKU or even a UPC.
  • What is a "style"? Perhaps this is best illustrated by: Example of a style
  • Hence, when you search for "UGG CLASSIC SHORT", you will get all 5 styles returned in the search results.

/Search?term=boots

Response:

{
"statusCode": "200",
"results":
[    
 { 
   "styleId": "556677", 
   "productId": "123456", 
   "brandName": "Ugg", 
   "productName": "Classic Tall", 
   "thumbnailImageUrl": "http://www.zappos.com/images/image.jpg", 
   "originalPrice": "$198.00", 
   "price": "$198.00", 
   "percentOff": "19%", 
   "productUrl": "http://www.zappos.com/product/101183/color/381" 
 },
 { 
   "styleId": "556678", 
   "productId": "123457", 
   "brandName": "Ugg", 
   "productName": "Classic Short", 
   "thumbnailImageUrl": "http://www.zappos.com/images/image.jpg",  
   "originalPrice": "$158.00", 
   "price": "$140.00", 
   "percentOff": "19%", 
   "productUrl": "http://www.zappos.com/product/101183/color/381" 
 },
 { 
   "styleId": "556679", 
   "productId": "234567", 
   "brandName": "Frye", 
   "productName": "Engineer 12R W", 
   "thumbnailImageUrl": "http://www.zappos.com/images/image.jpg", 
   "originalPrice": "$300.00", 
   "price": "$300.00", 
   "percentOff": "19%", 
   "productUrl": "http://www.zappos.com/product/101183/color/381" 
 }
]
}

Includes

Bold fields are returned by default (and only if their parent fields are included). To include any other search fields, you will need to include them in the includes parameter: e.g. /Search/term/boots?includes=["description"]

  • results
    • styleId
    • productId
    • colorId
    • brandName
    • productName
    • productUrl
    • thumbnailImageUrl
    • price
    • originalPrice
    • percentOff
    • description
    • videoUrl
    • videoFileName
    • videoUploadedDate
    • productRating
    • brandId
    • categoryFacet
    • heelHeight
    • subCategoryFacet
    • txAttrFacet_Gender (yes, dumb name to pull gender)
  • currentResultCount: the number of results returned in this request
  • totalResultCount: the total number of results found
  • limit: the max number of search results to return for this request
  • currentPage: the current page returned
  • pageCount: the total number of result pages
  • filters
  • facets
    • facetField
    • facetFieldDisplayName
    • values
    • name
    • count

Excludes

You can also exclude elements from coming back in the response as well. You may want to use this to not return the results or not bother returning certain fields you know you won't use. The syntax is the same as includes (e.g. /Search/term/boots?excludes=["results","brandName"])

Sorting your results

/Search/term/<SEARCH_TERM>?sort={"<FIELD>":"<ORDER>"}

  • The sort parameter can be used to order your results (asc or desc)
  • Valid sort fields are:
    • price
    • goLiveDate - newest product
    • productPopularity - most popular
    • recentSales - popularity in a smaller time window
    • brandNameFacet - sort on brand name

e.g. /Search/term/boots?sort={"price":"desc"}

Limiting your results

/Search/term/<SEARCH_TERM>?limit=<LIMIT>

  • Retrieve paginated results by using the limit and page fields
  • By default, the limit on search results will be set to 10
    • limit: The number of results to return
    • NOTE: There is a maximum of 100 results per call

Pagination

/Search/term/<SEARCH_TERM>?limit=<LIMIT>&page=<PAGE_NUMBER>

  • Retrieve paginated results by using the limit and page fields
    • limit: The number of results to return
    • page: The page number to return (if not specified, will default to the first page)

Facets

Facets are a way of grouping your results. This is like a GROUP BY clause in sql.

Standard Facet Groupings

If no facet groupings are specified, then by default the following groupings will be returned:

  • Product Type
  • Size
  • Width
  • Color
  • Price
  • Brand

/Search/term/boots?includes=["facets"]

{
   "statusCode": "200",
   "facets": 
   [
   { 
      "facetField": "Product Type",
      "facetFieldDisplayName": "productTypeFacet",
      "values": 
    [
      {
        "name": "Shoes", 
        "count": "25"
      },
      {
       "name": "Accessories", 
       "count": "15"
     },
     {
       "name": "Sporting Goods", 
       "count": "6"
     },
     {
       "name": "Baby Shop", 
       "count": "4"
     }
    ]
   }, 
  { 
   "facetField": "size",
   "facetFieldDisplayName": "Size",
   "values": 
     [
       {
       "name": "7.5", 
       "count": "14"
       },
       {
        "name": "8", 
        "count": "13"
        },
       {
         "name": "9", 
         "count": "12"
        },
       {
         "name": "11", 
         "count": "11"
       }
     ]
    }, 
 { 
   "facetField": "priceFacet",
   "facetFieldDisplayName": "price",
   "values": 
   [
     {
       "name": "$50.00 and Under", 
       "count": "40"
     },
     {
       "name": "$100.00 and Under", 
       "count": "10"
     }
   ]
 },
 { 
   "facetField": "brandNameFacet",
   "facetFieldDisplayName": "Brand",
   "values": 
   [
     {
       "name": "Ugg", 
       "count": "25"
     },
     {
       "name": "Frye", 
       "count": "25"
     }
   ]
 }
 ],
  "results":
  [
   ....    
   ]
  }

Customized Facet Groupings

You can also specify which facet groupings you would like back by using the facets parameter. * NOTE: The inputs for the facets must be a '''facetField''', NOT a facetFieldDisplayName

/Search/term/boots?includes=["facets"]&facets=["productTypeFacet","size"]

{
 "statusCode": "200",
 "facets": 
 [
   { 
     "facetField": "Product Type",
     "facetFieldDisplayName": "productTypeFacet",
     "values": 
     [
     {
       "name": "Shoes", 
       "count": "25"
     },
     {
       "name": "Accessories", 
       "count": "15"
     }
   ]
   }, 
   { 
     "facetField": "size",
     "facetFieldDisplayName": "Size",
     "values": 
     [
       {
       "name": "S", 
       "count": "30"
       },
       {
         "name": "M", 
         "count": "10"
       }
     ]
   }
 ],
  "results":
   [
    ....    
  ]
  }

Sorting Facets

By default, we return the facets sorted in the same order as it is on our www.zappos.com website - for example, "productTypeFacet" is returned by count desc, while "size" is returned alphabetically asc. However, you can override these default sorts by setting the "facetSort" parameter:

/Search/term/boots?includes=["facets"]&facets=["productTypeFacet","size"]&facetSort=<FACET_SORT>

facetSort values:

  • name - alphabetically, ascending
  • count - result count, descending

Filters

Filters are a way of narrowing down your results. This is like a WHERE clause in sql.

/Search?term=&filters={"<FACET_FIELD>":["<FACET_VALUE>"]}

You can filter your results by choosing a particular facet value to narrow down your result set.

  • NOTE: For each value in a filter, the results are OR-ed together; across filters, the results are AND-ed together
  • NOTE2: To filter results using "IS NOT EQUALS" logic, include a "-" before the facet field.

Examples:

  • /Search?term=boots&filters={"colorFacet":["Blue"]}
    • Narrows your result set to only have items that ARE blue
  • /Search?term=boots&filters={"-colorFacet":["Blue"]}
    • Narrows your result set to only have items that AREN'T blue
  • /Search?term=boots&filters={"colorFacet":["Blue"],"size":["13"]}
    • Narrows your result set to only have items that are blue AND size 13
  • /Search?term=boots&filters={"colorFacet":["Blue","Black"],"size":["10","11"]}
    • Narrows your result set to only have items that are (blue OR black) AND (size 10 OR 11).
    • Your results will be in one of the following subsets
      • blue & 10
      • blue & 11
      • black & 10
      • black & 11

List All Available Facet Fields

/Search?list=facetFields&type=facetable

{
 "statusCode": "200",
 "facetFields":  
 [
       "attrFacet_Accessories",
       "attrFacet_Accessory_Materials",
       "attrFacet_Accessory_Prints",
       "attrFacet_Appliance_Type",
       "brand",
       "brandFirstLetter",
       "brandId",
       ...
 ]
}

You can limit this result set by including a regex filter expression

/Search?list=facetFields&filterExpression=

Ex: /Search?list=facetFields&filterExpression=attrFacet_.*

List All Facet Values For a Facet Field

If you wanted to see all available facet values for a particular facet field, you could make a call that does a search on all available products (no "term" is specified) and groups the full result set by the "colorFacet":

/Search?term=&facets=["colorFacet"]&excludes=["results"]

 {
   "statusCode": "200",
   "facets":     
   [    
     {
        "facetField": "colorFacet",
        "facetFieldDisplayName": "Color",
        "facetValues":     
         [  
            {
               "facetValueName": "Black",
               "facetValueCount": "34,020"
            }
            ,
            {
               "facetValueName": "Brown",
               "facetValueCount": "16,702"
            }
            ,
            {
               "facetValueName": "White",
               "facetValueCount": "9,860"
            }
            ....
         ]
     }
   ]
 }

Commonly Used Facets

You can see we have a LOT of facets. We use them for a lot of internal reasons as well so that list has really piled up over time. But a few of the more common facets you might want to use (beside the standard ones) are:

  • onSale - you can return only onSale items
  • isNew - if true, returns items that have been put on the site in the last 14 days

e.g. Get only new, on sale items sorted by how new they are: http://api.zappos.com/Search?includes=["isNew","onSale"]&filters={"isNew":["true"],"onSale":["true"]}&sort={"goLiveDate":"desc"}

Drupal theme by Kiwi Themes.