es

^^The API is still in a beta state!^^ ^^No further changes are expected, but I'll only feel a little bad if they happen.^^ XML Responses '''(NOTE: XML Responses are deprecated)''' !This documents the Showiki Search API, namely, the JSON responses to API calls.

Basic Concepts

JSON responses will be a single JSON object. JSON objects are JavaScript objects, consisting of maps, lists, and other JavaScript primitives. Whenever a response, or part of a response, is a JSON map, some fields will always be sent (no matter what), some fields will usually be sent (unless there's an error), and some fields will sometimes be sent (if they're there). In the following sections, there will be sections labeled 'always', 'usually', and 'sometimes'. Use these labels as guides when deciding how to use a field and when to check for its existence.

search

A search returns a JSON map with the following fields:

always

* "offers" : [ '''''<SEARCH_RESULT>''''' ]

usually

* "number_of_results" : ''<integer>'' * "shopwiki_url" : ''<string>'' ** URL of this search on Shopwiki. ** You're probably required to include this link somewhere.

sometimes

* "related_searches" : [ '''''<SEARCH_SUGGESTION>''''' ] ** A list of searches which we think are related to this search. * "spelling_correction" : ''<string>''

stores

A stores or detail call returns a JSON map with the following fields:

always

* "item" : '''''<OFFER'>''''' * "offers" : [ '''''<OFFER>''''' ]

usually

* "number_of_results" : ''<integer>'' * "price_range" : [ ''<integer>'', ''<integer>'' ] * "shopwiki_url" : ''<string>'' ** URL of this search on Shopwiki. ** You're probably required to include this link somewhere. * "related_offers" : [ '''''<OFFER>''''' ]

store-list

The output is a JSON list of stores. * [ '''''<STORE>''''' ]

adbar-search

A search returns a JSON map with the following fields:

always

* "offers" : [ '''''<OFFER>''''' ]

usually

* "shopwiki_url" : ''<string>'' ** URL of this search on Shopwiki. ** You're probably required to include this link somewhere.

Common objects (maps)

SEARCH_RESULT

always

* "offer" : '''''<OFFER>''''', * "score" : [ ''<real>'', ''<real>'' ] ** Two-component score, first component is relevancy (with respect to query), second component is bonus (prettiness of the offer).

sometimes

* "number_of_stores" : ''<integer>'' ** 'detailed' information. * "price_range" : [ ''<real>'', ''<real>'' ] ** Lower and upper bounds on prices for this result. ** 'detailed' information. * "short_list" : [ '''''<OFFER>''''' ] ** A short list of stores this offer is available from. ** 'detailed' information.

OFFER

always

* "title" : ''<string>'' * "price" : ''<real>''

usually

* "url" : ''<string>'' ** The only time the "url" field will be absent is if there is an "affiliate_url" field, and vice versa. Both may be present, but one always will. * "affiliate_url" : ''<string>'' ** URL which will work with our affiliate program. ** This is the one you actually need to use. ** If affiliate_url is missing from an offer, default to url. ** affiliate_url may expire. No affiliate_url should be cached for more than a day. ** '''&v=''''''''<string>''''' may be appended to the affiliate URL. *** This string is whatever visit id / user id you want it to be, from your own internal user tracking. *** The string can be up to 32 characters. *** This vid will be referenced in the reports you receive, indicating which transactions converted. * "image" : ''<string>'' ** URL of image on store's site * "thumbnail" : ''<string>'' ** URL of a 120x120 thumbnail of the image, hosted by ShopWiki. ** This uses the Shopwiki thumbnailing system. * "hosted_image" : ''<string>'' ** URL of image, hosted by ShopWiki. * "offer_id" : ''<integer>'' ** Internal ID. Useful for requests to ShopWiki, not useful for anything else. Not guaranteed to be stable from day to day. * "site_id" : ''<integer>'' ** Internal ID, one ID per store.

sometimes

* "description" : ''<string>'' * "model" : ''<string>'' * "brand" : ''<string>'' * "breadcrumbs" : ''<string>'' ** The breadcrumbs found for an offer. ** These may indicate some sort of category information, ie "Clothing > Pants > Jeans > Levi's". ** Maybe not, though. * "locale" : ''<string>'' ** In the form 'en_US', 'fr_FR'.

OFFER'

always

* "title" : ''<string>'' * "price" : ''<real>''

usually

* "image" : ''<string>'' * "thumbnail" : ''<string>'' * "hosted_image" : ''<string>''

sometimes

* "description" : ''<string>''

SEARCH_SUGGESTION

always

* "search" : ''<string>'' * "filters" : ''<string>''

STORE

always

* "site_id" : ''<integer>'' ** Shopwiki Site Id. * "homepage_url" : ''<string>'' ** URL of the store's homepage, eg, "http://bobshardware.com/".

sometimes

* "store_name" : ''<string>'' ** Name of a store, eg, "Bob's Hardware Store". ** We might not have the name. We always have the URL, since we can't crawl the store otherwise, but the name has to be hand entered. We try to add store names whenever they're needed, but this field may be absent sometimes.