Match Product

Description

The match product method for the Product API provides an API frontend that enables the retrieval of a list of Twenga products.

A product is a item/good with a brand, an image and a category attached. Examples: the Iphone, the sports video camera GoPro, the Nespresso Coffee Machine, etc. A product does not have a price or a merchant linked to it (unlike an offer which is a sale proposal with a defined price and a merchant).

A product has specific offers associated inside Twenga catalog, in order to find those offers you just need to use the Search Offer call indicating the relevant Product_id (the Twenga internal product reference).

Use the Match Product to retrieve those product_ids, before building your Search Offer call.

Current version is:
2.1.0.

API Call

In order to use the Match Product method, you need to:

Note: if you add more than one primary parameter to the call, they must make a coherent whole. Examples:

  • For the keyword "skirt" and the category_id for computers "8", you will have no results.
  • For the keyword "skirt" and the category_id for Women's Skirts "138997”, you will get results.

A Match Product call with the primary parameter product_id filled in can be used to consult the detailed information of a particular product. If other primary parameters are filled in in the same Match Product call, they will be ignored.

The list of all parameters for the Match Product Method is the following one:

Parameter Mandatory Description
cack Yes This parameter, used internally for tracking and control, is provided by your account manager or the affinitAD support team. To receive it, please contact us.
e Yes This parameter, used internally for tracking and control, is provided by your account manager or the affinitAD support team. To receive it, please contact us.
confkey Yes Your configuration key. This parameter, used internally for tracking and control, is provided by your account manager or the affinitAD support team. To receive it, please contact us.
keyword Primary Keyword used to search products (ipad, Samsung, chromebook, leather handbags ...)
category_id[] Primary Twenga internal reference for the product categories, separated by commas.
product_id[] Primary Twenga internal reference for the products needed, separated by commas. If other primary parameters are filled in in the same Match product call, they will be ignored.
nb_results No Number of products you would like to receive. The default number is 10 and the maximum number is 50. If you set a value that is higher than 50, you’ll get 50 results.
min_offers No Minimum number of offers associated to the product. Example: you want only products where at least 2 offers exist (2 sales proposals). In that case, set min_offers to 2.
sort_by No You can sort results (products) by the price of its associated offers ("price_desc" or "price_asc"), relevance or popularity ("top_offers").

API Call Samples

GET : Querying the match product service for keyword iPAD
http://api.wtpn.twenga.co.uk/v2/match/product?[...]&nb_results=1

GET : Querying the match product service for keyword iPAD
http://api.wtpn.twenga.co.uk/v2/match/product?[...]&nb_results=1

JSON XML

{
"code": 200,
"infos": {
  "nb_tw_objects": 1
},
"tw_objects": [
  {
  "nb_results": 1,
  "confkey": "4fad3d414ce4c",
  "results": [
     {
        "name": "iPad mini",
        "product_id": 33067361,
        "has_image": true,
        "has_brand": true,
        "has_category": true,
        "nb_offers_new": 35,
        "nb_offers_used": 0,
        "brand": {
           "name": "Apple",
           "brand_id": 24,
           "has_logo": true,
           "match_url": "http://demo.wtpn.twenga.co.uk/v2/match/brand?cack=91b442b514c51f66f5e96bd37a51a60c31f1b5eb&e=eyJrIjoiNGU2ZTkxNDczYzUyOCIsImMiOiIxIiwibCI6IjE1IiwibyI6Impzb24ifQ%3D%3D&confkey=4fad3d414ce4c&brand_id=24",
           "logo": {
              "Url": "http://s0.c4tw.net/img/brands/24.png",
              "Width": 87,
              "Height": 26
           }
        },
        "category": {
           "name": "Apple computers & accessories",
           "category_id": 73963,
           "twenga_url": null,
           "match_url": "http://demo.wtpn.twenga.co.uk/v2match/category?cack=91b442b514c51f66f5e96bd37a51a60c31f1b5eb&e=eyJrIjoiNGU2ZTkxNDczYzUyOCIsImMiOiIxIiwibCI6IjE1IiwibyI6Impzb24ifQ%3D%3D&confkey=4fad3d414ce4c&category_id=73963"
        },
        "image": {
           "small": {
           "url": "http://i00.twenga.com/ipad/apple-ipad-mini-p_33067361.jpg",
           "width": 100,
           "height": 100
           },
           "medium": {
              "url": "http://i00.twenga.com/ipad/apple-ipad-mini-p_33067361b.jpg",
              "width": 150,
              "height": 150
           },
           "large": {
              "url": "http://i00.twenga.com/ipad/apple-ipad-mini-p_33067361vb.jpg",
              "width": 290,
              "height": 290
           }
        }
     }
  ]
  }
]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
<code>200</code>
<infos>
  <nb_tw_objects>1</nb_tw_objects>
</infos>
<tw_objects>
  <tw_object>
     <nb_results>1</nb_results>
     <confkey>523ff8804d3fc</confkey>
     <results>
        <result>
           <name>iPad mini</name>
           <product_id>33067361</product_id>
           <has_image>true</has_image>
           <has_brand>true</has_brand>
           <has_category>true</has_category>
           <nb_offers_new>519</nb_offers_new>
           <nb_offers_used>73</nb_offers_used>
           <brand>
              <name>Apple</name>
              <brand_id>24</brand_id>
              <has_logo>true</has_logo>
              <match_url>http://demo.wtpn.twenga.co.uk/v2/match/brand?cack=0f5e99fbeda053923a945d5a0be7619fc6652176&e=eyJrIjoiNGU2ZTkxNDczYzUyOCIsImMiOiI1IiwibCI6IjE1IiwibyI6InhtbCJ9&confkey=523ff8804d3fc&brand_id=24</match_url>
              <logo>
                 <url>http://s0.c4tw.net/img/brands/24.png</url>
                 <width>87</width>
                 <height>26</height>
              </logo>
           </brand>
           <category>
              <name>Apple computers & accessories</name>
              <category_id>73963</category_id>
              <twenga_url>http://www.twenga.co.uk/#&p=73963&u=p</twenga_url>
              <match_url>http://demo.wtpn.twenga.co.uk/v2/match/category?cack=0f5e99fbeda053923a945d5a0be7619fc6652176&e=eyJrIjoiNGU2ZTkxNDczYzUyOCIsImMiOiI1IiwibCI6IjE1IiwibyI6InhtbCJ9&confkey=523ff8804d3fc&category_id=73963</match_url>
           </category>
           <image>
              <small>
                 <url>http://i00.twenga.com/ipad/apple-ipad-mini-p_33067361.jpg</url>
                 <width>100</width>
                 <height>100</height>
              </small>
              <medium>
                 <url>http://i00.twenga.com/ipad/apple-ipad-mini-p_33067361b.jpg</url>
                 <width>150</width>
                 <height>150</height>
              </medium>
              <large>
                 <url>http://i00.twenga.com/ipad/apple-ipad-mini-p_33067361vb.jpg</url>
                 <width>290</width>
                 <height>290</height>
              </large>
           </image>
        </result>
     </results>
  </tw_object>
</tw_objects>
</root>

GET : Querying the match product service for keyword Notebook

http://api.wtpn.twenga.co.uk/v2/match/product?[...]&keyword=notebook&nb_results=3

GET : Querying the match product service for the product_id of ‘Lightning to USB Cable’
http://api.wtpn.twenga.co.uk/v2/match/product?[...]&product_id=33149071

Output format

The output format is set by the affinitAD support team based on the contract and technical implementation requirements.
The default output format is json. The xml format is also available: should you require this, please send us a request or contact your account manager.

Generic fields

The code field is the first field to check.
Its possible values are:

  • 200: OK, data sent: This code is returned when no error has occurred, even if 0 results have been found for your call This means that you can get the code 200 for a call return with products or for a call returning 0 products.
  • if offers are found for your call, they are displayed. If no offers are found, 0 offers are returned.
  • 503: NOK, an error occurred: a specific error code is displayed in that case.

Retrieving a list of products

The infos field contains a list of information such as:

  • nb_tw_objects: this is the number of containers of the results and it is always set to one. this is the number of containers for results: always one. Even if 0 offersproducts are returned, there will be a tw_object.
  • tw_objects: It is the main results container.
  • nb_results: the number of products sent Check this to verify that there is at least one product.
  • confkey: Your configuration key. This parameter, used internally for tracking and control, is provided by your account manager or the affinitAD support team. To receive it, please contact us.
  • results: the list of products sent. Its format is defined below.

The output for product is split into different parts:

  • a. Global item information
  • b. Brand information
  • c. Category information
  • d. Image information

The presence of a part depends on the products. All products have global information but sometimes for certain products, some data may not be available like the brand, etc. Example: if has_brand: false, that means that the brand name is not available.

a. Global information

The following fields are always available for a product. Some are available for all the versions, others not: please check the "Starting from version" column (the current version is 2.1.0.)

Fields Starting from version Description
name 1 Product name. Example "White Leaves Print Skirt"
description 1 A detailed description of the product. Example "White Polyester Knee Length Pleated Street Print Skirts, size features are:Length: M:65cm, L:66cm"
product_id 1 Twenga internal reference for the product. A product is the item/good with no price or merchant attached (since it is not a sale proposal). Examples: the Iphone, the sports video camera GoPro, the Nespresso Coffee Machine, etc.
has_image 1 This field indicates that the image section exists below in the answer provided.
has_brand 1 This field indicates that the brand section exists below in the answer provided.
has_category 1 This field indicates that the category section exists below in the answer provided.
nb_offers_new 1 Number of offers that exist for this product, in a brand new condition.
nb_offers_used 1 Number of offers that exist for this product, in a second-hand condition.
search_url 2.1 Search URL to retrieve directly the list of offers based on the product provided by the Match Product.

b. Brand information

The has_brand parameter is set to true if a brand is identified and available in the Twenga catalogue for the product.
In this case, a brand field will contain the brand related data.

Field Description
brand_id Twenga internal brand reference. If you need to see or search for a particular brand_id, use the Match brand.
name Brand name. Examples: Apple, Sony, Levi's, Dolce & Gabbana, etc.
match_url Match url to retrieve brand information.
has_logo True returned if the brand has a logo.
logo Exists if has_logo is set to true. In that case, these fields are dsplayed:
  • url: logo URL
  • width: logo width
  • height: logo height

c. Category information

If the selected product is included in one or several categorie(s), the has_category parameter is set to true and a category field will display the category data.

Field Description
category_id Twenga internal category reference. If you need to see or search for a particular category_id, use the Match category.
name Category name. Examples: Bedside lamp, Desk lamp, Clip lamp, etc.
match_url Match url to retrieve category information.
twenga_url Link to the category inside Twenga’s website.

d. Image information

This corresponds to a product image. By default, all the products returned in the output have an image: meaning that normally you should always have has_image: true. If an image is available, you will find the related data in the image field.
This field gives you three different sizes for the image, so you can choose which one you prefer.

If an image exists, you will find the data in the image parameter.
This parameter gives you three different sizes for the image, so you can choose which one you prefer.

The different sizes are (in pixels):

  • small: 100×100
  • medium: 150×150
  • large: 290×290

For each of these sizes, these fields are provided:

  • url: image URL
  • width: image width
  • height: image height