ShopStyle Developer Blog

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.

Category updates

Mike — Thu, 12 Feb 2009 15:09:03 -0800

Along with the redesigned shopstyle.com launched this week we have made a few changes to the category tree that may be relevant to API users.

The "living" domain no longer exists. Fashion (women, men and kids) and living (home) products now exist in the same category tree.
Jewelry and Accessories have been made sub-categories of Women's Clothing.
Teen clothing have been made sub-categories of Women/Teens and Men/Teens.
Shorts has been made a sub-category of Pants. Bridal dresses and shoes have been moved to the main Dresses and Shoes categories.

If you are making calls such as

api.shopstyle.com/action/apiSearch?fts=leather&site=living.shopstyle.com

this will continue to work, but the site=living.shopstyle.com parameter will be deprecated and should be replaced with cat=living:

api.shopstyle.com/action/apiSearch?fts=leather&cat=living

Most API uses should not be affected by these changes. If you use apiSearch to find items and apiGetCategoryHistogram to group items by category, the new category structure will be populated automatically. If you hard-code any category identifiers, you may need to change them to match the new tree; for example, cat=pants becomes cat=pants-shorts.

Please leave a comment or contact us with any questions.

Ruby, Google and more

Mike — Mon, 05 Jan 2009 14:46:23 -0800

Some enterprising folks have posted a simple Ruby client that connects to the ShopStyle API:

http://infrastacks.com/?p=73

Also, check out a few examples of hosting apps on Google App Engine, with code ready to download:

http://developer.onsugar.com/

The ShopStyle team wishes everyone a happy and prosperous 2009!

Feed your RSS habit

Mike — Mon, 29 Dec 2008 14:50:14 -0800

To kick off the new year: RSS support (in beta). You may pass "format=rss" to the apiSearch method to retrieve a feed of matching products for use in your favorite RSS reader.

Example feed results:

Welcome

Mike — Sun, 05 Oct 2008 22:21:05 -0700

Our API lets you search and filter hundreds of thousands of fashion and living products featured on ShopStyle's US and UK sites; access thousands of looks created by our members; and get data on most popular brands and categories. Build your own site, mobile app or mash-up featuring ShopStyle products and we'll keep track of clicks you generate to our retailers. And enter our contest to win an iPhone and a year of service!

Here you can peruse our

API documentation;
Example sites built with the ShopStyle API;
Library of widgets ready to embed on your site.

To sign up you just need an account on shopstyle.com, and we'll provide you an API key. Questions or comments? Leave a comment here or email us at developer [at] shopstyle.com. We can't wait to see what you're working on to feed their habit. Have fun!

Sites powered by ShopStyle

Mike — Sun, 05 Oct 2008 22:02:33 -0700

Check out a few examples of websites that use the ShopStyle API!

CelebStyle.com - the definitive guide to what celebrities are wearing on and off the screen. The ShopStyle API powers custom product queries and layouts.

SaleHabit.com - search fashion and products on sale across the internet. The ShopStyle API powers a full example storefront with search, browsing and filtering features.

InStyle Shopping - the leading fashion & style magazine's shopping website is powered by ShopStyle. On this page, the "Most Shopped" ticker and "Editor's Picks" Flash widget use the ShopStyle API.

OnSugar - the Sugar Network's new blogging platform features a spread builder allowing members to build custom magazine-like layouts of their favorite ShopStyle items, powered by the API.

Also dozens of sites embed ShopStyle widgets. Take a look at glamour.com, instyle.com, fabsugar, casasugar, stylebakery, runwaydaily, shefinds, vibe.com, cumul.us, and many others for widget examples!

Widget: share a product

Mike — Sun, 28 Sep 2008 22:58:39 -0700

Find a ShopStyle product you want to share on your site or blog, and get credit for clicks by your visitors? Easy to do ... mouse over an item, click "Share this item", then "Blog it", and pick your image size.

Start shopping on shopstyle.com or check out a great widget example on fabsugar.com.

Widget: product search

Mike — Sun, 28 Sep 2008 22:58:32 -0700

Toss up a widget to allow your visitors to search and scroll through ShopStyle's inventory without leaving your site!

Here's an example:

Configure your own here: US fashion/home, UK fashion.

Widget: share a look

Mike — Sun, 28 Sep 2008 22:58:23 -0700

Share your own or other members' looks on your site with a ShopStyle widget. Just click the "Blog It" button next to any look in a stylebook. Here's a celebrity look from our fashion archive:

Customize the size, layout and contents of your widget. Build your own now!

A spread by one of our prolific members:

Build your own!

Widget: spread browser

Mike — Sun, 28 Sep 2008 22:57:51 -0700

Embed a scrolling browser of looks in spread format from your favorite member, group or tag!

Example: large widget for member 'HanounaQ':

Here's the same code. Build your own widget by clicking Blog Looks from a member or group page!

Widget: hot trends

Mike — Sun, 28 Sep 2008 22:57:38 -0700

Feature the most popular brands or products, automatically pulled from ShopStyle's inventory.

Popular brands & categories in women's fashion:

Customize this code to build your own!

Popular products in dresses, shoes, jewelry, and bags from our UK site:

Customize this code to build your own!

Sample PHP Client

Mike — Thu, 25 Sep 2008 09:40:33 -0700

We have created a simple PHP client to show one of the many possible ways of using the the ShopStyle API. This sample application contains two files: A reusable PHP class file that invokes various methods of the API, and a simple presentation module to display these results.

Click here to see this example in action.

You can also download these two sample files here:

Copy these files to your php-enabled webserver's document root and load http://localhost/ShopStyleAPIExample.php in your browser to run the application locally.

Medium silver hoops - $68.00	Circadian Studios Medium Silver Floating Hoop Earrings - $55.00
Herve Leger Mock Turtleneck Chevron Bandage Dress - $1,350.00	Herve Leger Scoopneck Tank Dress - $730.00
Modal Jersey Satin Insert Dress - $49.00	"Singer22 Exclusive" Mike and Chris Kian Donovan Leather Jacket in Black or Onyx with Trim as seen on Kate Moss-in stock - $775.00
Veda Domino Leather Jacket - $745.00	Paris Hilton - Brandy (Red Patent) - $93.00
rsvp - Paris (Red Patent) - $80.00	Nancy Gonzalez East-West Croc Clutch, Black - $1,400.00
Prada black leather 'Stripes' clutch - $736.00