Contents[Hide]
1 Basic Concepts
    1.1 Obtaining an API key
    1.2 Standard API Call Parameters
        1.2.1 required
        1.2.2 optional
2 search
    2.1 Input
    2.2 Examples
    2.3 Parameters
        2.3.1 required
        2.3.2 optional
3 stores
    3.1 Input
    3.2 Parameters
        3.2.1 required
        3.2.2 optional
4 store-list
    4.1 Input
5 adbar-search
    5.1 Input
    5.2 Parameters
        5.2.1 required
        5.2.2 optional
6 browse
    6.1 Input
    6.2 Parameters
        6.2.1 almost required
        6.2.2 optional

Search API | JSON Responses | XML Responses
This documents the Showiki Search API.

Basic Concepts

Shopwiki provides a web-service for performing searches on Shopwiki.  A request made to a URL will return a JSON or XML response containing the search results.

The basic form of this request will be:

http://api.shopwiki.com/api/<api-call>?key=<api-key>&<parameters>

The most common API call will be search, which takes the parameter q=<query>.  A search for the game apples to apples will take the form:

http://api.shopwiki.com/api/search?key=<api-key>&q;=apples+to+apples

API keys are needed to use make API calls.  The API key does three things:

  • Authorizes users to make API calls. No key, no call.
  • Ties revenue to specific API users.
  • Sets a number search options, like what subset of stores should be searched.

Obtaining an API key

API keys are available to our affiliates.  If you wish to become an affiliate, please contact James Keating, VP of Marketing, jk@shopwiki.com.

A public/test API key is available; it is 'b2cce8c214472b0c2bc17acf06d4da86'.  This test API key is intended to allow you to test the Shopwiki API from a technical standpoint; it is restricted both in the number of stores searched and in the frequency of the requests.  Additionally, there is no way to claim revenue produced using the public API key.  So, if you want to test the Shopwiki API from a business perspective with live traffic, you should become an affiliate first.

Standard API Call Parameters

There are several standard parameters which all API calls accept.

required

  • key=<api-key>
    • All calls must include this parameter.
    • The API key; a hexidecimal string which authenticates you to use the API.
    • The public/test API key is 'b2cce8c214472b0c2bc17acf06d4da86'.
      • The search results returned by the test API key are restricted to a subset of Shopwiki's offers and stores. It is intended for testing a front-end and ensuring that it works with the API correctly.
      • The test API key may change periodically. When it does, the new key will be listed here.

optional

  • version=<integer>
    • Optional parameter.
    • Selects the version of the API to be used for the call.
    • The currently acceptable values are: 1.
    • The current default version is: 1.
  • output=<output-format>
    • Optional parameter.
    • Selects the output format for responses.
    • The currently acceptable values are: json, xml.
    • The current default version is: json.
    • The default can be changed on a per-api-key basis.

search

JSON Response | XML Response
Searches take a search or query and return a list of (hopefully unique) products.  For instance, you might search for 'ipod', and expect to get back a list including 'Ipod Nano 8GB', 'Ipod Shuffle 1GB', and 'Ipod Nano 4GB'.  A search can be done using just a keyword string, or it can be filtered based on features of the products you're looking for, like the price range or brands.

Input

Examples

Parameters

required

  • q
    • The query string.

optional

  • loc
    • Locale for search.
    • Must be in form 'en_US', 'fr_FR', etc.
    • Defaults to 'en_US'.
  • n
    • Number of results desired.
    • Defaults to 20.
    • Maximum of 2000.
  • start
    • Position in the results.
    • Defaults to 0.
    • Maximum of 1999.
  • bot
    • Indicates this search is being performed on behalf of a robot (crawler).
    • bot=t[rue].
  • detailed
    • Indicates whether to included extra information (slower, not necessarily necessary) in the results.
    • detailed=t[rue].
    • The following fields are included in offers when detailed=true:
      • "number_of_stores"
      • "price_range"
      • "short_list"
  • min_price
    • Integer, minimum price.
    • Filters results to only include offers above this price.
  • max_price
  • brand
    • Comma-separated list of brands.
    • Filters results to only include offers with one of these brands.
  • color
    • Six-digit hexidecimal color code.
    • Filters results to only include offers with this color.
  • sort
    • sort=price|relevancy
    • Dictates sort-key.
    • Defaults to 'sort=relevancy'.
  • ascending
    • ascending=t[rue]
    • Dictates sort-order.
    • Defaults to false (descending order).
  • site_id
    • site_id=<comma-separated-list-of-integers>
    • Filters a search to only the stores with the specified Shopwiki site_ids.
    • site_id, store_name, and store_url will search the union of their sets when used together.
      • Don't use them together, that's just silly.
  • store_url
    • Filters a search to only the stores with the specified store_urls.
  • store_name
    • Filters a search to only the stores with the specified store_names.
    • This really only works if you are working with a subset of all stores. We really only know the names of a tiny number of stores.
  • image_size
    • Adjusts the size of the hosted_image. The hosted image will not be resized to a larger size than the original.
    • Defaults to full-sized.
  • thumbnail_size
    • Adjusts the size of the thumbnail. The thumbnail will not be resized to a larger size than the original.
    • Defaults to 140.
  • relevancy
    • Adjusts the threshold for a relevant result, relative to the default threshold.
    • Values greater than 1.0 produce stricter (that is, fewer) results.
    • Values less than 1.0 produce looser (that is, more) results.
    • Defaults to 1.0

stores

JSON Response | XML Response
A stores search basically returns the list of stores a product is available at.

Input

Parameters

required

  • d
    • Title of the product you are looking up.

optional

  • o
    • Offer-id of the offer you are looking up, as returned in the offer_id field of a search result.
  • s
    • Site-id of the offer you are looking up, as returned in the site_id field of a search result.
  • loc
    • The locale of the offer you are looking up. Defaults to 'en-US'.

store-list

JSON Response | XML Response
Some API users search a specific set of stores.  The store-list call returns the list of stores.

Input

adbar-search

JSON Response | XML Response
The search/stores calls are really intended for an interactive user search through some front-end.  The adbar-search is specialized for when the front-end is not interactive, and is instead just an ad-box or other list of a handful of offers.

Input

Parameters

required

  • q
    • A search string or other collection of keywords.

optional

  • n
    • The number of results to return.
    • Default value is 5.

browse

JSON Response | XML Response
The 'browse' call is used to browse the offers from a particular store or set of stores.

Input

Parameters

almost required

If your API key has a set of sites associated with it, you don't need to pass any parameters; you can browse all of these stores as a whole.  If you don't, you will need to pass one of site_id, store_url, store_name.

  • site_id
    • site_id=<comma-separated-list-of-integers>
    • Filters a search to only the stores with the specified Shopwiki site_ids.
    • site_id, store_name, and store_url will search the union of their sets when used together.
      • Don't use them together, that's just silly.
  • store_url
    • Filters a search to only the stores with the specified store_urls.
  • store_name
    • Filters a search to only the stores with the specified store_names.
    • This really only works if you are working with a subset of all stores. We really only know the names of a tiny number of stores.

optional

  • loc
    • Locale for search.
    • Must be in form 'en_US', 'fr_FR', etc.
    • Defaults to 'en_US'.
  • n
    • Number of results desired.
    • Defaults to 20.
    • Maximum of 2000.
  • start
    • Position in the results.
    • Defaults to 0.
    • Maximum of 1999.
  • bot
    • Indicates this search is being performed on behalf of a robot (crawler).
    • bot=t[rue].
  • detailed
    • Indicates whether to included extra information (slower, not necessarily necessary) in the results.
    • detailed=t[rue].
    • The following fields are included in offers when detailed=true:
      • "number_of_stores"
      • "price_range"
      • "short_list"
  • min_price
    • Integer, minimum price.
    • Filters results to only include offers above this price.
  • max_price
  • brand
    • Comma-separated list of brands.
    • Filters results to only include offers with one of these brands.
  • color
    • Six-digit hexidecimal color code.
    • Filters results to only include offers with this color.
  • sort
    • sort=price|relevancy
    • Dictates sort-key.
    • Defaults to 'sort=relevancy'.
  • ascending
    • ascending=t[rue]
    • Dictates sort-order.
    • Defaults to false (descending order).
▼ Advertisement ▼