Find products

As noted before, a product call must be made by passing at least one keyword. The XML response is designed to provide as much detail as possible in a single call. The products matching the supplied keywords will be returned as well as matching price ranges, merchants, categories, brands, and deals.

A simple product call limited to the products in your catalog would be a call to return all products in XML (products.xml) with the word "ipod 16gb" (keywords=ipod+16gb) within your catalog. Use the "+" sign to combine multiple words into a single keyword call. The first parameter would be separated with an question mark "?" and the additional parameters an ampersand "&". This call would look like the following:

http://api.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/products.xml?catalog_key=48qsligejm5qng6cv5waprcoq&keywords=ipod+16gb

Request URL

http://api.popshops.com/{API version}/{API key}/products.xml?catalog_key={Catalog key}

Sample requests

Find 'ipod' products:
http://api.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/products.xml?catalog_key=48qsligejm5qng6cv5waprcoq&keywords=ipod

Find all products for a specific merchant:
http://api.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/products.xml?catalog_key=48qsligejm5qng6cv5waprcoq&merchant_id=1447

Find all products in your catalog:
http://api.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/products.xml?catalog_key=48qsligejm5qng6cv5waprcoq

Required request parameters

Field	Value	Description
API version	string v1 or v2	The specifies which API version you wish to call. v2 provides the ability to make price comparison calls through the use of product groups.
API key	string	Unique key identifying your account
catalog_key	string	Unique key identifying catalog of merchants

Optional request parameters

Field	Value	Description
keywords	string	A list of keywords to search across your catalog merchants. keywords=ipod Is a basic search for products containing the keyword 'ipod' keywords=ipod -case is a search for products containing the keyword 'ipod' and NOT containing the keyword 'case'
merchant_id	integer	A unique PopShops merchant_id, limiting products to a single merchant
merchant_type_id	integer	A unique merchant_type_id limiting products to a single merchant_type.
category_id	integer	A PopShops category ID, limiting products to a single merchant's category. Category ids are currently only returned in product query responses.
brand_id	integer	A PopShops brand_id, limiting products to a single brand
price_min	decimal 10.00,19.95, etc	Price minimum product prices should not go below
price_max	decimal 10.00,19.95, etc.	Price maximum product prices should not exceed
product_sort	price_asc price_desc	Featured (default), Lowest Price, Highest Price
product_limit	1-100	Number of products to display at a time. 100 maximum.
product_offset	integer	Number to offset the product results by
include_product_ids	boolean 1 or 0	.v2 Product id information will be included on product nodes. Defaults to 0.
product_id	integer	.v2 A unique id for an individual product. This will return a single product which can be used for product detail pages, wishlists, etc. Note: You can pass in multiple product ids by separating with commas. For example: product_id=1234,7890
include_product_groups	boolean 1 or 0	.v2 Product group information will be included on product nodes. Defaults to 0.
product_group_id	integer	.v2 A unique id for a group of similar products. This will return a set of products belonging to the same product group, which can be used for price comparisons. The 'keywords' parameter is required when passing a product_group_id.
include_deals	boolean 1 or 0	Available deals can also be included in the result set that match returned products and merchants.
url_subid	string	Custom subid/sid to be appended in any final affiliate product urls.

Response fields

Field	Description
search_results	Contains all of the query responses. Attributes: keywords: any keywords passed in product_limit: any product_limit passed in product_offset: any product_offset passed in merchant_id: any merchant_id passed in category_id: any category_id passed in brand_id: any brand_id passed in product_sort: any product_sort passed in price_min: any price_min passed in price_max: any price_max passed in merchant_type_id: any merchant_type_id passed in
products	Contains products matching the query parameters. Attributes: total_count: Total number of products matching the query parameters
product	Contains an individual product. Attributes: name: The name of the product description: The description of the product merchant_id: The merchant_id for the merchant the product belongs to. large_image_url: A url for the largest sized image available for the product. medium_image_url: A url for a medium sized image of the product. small_image_url: A url for a small sized image of the product. merchant_price: The price offered through the merchant. Usually corresponds to the lowest price. retail_price: The listed retail price of the product. .v2 id: A unique id identifying a single product. .v2 product_group_id: A unique id identifying a group of similar products the product belongs to. .v2 product_group_product_count: The number of products in the product group. .v2 product_group_merchant_count: The number of merchants belonging to the product group. .v2 product_group_min_price: The lowest price available in the product group. .v2 product_group_max_price: The highest price available in the product group.
price_ranges	Contains price_ranges for products matching the query parameters.
price_range	Contains an individual price_range. Attributes: max: The max dollar value in the range min: The min dollar value in the range product_count: The number of products within this price range.
merchants	Contains top merchants for products matching the query parameters. In many cases the number of merchants matching the query is too many to bring back, so this will only bring back the top 50 merchant matches by product count. You may encounter results where you get a product on a page and there is no matching merchant in the merchants node.
merchant	Contains an individual merchant. Attributes: id: A unique id for the merchant. You can pass this in as a merchant_id to filter products to this specific merchant. name: The name of the merchant. product_count: The number of products matching the query for this specific merchant. logo_url: If available a logo_url will be provided which is a url to small thumbnail of a logo for the merchant. url: If available the url will be returned, which is a landing page for this merchant. merchant_type_id: If the merchant belongs to a merchant_type, this will be the id for the merchant_type. This can be used to further filter products as a merchant_type_id parameter.
merchant_types	Contains top merchant_types for products matching the query parameters.
merchant_type	Contains an individual merchant_type. Attributes: id: A unique id for the merchant_type. You can pass this in as a merchant_type_id to filter products to this specific merchant_type. name: The name of the merchant_type. product_count: The number of products matching the query for this specific merchant_type.
brands	Contains top brands for products matching the query parameters.
brand	Contains an individual brand. Attributes: id: A unique id for the brand. You can pass this in as a brand_id to filter products to this specific merchant_type. name: The name of the brand. product_count: The number of products matching the query for this specific brand.
suggested_merchants	If the keywords match any merchant names, or have been tagged by PopShops as belonging to a specific merchant, this node will return any merchants that may be possible matches. This node will have child merchant nodes with attributes available on normal merchant nodes.
deals	Contains deals available for products,merchants, and suggested merchants matching the query. Attributes: restrictions: Global restrictions that apply to any deal returned.
deal	Contains an individual deal. Attributes: name: The name of the deal. description: A description of the deal. url: The redirect url for the deal. image_url: If an image is available for the deal, this will be a url for that image. specific: This is a boolean (true/false) indicating whether the deal is specific to a product, or applies to all products from the merchant. start_on: The start date the deal is valid. end_on: The end date the deal is no longer valid. code: Any associated code for the deal. This is a code that would need to be used to redeem the deal. deal_type_ids: The deal_type id indicating what kind of deal this is. restrictions: Any applicable restrictions unique to this deal or merchant. merchant_id: A unique id for the merchant. merchant_type_id: The id of the merchant_type the merchant of this deal belongs to.

Sample response

The following is a sample response listing the available merchants: