The v3 API introduces a new way of looking at information in the affiliate space. The previous version of the API focused on specific products being sold by individual merchants. This conforms to a traditional understanding of affiliate data feeds, and the information being provided in them. One feed per merchant and each row in that feed is a product sold by that merchant. What this doesn't account for is the real world use of this information in shopping comparison websites. Outside the context of an individual feed, a product is offered from many different merchants spanning multiple affiliate networks.
To better facilitate the creation of shopping comparison websites, v3 takes a slightly different approach by introducing the concepts of products and offers.
Product: A product is an item made by a manufacturer. This can be an ipod, a curling iron, a song, a surfboard, etc. You buy a product from one or more merchants.
Offer: An offer is a product being sold by a specific affiliate merchant. It has a specific price being offered by the merchant for the product, and a specific affiliate URL to link to the merchant page offering the product. An example of this would be an iPod is a product manufactured by Apple, but offered for sale from Buy.com, Newegg, pcRush.com, etc.
This is a significant change from the v2 api. But can be thought of simply in the following two rules:
We understand this is a significant change, but it provides a much cleaner approach to building a comparison site, and enables us to build a more robust API for you to interact with.
More detail can be found about the differences between products and offers in the Find products guide.
In the last version of the API, there were slight variations in the response structure being returned. This has been standardized for v3, and modified to add semantic meaning to information being returned. The response structure is similar for both our XML and JSON responses.
A response is now comprised of the following container nodes:
{
"status": 200,
"message": "ok",
"parameters": [],
"results": {},
"resources": {},
"filters": {}
}
"parameters":
[
{
"type": "item",
"value": "1",
"kind": "pagination",
"name": "page"
},
{
"type": "item",
"value": "20",
"kind": "pagination",
"name": "results_per_page"
},
{
"value": "ipod",
"kind": "query",
"name": "keyword"
},
{
"value": "false",
"kind": "control",
"name": "include_discounts"
},
{
"value": "{{account_key}}",
"kind": "account",
"name": "account"
},
{
"value": "{{catalog_key}}",
"kind": "catalog",
"name": "catalog"
}
]
{
"results":
{
"products":
{
"count": 119615,
"product":
[
{
"offer_count": "1",
"image_url_large": "http://images10.newegg.com/ProductImageCompressAll200/55-101-237-11.jpg",
"price_min": "439.95",
"category": "7231",
"price_max": "439.95",
"description": "See, hear, touch, everything that entertains you on one really great iPod. iPod touch lets you enjoy everything you love about an iPod, and then some. Watch your movies and TV shows on a brilliant 3.5-inch display. Use the revolutionary Multi-Touch interface to flick through your music in Cover Flow. And anytime you re itching for more entertainment, just tap iTunes to browse and buy on the fly. Music With room for up to 14,000 songs and up to 30 hours of audio playback time, iPod touch gives you nonstop musical entertainment* And the new Genius Mixes and Voice Control features add even more ways for you to experience your music. Genius Mixes Now the Genius feature is even more powerful. Introducing Genius Mixes. All you do is sync iPod touch to iTunes, and Genius automatically searches your library and finds songs that sound great together. Then it creates multiple mixes you ll love. These mixes are like channels programmed entirely with your music. Genius Playlists Say you re listening to a song on your iPod touch that you really like and want to hear other tracks that go great with it. Just tap the Genius icon. Genius automatically finds songs on your iPod touch that go great with your selected song and makes a Genius playlist for you. Voice Control You listen to music, and now your music listens to you. The new 32GB and 64GB iPod touch models feature Voice Control. So you can tell iPod touch to play songs from a specific playlist or artist. Or speak simple commands such as shuffle, pause, and next song. You can even ask for the name of the track that s currently playing (and hear iPod touch answer you). iTunes Part of what makes iPod touch so amazing is that iTunes is literally at your fingertips. A Wi-Fi connection and a quick tap are all it takes to get instant access to millions of songs and thousands",
"offers":
{
"count": 1,
"offer":
[
{
"price_merchant": "439.95",
"image_url_large": "http://images10.newegg.com/ProductImageCompressAll200/55-101-237-11.jpg",
"merchant": "230",
"condition": "new",
"sku": "9SIA0AJ0D42778",
"description": "Apple's iPod has revolutionized the way we buy and listen to music. Don't buy the whole album; just get the songs you want. Listening to an iPod is like having a commercial-free radio station that plays only the songs you choosea€|and they always take your requests! The iPod Touch takes the revolution into a new dimension, with the addition of WiFi and theatrical widescreen capabilities! The iPod Touch's stunning 3.5" multi-touch screen lets you navigate quickly through the intuitive menu system to any of your videos, photos, music, or audio books. The screen automatically re-orients itself, whichever way you're holding the iPod, so choose the view you want. Browse and download from the WiFi iTunes Store, surf the Web using Safari, search using Yahoo! or Google, or watch videos on YouTube, anywhere you have WiFi access! The Touch uses flash memory, which is stable under the worst vibrations. It's a perfect choice for the gym, motorcycling, or any other active pursuit! The Touch gives you up to 30 hours of m Height: 4.3" Width: 2.4" Depth: 0.33" Weight: 4.05 oz. Memory Type: Flash Memory Display Type: TFT Display Resolution: 320 x 480 Audio Formats: MP3/WAV/AAC/Audible/Apple Lossless/AIFF",
"price_retail": "439.95",
"name": "Apple MC008LL/A - iPod Touch 32GB (3rd Gen)",
"id": "92926853",
"currency_iso": "USD",
"url": "http://r.popshops.com/r/ejFhSXhXUVZ1aFUyWnJiYjRWNGdBYWNCOXNhd3VzRlkvdEJlZ21mcmNNb3pZVm9ra0U2bDRiTWdMNUV4CnVURE8K"
}
]
},
"name": "Apple MC008LL/A 32GB Generation 3 iPod Touch-Refurbished",
"brand": "25471",
"id": "2622072"
}
]
}
}
}
{
"resources":
{
"deal_types":
{
"count": 3,
"deal_type":
[
{
"count": "1",
"name": "Sale/Clearance",
"id": "4"
},
{
"count": "1",
"name": "Hot Product",
"id": "16"
},
{
"count": "1",
"name": "Free Shipping",
"id": "1"
}
]
},
"merchants":
{
"merchant":
[
{
"count": "79",
"name": "Vann's",
"logo_url": "http://www.popshops.com/img/public/l/0/0/0/25-1.jpg",
"id": "25",
"url": "http://r.popshops.com/r/ejFhSXhXUVZ1aFUyWnJiYjRWNGdBWnhXZGF5RkxuNG5saGFyUmd3UWp3Wm9xd0JZS2ZoLytYa0tSLzNFCnRySkQK"
}
]
}
}
}
...
{
"filters":
{
"filter":
[
{
"type": "selection",
"parameter": "merchant",
"resource": "merchant",
"name": "merchant"
},
{
"type": "selection",
"parameter": "brand",
"resource": "brand",
"name": "brand"
},
{
"type": "range",
"parameter": "price",
"name": "price",
"values":
{
"value":
[
{
"count": "119207",
"min": "1",
"max": "360"
}
]
}
}
]
}
}
There are distinct types of parameters you can use in the v3. The parameter type indicates a certain type of behavior for that parameter. You do not need to pass the parameter type, it is only used to indicate how a parameter can be used.
| Name | Description |
|---|---|
| item | Accepts individual values. Multiple delimited values are not allowed. |
| range | Accepts a single value for matching exactly, or min max values delimited with a dash '-' used for searching across a range of values. For example price=50-100, or percent_off=25. |
| selection | Accepts single or multiple values. Multiple values are delimited with a comma ','. For example: product=1 OR product=1,2,3 |
Parameter kinds describe how a parameter is going to be used within the search itself. Some are used to authenticate your account, others used to sort the results. You do not need to pass the parameter kind, it is only used to indicate how a parameter will be used.
| Name | Description |
|---|---|
| account | This is a parameter tying the results to your specific account. |
| control | Controls fundamental types of additional resources being returned in a response. |
| filter | A parameter used to constrain the results that will be searched within. |
| pagination | Parameters specifically altering number of results returned. Example: page=1&results_per_page=100 |
| query | A parameter used for any search comparison looking at textual information about products, categories, merchants, etc. |
| session | Stores data about the previous API call in order to provide consistent browsing mechanisms. |
| sort | Determines sort ordering for specific results returned. |
| value | This is a value being passed in to update a record within an account. |
| view | Alters attributes or nodes returned in a response. |
Attribute types are used to describe an attribute being returned for a specific result. It is an indication to you what type of data the attribute contains.
| Name | Description |
|---|---|
| count | A count of the number of results |
| display | A displayable value for a result |
| image | An image URL |
| price | A price related to a result |
| primary_key | This is a unique primary identifier for a result |
| redirect_url | An affiliate URL that will redirect through the network passing along any tracking information. |
| resource | This identifies an attribute that is an id for an associated resource that is found within the resources section of the response. |
A resource at it's simplest is an entity you wish to get information about. In the context of the v3 API we use this concept to return information on many different things. The following list of resources describe the common types of information you will encounter in v3 responses.
| Name | XML node name | Description |
|---|---|---|
| Attribute | attribute | An attribute for a product. Examples such as color, screen resolution, size, etc. |
| Attribute Group | attribute_group | A group of attributes within a specification |
| Brand | brand | The brand or manufacturer for a product. This is not available to be searched directly, but appears in product results. |
| Catalog | catalog | A collection of merchants and associated exclusion and constraints. |
| Category | category | Categories are used to classify products. |
| Country | country | Country the merchant operates within. This primarily influences the type of currency prices are provided in. This only exists as nodes and filters in other calls. |
| Deal | deal | A deal provided through an affiliate network for a specific merchant. Usually expressed as a percent off, dollar off, or some other special discount for a specific period of time. |
| Deal type | deal_type | A simple classification system for deals. These are essentially custom categories for deals |
| Filter | filter | A filter is a resource/attribute or other condition that another resource can be filtered by |
| Merchant | merchant | A merchant or store that is available through an affiliate network. The merchant provides offers for products. |
| Merchant type | merchant_type | A classification of a merchant itself, not necessarily it's products or offers |
| Network | network | An affiliate network with merchants available within Rakuten PopShops |
| Offer | offer | This represents an instance of a product being sold by a specific merchant. |
| Product | product | A product is physical good sold by one or more merchants. |
| Specification | specification | A specification contains attribute groups, and attributes describing the product in more detail. Usually these correspond to the categories the product belongs to. |
One thing to keep in mind when working with the API, is that we try to only bring back the information you need. So if an attribute, or node is empty, then it usually is not returned. Don't always count on an attribute or node on being there. If an attribute is guaranteed to always be there we will mark it as 'required' in the documentation.
A new parameter is being introduced in v3, 'session'. This parameter is basically a container for us to manage information about previous states of requests. This information is used to better populate the different filters and resources available in the current request, allowing for you to build better navigation for any final user of your information.
For example, by passing the session parameter value we give to you, a subsequent request would know the price ranges that were available on the previous call, and would be able to inject those values back into the results for you to provide a fantastically better browsing experience for your user.
If you prefer working with JSON, you can also make api calls and request a ".json" format for the response. For example, http://api.popshops.com/v3/merchant_types.json?account=d1lg0my9c6y3j5iv5vkc6ayrd
JSONP - We also provide JSONP responses so you don't run into any cross-domain issues (google it). You don't need to change the format extension, you can leave it ".json", but you will need to use one or both of the following parameters:
| Parameter name | Description |
|---|---|
| callback | This is the name of a function that will be returned, with the response object being passed as a parameter to the function. The response will take the format of:
|
| variable | This will be the name of a variable you want assigned to the results. The response will take the format of:
|
Note: If you pass both parameters the response will take the following format:
var myCustomVariableName = {"results":...}; myCustomFunctionName(myCustomVariable);