API


API Overview

The ShopStyle API allows client applications to retrieve the underlying data for all the basic elements of the ShopStyle website, including products, brands, retailers, and categories. 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.

To use the ShopStyle API, make sure your Partner ID is appended to all requests.

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:

  1. Choose the method that returns the data your application needs. For example, the /products method is used to get products that match a given category or brand.
  2. Construct a URL for that method with the appropriate host, method name, and query parameters.
  3. Invoke the URL as an HTTP GET.
  4. 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 responses 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 format.

There are clients implemented in different languages: Ruby, PHP, Python, Objective-C and Java.

ShopStyle API URLs

All ShopStyle API URLs have the following form:

http://api.shopstyle.com/api/VERSION/METHOD_NAME?pid=YOUR_API_KEY&format=FORMAT&...

The METHOD_NAME is taken from the list of methods in the various API shown at left.

The VERSION is the API version with the prefix 'v'. Our latest version is 'v2'. The version can be omitted to always use the latest version available. However we do not guarantee backward compatibility between different versions of the API.

Common API Parameters

All methods in the API accept these parameters:

pid Unique API_KEY string that is assigned to the caller. Sign up here to get your Shopstyle API key. Your Partner ID: This parameter must be present.

format

The format of the response. Supported values are:

  • json - The response is in JSON format with UTF-8 encoding. This is the default if the parameter is absent.
  • xml - The response is in XML format with UTF-8 encoding.
  • jsonp - The response is in JSON format with UTF-8 encoding wrapped in a JavaScript method called padding. The padding must be specified with the query parameter 'callback'. Only single expressions (function reference, or object property function reference) are accepted as valid paddings.
  • 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.
suppressResponseCode When set to 1 or 'true' the HTTP status will always be 200. Use the field "errorCode" in the response to detect whether the API Call was successful. By default, when an error occur the HTTP Status of the response will be different than 200