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:
There is also a sample client application written in PHP.
- 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.
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:
|
| site | Specifies the ShopStyle website to be searched or queried (optional; defaults to US fashion).
|
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 http://www.shopstyle.com/browse/womens-clothes?fl=d0&fl=b3510&fl=b689&fl=r21 Filter prefixes are:
|
| 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. |
This method returns a set of products that match a query, specified using the product query parameters and those listed bellow.
| 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.
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.
| 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.
This method returns a list of brands that have live products. Brands that have very few products will be omitted.
Response
A list of all Brands, with id, name, url, and synonyms of each.
This method returns a list of retailers that have live products.
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.
| 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.
| type | The type of search to perform. Supported values are:
|
| 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.
| 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.
| 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.
| 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.
