API Documentation

ShopStyle — Wed, 08 Apr 2009 14:38:55 -0700

ShopStyle API Developer's Guide

Overview

Welcome to the Shopstyle developer portal! The ShopStyle API allows client applications to retrieve the underlying data for all the basic elements of the ShopStyle websites, including products, brands, retailers, categories and looks. For ease of development, the API is a REST-style web service, composed of simple HTTP GET requests. Data is returned to the client in either XML or JSON formats. The API is client language independent, and easy to use from PHP, Java, JavaScript or any other modern development context.

To use the ShopStyle API, you need to first sign up here to get your unique API key. Once you have this key you can start making the API calls described below.

Intended Audience

This document is intended for programmers who would like to develop a client application that will use the ShopStyle API. The client will need to know how to invoke an HTTP request with a particular URL, and process the body of the response as either XML or JSON.

How to Use the API

Here are the basic steps for using the API, regardless of the client language you are using:

Choose the method that returns the data your application needs. For example, the apiSearch method is used to get products that match a given category or brand.
Contruct a URL for that method with the appropriate host, method name and query parameters.
Invoke the URL as an HTTP GET.
When the HTTP response arrives, extract the required data elements from the response's body.

The rest of this document describes the details of constructing the right URL for each of the API's methods. The XML format of the reponses may be seen by clicking on the sample URLs shown for each method. The responses in JSON format contain identical information, just in a different language.

There is also a sample client application written in PHP.

ShopStyle API URLs

All ShopStyle API URLs have the following form:

http://api.shopstyle.com/action/METHOD_NAME?pid=YOUR_API_KEY&format=FORMAT&site=SITE&...

The METHOD_NAME is taken from the list of methods in the API shown below.

Common API Parameters

All methods in the API accept these parameters:

pid	Unique API_KEY string that is assinged to the caller. If you haven't signed up yet, sign up here to get your Shopstyle API key. This parameter must be present.
format	The format of the response. Supported values are: xml - The response is in XML format with UTF-8 encoding. This is the default if the parameter is absent. json - The response is in JSON format with UTF-8 encoding. jsonvar - The response is in JSON format with UTF-8 encoding, and includes a JavaScript assignment statement. This is useful when the API URL is the src attribute of a script tag, as the result is stored in a variable that can be used by subsequent JavaScript code. rss - The response is an RSS feed (beta).
site	Specifies the ShopStyle website to be searched or queried (optional; defaults to US fashion). www.shopstyle.com - provides access to US fashion & home products. www.shopstyle.co.uk - provides access to UK fashion products.

Product Query Parameters

Many of the methods listed in the next section accept this set of optional product query parameters, which are similar to query parameters used by the ShopStyle websites:

fts	Text search terms, as a user would enter in a Search: field.
cat	A product category. Only products within the category will be returned. The easiest way to find values for this parameter is to browse to a category on the ShopStyle website, and take the last element of the URL path, e.g., from http://www.shopstyle.com/browse/dresses use "dresses". Another way is to look at the categories of the products returned by the `apiSearch` or to look at the list of categories from `apiGetCategoryHistogram`.
fl	Specify one or more filters on the query for brand, retailer, price, discount, and/or size. Each filter value has an initial letter and a numeric id. The easiest way to construct a filter list is to do a search on ShopStyle, select one or more filter in the UI, and copy the resulting URL. To convert brand or retailer names to ids, use the `apiGetBrands` and `apiGetRetailers` calls. Here is a sample URL showing sale clothing from two brands and one retailer: http://www.shopstyle.com/browse/womens-clothes?fl=d0&fl=b3510&fl=b689&fl=r21 Filter prefixes are: b - brand r - retailer p - price d - sale s - size c - color
pdd	A "price drop date" expressed as a number of milliseconds since Jan 1, 1970. If present, limits the results to products whose price has dropped since the given date.
prodid	The id of a specific product to return. This may be specified multiple times to get many products in one response.

Methods of the API

apiSearch

This method returns a set of products that match a query, specified using the product query parameters and those listed bellow.

http://api.shopstyle.com/action/apiSearch?pid=YOUR_API_KEY&fts=red+dress&min=0&count=10

min	The index of the first product to return, or 0 (zero) if not specified. A client can use this to implement paging through large result sets.
count	The maximum number of results to return, or 20 if not specified. Requesting too many results may impact performance. Combine with the min parameter to implement paging.

Response

A list of Product objects. Each Product has an id, name, description, price, retailer, brandName, categories, images in Small/Medium/Large, and a url that forwards to the retailer's site.

Note: To view the response xml or json, copy an API link and paste it in your browser after replacing YOUR_API_KEY with the api key assigned to you.

apiGetCategoryHistogram

This method returns a list of categories and product counts that describe the results of a given product query. The query is specified using the product query parameters.

http://api.shopstyle.com/action/apiGetCategoryHistogram?pid=YOUR_API_KEY&fts=tunic

Response

A list of Category objects. Each Category has an id, name, and count of the number of query results in that category.

apiGetFilterHistogram

This method returns a list of filters and product counts that describe the results of a given product query. The query is specified using the product query parameters.

http://api.shopstyle.com/action/apiGetFilterHistogram?pid=YOUR_API_KEY&filterType=Retailer&fts=red+dress

filterType The type of filter data to return. Possible values are Brand, Retailer, Price, Discount and Size.

Response

A list of Filter objects of the given type. Each Filter has an id, name, and count of the number of results that apply to that filter.

apiGetBrands

This method returns a list of brands that have live products. Brands that have very few products will be omitted.

http://api.shopstyle.com/action/apiGetBrands?pid=YOUR_API_KEY

Response

A list of all Brands, with id, name, url, and synonyms of each.

apiGetRetailers

This method returns a list of retailers that have live products.

http://api.shopstyle.com/action/apiGetRetailers?pid=YOUR_API_KEY

Response

A list of all Retailers, with id, name, and url of each.

apiGetLook

This method returns information about a particular look and its products.

http://api.shopstyle.com/action/apiGetLook?pid=YOUR_API_KEY&look=548347

look The ID number of the look. An easy way to get a look's ID is to go to the stylebook page that contains the look at the ShopStyle website, and right-click on the button that you use to edit the look. From the popup menu, select "Copy Link", and paste that into any text editor. The "lookId" query parameter of that URL is the value to use for this API method.

Response

A single look, with title, description, a set of tags, and a list of products. The products have the fields listed above (see apiSearch).

apiGetLooks

This method returns information about looks that match different kinds of searches.

http://api.shopstyle.com/action/apiGetLooks?pid=YOUR_API_KEY&type=New&min=0&count=2

type	The type of search to perform. Supported values are: New - Recently created looks. TopRated - Recently created looks that are highly rated. Celebrities - Looks owned by celebrity users. Featured - Looks from featured stylebooks.
min	The index of the first product to return, or 0 (zero) if not specified. A client can use this to implement paging through large result sets.
count	The maximum number of results to return, or 20 if not specified. Combine with the min parameter to implement paging.

Response

A list of looks of the given type. Each look has the fields listed above (see apiGetLook).

apiGetStylebook

This method returns information about a particular user's stylebook, the looks within that stylebook, and the title and description associated with each look.

http://api.shopstyle.com/action/apiGetStylebook?pid=YOUR_API_KEY&handle=FabSugar

handle	The username of the stylebook owner.
min	The index of the first look to return, or 0 (zero) if not specified. A client can use this to implement paging through large result sets.
count	The maximum number of results to return, or 20 if not specified. Requesting too many results may impact performance. Combine with the min parameter to implement paging.

Response

A look id of the user's stylebook, the look id of each individual look within that stylebook, and the title and description associated with each look.

apiVisitRetailer

This method does not return a reponse of XML or JSON data like the other elements of the API. Instead, it forwards the user to the retailer's product page for a given product. It is the typical behavior to offer when the user clicks on a product. The apiSearch method returns URLs that call this method for each of the products it returns.

http://www.shopstyle.com/action/apiVisitRetailer?pid=YOUR_API_KEY&id=27500798

id The ID number of the product. An easy way to get a product's ID is to find the product somewhere in the ShopStyle UI, and right-click on the product image. From the popup menu, select "Copy Link", and paste that into any text editor. The "id" query parameter of that URL is the value to use for this API method.

apiGetTrends

This method returns the popular brands for a given category along with a sample product for the brand-category combination.

http://www.shopstyle.com/action/apiGetTrends?pid=YOUR_API_KEY&cat=109

cat	Category you want to restrict the popularity search for. This is an optional parameter. If category is not supplied, all the popular brands regardless of category will be returned.
products	To skip sample products, just pass value 0 for this attribute. This is an optional attribute as well.

Response

A list of trends in the given category. Each trend has a brand, category, url, and optionally the top-ranked product for each brand/category.

ShopStyle Developer Blog

API Documentation