What's new in v3?

Back to top

1. Products vs. Offers

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:

  1. A v2 product is now a v3 offer.
  2. A v2 product_group is now a v3 product.

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.

Back to top

2. Standard response structure

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:

  1. Response: All responses will be contained within a top level response container. This may contain attributes relating to the success or failure of the query.
    
    
        
        
        
        
    
    
    
    {
        "status": 200,
        "message": "ok",
        "parameters": [],
        "results": {},
        "resources": {},
        "filters": {}
    }
    
    
  2. Parameters: The parameters block is used to list all parameters that were used to build up the response information. This can be used for troubleshooting problems, as well as rebuilding links by knowing how you got to the information you are currently viewing.
    
    
        
        
        
        
        
        
    
      
    
    "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"
       }
    ]
      
  3. Results: This contains the primary information found using the parameters that were passed in to make the query. The results can contain different kinds of information such as products, deals, merchants, networks, etc. The type of information returned in the results is based on the resource being requested in the URL. You will find examples of this in the different API guides specific to that resource.
    
    
        
            
            
                
                    
                
            
        
    
    
    
    {
      "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"
                   }
               ]
            }
        }
    }
    
  4. Resources: A resource is an entity you wish to get information about. In the context of the v3 API we use this node to provide additional information about items contained in the results node. We do this to minimize the amount of information being duplicated in a response, while still providing all the information you need to build something on your end. An example of this is a merchant resource node being returned for a products call. If you do a product search looking for 'ipods' instead of re-listing all merchant information on every single product node, we provide a separate merchant node in the resources, and each product node provides a reference id to get to the merchant for information.
    
    
        
            
            ...
        
        
            
            
            
            ...
        
    
    
    
    {
       "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"
                   }
                ]
            }
        }
    }
    
  5. Filters: Filters show you options available to you for further refining the current search. These filters may be ranges for prices or percent offs, or maybe a reference to resources you could filter on.
    
    
        
        
        
            
                
                
                ...
            
        
        ...
    
    
    
    {
        "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"
                           }
                        ]
                    }
                }
            ]
        }
    }
    
Back to top

3. Parameter types

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
Back to top

4. Parameter kinds

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

5. Attribute types

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

6. Resources

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

7. A note about attributes

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.

Back to top

8. Session

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.

Back to top

9. JSON, and JSONP responses

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:

Optional request 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:

myCustomFunctionName({"results":...});

variable This will be the name of a variable you want assigned to the results. The response will take the format of:

var myCustomVariableName = {"results":...};

Note: If you pass both parameters the response will take the following format:


var myCustomVariableName = {"results":...}; myCustomFunctionName(myCustomVariable);