Find products

A product call is 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

Back to top

2. Call parameters

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 Rakuten 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 Rakuten 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 Rakuten 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. For example, to display page 11 with 10 products per page the product_limit should be set to 10 and product_offset should be 110. Note: You can pagination for up to 15,000 top relevant results on a query.
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.
Back to top

3. 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 Rakuten 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.
Back to top

4. Price comparison

Available in v2 of the API is the ability to get back additional data about products which can be used to build price comparison applications.

Price comparison product attributes

Additional attributes will be returned with a product if it belongs to a group of similar products and you have passed in the 'include_product_groups=1' parameter on your product request.

This group of related products is identified within Rakuten PopShops with a product_group_id. These attributes will be returned in addition to the normal product attributes.

Attribute Value Description
product_group_id integer A unique id identifying a group of similar products the product belongs to.
product_group_product_count integer The number of products in the product group.
product_group_merchant_count integer The number of merchants belonging to the product group.
product_group_min_price decimal
10.00,19.95, etc
The lowest price available in the product group.
product_group_max_price decimal
10.00,19.95, etc
The highest price available in the product group.

Example price comparison request

To retrieve products for a specific product group you make a normal product query, but add the product_group_id for the relevant product group. Here is an example call. (Note: It may not work because of the specific merchants in your catalog)

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

The "keywords" parameter is required when passing a product_group_id.

Look at the product request documentation to see the available request/response fields that are associated with this call.

Back to top

5. Product details

Available in v2 of the API is the ability to get back individual product information which can be used to implement product detail pages, wishlists, product reviews, etc.

Product detail attributes

In order to get access to product_id attributes required to make product detail calls, you will need to add include_product_ids=1 onto any keyword search queries.

Products will now have an 'id' attribute which can be used to make a call for that specific items details.

Sample requests

Find "ipod" products listing product ids:
http://api.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/products.xml?catalog_key=48qsligejm5qng6cv5waprcoq&keywords=ipod&include_product_ids=1

Example product detail request

Now that you have a product id you can use it to retrieve product details. Here is an example call. (Note: It may not work because of the specific merchants in your catalog)

http://api.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/products.xml?catalog_key=48qsligejm5qng6cv5waprcoq&product_id=80325107

The "catalog_key" parameter is required when passing a product_id.

Required request parameters

Field Value Description
catalog_key string Unique key identifying catalog of merchants
product_id integer Unique id for a specific product

Optional request parameters

Field Value Description
include_product_groups boolean
1 or 0
.v2 Product group information will be included on product nodes. Defaults to 0.
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:
  • product_id: product id passed in
products Contains products matching the query parameters. Attributes:
  • total_count: Total number of products matching the query parameters
product_group_products Contains products within a product's product group. This is only returned if the parameter include_product_groups=1 was passed in. This is helpful if you want to retrieve comparable products within a single call. Attributes:
  • total_count: Total number of products in the product group
  • product_group_id: Unique id identifying the product group
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.
  • ONLY IN PRODUCT_ID CALLS active: Indicates whether the product is still actively available
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.
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.

Recently viewed

Most viewed