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/{API version}/{API key}/products.xml?catalog_key={Catalog key}
Find "ipod" products:
http://api.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/products.xml?catalog_key=48qsligejm5qng6cv5waprcoq&keywords=ipod
Find 'xbox' price-comparison products:
http://api.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/products.xml?catalog_key=48qsligejm5qng6cv5waprcoq&include_product_groups=1&keywords=xbox
Find all products for a specific merchant:
http://api.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/products.xml?catalog_key=48qsligejm5qng6cv5waprcoq&merchant_id=1754
Find all products in your catalog:
http://api.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/products.xml?catalog_key=48qsligejm5qng6cv5waprcoq
| 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 |
| 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. |
| Field | Description |
|---|---|
| search_results |
Contains all of the query responses. Attributes:
|
| products |
Contains products matching the query parameters. Attributes:
|
| product |
Contains an individual product. Attributes:
|
| price_ranges | Contains price_ranges for products matching the query parameters. |
| price_range |
Contains an individual price_range. Attributes:
|
| 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:
|
| merchant_types | Contains top merchant_types for products matching the query parameters. |
| merchant_type |
Contains an individual merchant_type. Attributes:
|
| brands | Contains top brands for products matching the query parameters. |
| brand |
Contains an individual brand. Attributes:
|
| 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:
|
| deal |
Contains an individual deal. Attributes:
|
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.
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. |
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)
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.
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.
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.
Find "ipod" products listing product ids:
http://api.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/products.xml?catalog_key=48qsligejm5qng6cv5waprcoq&keywords=ipod&include_product_ids=1
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)
The "catalog_key" parameter is required when passing a product_id.
| Field | Value | Description |
|---|---|---|
| catalog_key | string | Unique key identifying catalog of merchants |
| product_id | integer | Unique id for a specific product |
| 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. |
| Field | Description |
|---|---|
| search_results |
Contains all of the query responses. Attributes:
|
| products |
Contains products matching the query parameters. Attributes:
|
| 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:
|
| product |
Contains an individual product. Attributes:
|
| 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:
|
| merchant_types | Contains top merchant_types for products matching the query parameters. |
| merchant_type |
Contains an individual merchant_type. Attributes:
|
| brands | Contains top brands for products matching the query parameters. |
| brand |
Contains an individual brand. Attributes:
|
| deals |
Contains deals available for products,merchants, and suggested merchants matching the query. Attributes:
|
| deal |
Contains an individual deal. Attributes:
|