Product calls are used to get all information related to products, and the specific merchant offers for those products. One thing to note is that only offers will have affiliate links associated with them, the product itself will not have an affiliate URL. Therefore products with multiple offers will require an additional API call using the "product' parameter listed below. Our product numbers use a 64bit integer.
http://api.popshops.com/v3/products.xml
http://api.popshops.com/v3/products.json
XML, JSON |
Parameter name | Type | Kind | Allowed values | Default value | Description |
---|---|---|---|---|---|
account | account | Your API account key. You can find this on your API keys account page. | |||
catalog | item | A catalog key to limit the products to those for a specific catalog. |
Note that identifier parameter (i.e. "keyword_identifier", "keyword_isbn", "keyword_ean", "keyword_upc", "keyword_mpn") values will be interpreted as queries whenever a keyword parameter (i.e. "keyword", "keyword_name", "keyword_description") is also set; otherwise, identifier parameters will be interpreted as filters.
Parameter name | Type | Kind | Allowed values | Default value | Description |
---|---|---|---|---|---|
brand | query | The brand ID the product offers should belong to. Limited to brand IDs as provided by the merchants. | |||
category | item | The Rakuten PopShops category a product belongs to. | |||
currency | item | filter | USD GBP AUD BRL CAD EUR MXN CHF CNY JMD NPR NZD AFN ZWD ARS AWG INR BAM BGN BOB |
en_US | The currency in which a given product is offered |
include_discounts | control | This will force the response to return the top discounted offer for each product as part of the results. | |||
keyword | query | Positive Keyword: A keyword or phrase you want to find in the product name or description. A specific phrase will need double quotes "keyword phrase" or it will return result for both individual words. Negative Keyword: A singular keyword you do not want to find in product name or description. These keywords are prefixed with a dash (-). Ex: keyword=ipod –case will bring up products containing the keyword ‘ipod’ but not the keyword ‘case’. |
|||
keyword_description | query | A keyword or phrase you want to find specifically in the product description | |||
keyword_brand | query | A term you want to search against a product's brand, such as "lenovo" or "samsung". | |||
keyword_ean | selection | filter,query | A term you want to search against a product's EAN. | ||
keyword_identifier premium | selection | filter,query | A term you want to search against product EAN, ISBN, MPN, UPC | ||
keyword_isbn | selection | filter,query | A term you want to search against product ISBNs | ||
keyword_mpn | selection | filter,query | A term you want to search against product MPNs | ||
keyword_name | query | A keyword or phrase you want to find specifically in the product name | |||
keyword_person | query | A term you want to search against product author or artist | |||
keyword_sku premium | query | A term you want to search against Merchant offer SKU | |||
keyword_upc | selection | filter,query | A term you want to search against product UPCs | ||
language | selection | filter | For English: en_US For French: fr_FR For German: de_DE For Brazilian Portuguese: pt_BR |
en_US | The language (or regional dialect of a language) with which matching offers will be associated and which keyword-based queries will be analyzed. Note:If two values are specified (i.e. language=L1,L2), then the first value represents the primary language and the second value represents the backfill language (to be used if fewer than 1000 hits match the primary language). |
merchant | selection | filter | The merchant ID of the merchant product offers should belong to. Could be a comma delimited list of multiple merchant IDs. | ||
merchant_type | selection | filter | The merchant type ID of the merchant product offers should belong to. Could be a comma delimited list of multiple merchant type IDs. | ||
page | item | pagination | 1-10 | 1 | The page number of results to return. This parameter will return up to a total of 1000 products. Ten pages with 100 product is the max results. |
percent_off | range | filter | The exact percent off you want the offer merchant prices vs. retail prices. You can also use this as shorthand for percent_off_min and percent_off_max by passing in both values delimited with a '-'. This is an example of requesting products with offers with at least a 5% off price to a maximum of 10% off: percent_off=5-10. You will also want to include '&include_discounts=true' in this call. | ||
percent_off_max | specific percent max | filter | The maximum percent off you want the offer merchant prices vs. retail prices. You will also want to include '&include_discounts=true" in this call. | ||
percent_off_min | specific percent min | filter | The minimum percent off you want the offer merchant prices vs. retail prices. You will also want to include '&include_discounts=true" in this call. | ||
price | range | filter | The exact price you want the offer merchant prices. You can also use this as shorthand for price_min and price_max by passing in both values delimited with a '-'. This is an example of requesting products with offers with at least a $5 price to a maximum of $10 off: price=5-10 | ||
price_max | range | filter | The maximum price you want the offer merchant prices. Please use whole dollar amounts only. | ||
price_min | range | filter | The minimum price you want the offer merchant prices. Please use whole dollar amounts only. | ||
product | selection | The product ID of the exact product you want returned. Necessary to get all offer URLs from multiple product offers. Could be a comma delimited list of multiple product IDs. | |||
product_spec premium | view | true,false | false | Indicates whether or not to include the product specification in the response. This will include an attributes node under the product node listing available attributes for the product. Offers will not be included in the results | |
include_identifiers premium | view | true,false | false | Indicates whether or not to include the product identifiers in the response. This will include an attributes node under the product node listing available identifiers for the product. Offers will be included in the results | |
results_per_page | item | pagination | 1-100 | 20 | The number of products to return in every response. |
session | session | This is zipped up information we use to determine any state of previous requests. This allows us to build up more relevant filter values in the current response in order to get back to previous filtered states. You do NOT to generate the session value. We will provide the session value in the parameters block being returned. You just need to pass it forward for any additional calls you make. | |||
sort_product | sort | name_desc, name_asc, price_desc, price_asc, percent_off_desc, percent_off_asc, cat_desc, cat_asc | relevance | ||
tracking_id | view | Optional custom tracking id to be passed along in affiliate links to the affiliate network. (Please note, there is a 20 character limit for tracking ids.) |
By default the response only brings back products. There are two cases where you will get actual offer information back.
Node | Attribute | Kind | Data Type | Description |
---|---|---|---|---|
products | The container for all individual products. | |||
count | count | integer | A count of all products matching the query. | |
product | An individual product. | |||
brand | resource | integer | The id of the brand a product belongs to. | |
category | resource | integer | The id of the category a product belongs to. | |
description | display | string | A description of the product. | |
idrequired | primary_key | integer | A unique identifier assigned by Rakuten PopShops for a product. | |
image_url_large | image_url | string | A URL for a large sized image of the product. | |
image_url_medium | image_url | string | A URL for a medium sized image of the product. | |
image_url_small | image_url | string | A URL for a small sized image of the product | |
namerequired | display | string | The name of the product. | |
offer_count | count | integer | A count of the number of merchant offers available for the product. | |
price_max | price | float | The maximum price of all merchant offers for the product. | |
price_min | price | float | The minimum price of all merchant offers for the product. | |
offers | Contains all offers for a given product | |||
offer | An individual offer for a product. | |||
condition premium | display | string | The condition of the offer, such as refurbished or new. | |
currency_iso | display | string | The currency ISO code for the offer. | |
currency_symbol | display | string | The HTML entity for the currency symbol of the offer. | |
description | display | string | The merchant provided description of the product offer. | |
estimated_shipping premium | price | float | The merchant provided estimated shipping of the product offer. | |
estimated_price_total premium | price | float | The total calculated price of an offer that takes into consideration any estimated sales tax or estimated shipping. | |
idrequired | primary_key | integer | This is the unique identifier assigned by Rakuten PopShops for the merchant offer. | |
image_url_large | image_url | string | The merchant provided large sized image URL. | |
image_url_medium | image_url | string | The merchant provided medium sized image URL. | |
image_url_small | image_url | string | The merchant provided small sized image URL. | |
merchant | resource | integer | The merchant ID of the merchant the offer belongs to. | |
namerequired | display | string | The merchant provided name of the product offer. | |
percent_off | percentage | float | The calculated percent off from the merchant provided price, and the merchant provided retail price. | |
price_merchant | price | float | The merchant provided price they are selling the product offer for. | |
price_retail | price | float | The merchant provided retail price to compare against the price they are offering the product at. | |
sku premium | display | string | The SKU (stock keep unit) identifier assigned by the merchant for the product offer. | |
url | redirect_url | string | A redirect url that will go through the affiliate network and pass along your tracking information to get to the final merchant product offer landing page. | |
attributes premium | Contains all attributes for a product. This is only returned if you pass in 'product_spec=true' in your api call. | |||
attribute premium | An individual attribute for a product. | |||
namerequired | display | string | The name describing what type of attribute this is for the product. Examples of this are: mpn, upc | |
value | display | string | The actual value of the attribute for the product. |
<?xml version="1.0" encoding="UTF-8"?>
<response status="200" message="ok"...>
<parameters>...</parameters>
<results>
<products count="1535">
<product brand="37254" offer_count="10" category="32277" image_url_large="http://www.popshops.com/img/public/o/0/2/352/18-3.jpg" price_min="149.99"
description="Logitech Squeezebox Radio (BLACK) brings a world of musicfree Internet radio subscription services or your personal digital music collection to any space in your home over your WiFi network."
image_url_medium="http://www.popshops.com/img/public/o/0/2/352/18-2.jpg"
price_max="214.54" name="Logitech Inc 930000101 Squeezebox Radio Black"
image_url_small="http://www.popshops.com/img/public/o/0/2/352/18-1.jpg" id="405966"></product>
</products>
<deals count="25">
<deal start_on="05/06/2010" site_wide="no" end_on="01/01/2017" merchant="5653"
description="PROMO: Dented Box and Refurbished Items From Logitech"
image_url="http://www.ftjcfx.com/image-2133188-10762343" deal_type="4"
name="Save big with Dented Box products have cosmetic damage to the packaging, but product is new and fully warranted." id="209974"
url="http://r.popshops.com/r/V1dKVzJJRmlvM241ZnhFTitubEk5by9NblF6aDErd3NDNUNLR25HSmFsRjlPTEJKS25lVm16bXNnTnlBCm0yQ2wK"></deal>
...
</deals>
</results>
<resources>
<merchants count="25">
<merchant logo_url="http://www.popshops.com/img/public/l/0/0/0/230-1.jpg"
count="268" name="Newegg.com" id="230"
url="http://r.popshops.com/r/V1dKVzJJRmlvM241ZnhFTitubEk5bnhlTEMwbnprN1k1dEQxRDN6cjlUSkp2eVpzY2lha2d3OG1nUWxTClBzS2QK"></merchant>
....
</merchants>
<brands count="25">...</brands>
<deal_types count="6">...</deal_types>
<categories>
<context>
<category order="0" name="All" id="1"></category>
</context>
<matches>
<category count="2" leaf="true" name="AM / FM & Clock Radios" id="32280"></category>
...
</matches>
</categories>
</resources>
<filters>
<filter type="selection" resource="merchant" name="merchant" parameter="merchant"></filter>
<filter type="range" name="price" parameter="price">
<values>
<value count="1475" min="0" max="360"></value>
...
</values>
</filter>
...
</filters>
</response>
{
"resources":
{
"deal_types":
{
"count": 6,
"deal_type":
[
{
"count": "1",
"name": "Sale/Clearance",
"id": "4"
}
...
]
},
"brands":
{
"brand":
[
{
"count": "16",
"name": "Franklin Sports",
"id": "29727"
},
...
],
"count": 25
},
"categories":
{
"context":
{
"category":
[
{
"order": "0",
"name": "All",
"id": "1"
}
]
},
"matches":
{
"category":
[
{
"count": "2",
"leaf": "true",
"name": "AM / FM & Clock Radios",
"id": "32280"
},
...
]
}
},
"merchants":
{
"count": 25,
"merchant":
[
{
"logo_url": "http://www.popshops.com/img/public/l/0/0/0/230-1.jpg",
"count": "268",
"name": "Newegg.com",
"id": "230",
"url": "http://r.popshops.com/r/TE1lK0VaWXRlNUt6RURHajhJMWFySnk0NWlYMFhjNUFhbS9TU2VtVHRXS0pKeXJaV0hpZU11T3ZENWxYCkNwS20K"
},
...
]
}
},
"filters":
{
"filter":
[
{
"type": "selection",
"resource": "merchant",
"name": "merchant",
"parameter": "merchant"
},
{
"type": "selection",
"resource": "brand",
"name": "brand",
"parameter": "brand"
},
...
{
"type": "item",
"resource": "category",
"name": "category",
"parameter": "category"
}
]
},
"results":
{
"products":
{
"count": 1535,
"product":
[
{
"brand": "37254",
"offer_count": "10",
"category": "32277",
"image_url_large": "http://www.popshops.com/img/public/o/0/2/352/18-3.jpg",
"price_min": "149.99",
"description": "Logitech Squeezebox Radio (BLACK) brings a world of musicfree Internet radio subscription services or your personal digital music collection to any space in your home over your WiFi network.",
"image_url_medium": "http://www.popshops.com/img/public/o/0/2/352/18-2.jpg",
"price_max": "214.54",
"name": "Logitech Inc 930000101 Squeezebox Radio Black",
"image_url_small": "http://www.popshops.com/img/public/o/0/2/352/18-1.jpg",
"id": "405966"
},
{
"brand": "37254",
"offer_count": "16",
"category": "32279",
"image_url_large": "http://www.capitolsupply.com/ImageServer.ashx?t=product&h=200&w=200&imageid=CS12935298",
"price_min": "79.99",
"description": "Enjoy crystal-clear calls and video chats and listen to up to 10 hours of music per charge with this Logitech 984-000204 Bluetooth-enabled boombox that features a specially designed acoustic chamber that delivers great sound with enhanced bass.",
"price_max": "119.37",
"name": "Logitech - Bluetooth-Enabled Boombox for Apple? iPod? and Most MP3 Players",
"id": "18725796"
},
{
"brand": "37254",
"offer_count": "3",
"category": "32275",
"image_url_large": "http://www.restockit.com/images/Product/medium/930000090.jpg",
"price_min": "309.42",
"description": "Logitech Squeezebox Touch. The color touch-screen Wi-Fi music player that lets you discover a world of music - all through your stereo!",
"price_max": "365.34",
"name": "Logitech Squeezebox Touch",
"id": "1334248"
},
...
]
},
"deals":
{
"count": 25,
"deal":
[
{
"start_on": "05/06/2010",
"site_wide": "no",
"end_on": "01/01/2017",
"merchant": "5653",
"description": "PROMO: Dented Box and Refurbished Items From Logitech",
"image_url": "http://www.ftjcfx.com/image-2133188-10762343",
"deal_type": "4",
"name": "Save big with Dented Box products have cosmetic damage to the packaging, but product is new and fully warranted.",
"id": "209974",
"url": "http://r.popshops.com/r/TE1lK0VaWXRlNUt6RURHajhJMWFySklleUFEc1JhQzNWNEoxeWJzSFNjcjNhL0FTd3pnZFIyeXlLUy83CkF3QkwK"
},
...
]
}
},
"status": 200,
"parameters":
[
...
],
"message": "ok",
}