Match Brand

Description

The match brand method for the product API provides an API frontent that enables the retrieval of a list of twenga brands.

A brand is the name (amongst other features) that distinguishes one seller's product from those of others. Examples: Apple, Sony, Levi's, Dolce & Gabbana, etc.

Use the Match Brand to retrieve the brand_id you need, i.e the Twenga internal brand references that you can then re exploit to refine your Search Offer calls.

API Call

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

Note: if you add more than one primary parameter to the call, they must make a coherent whole in order for you to get a list of offers. 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 no results.

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

The list of all parameters for the Match Brand 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 The keyword used to search brands (Blackberry, Whirlpool, Nike, ...)
category_id[] Primary Twenga internal reference for the brand categories, separated by commas.
brand_id[] Primary Twenga internal reference for the brands needed, separated by commas. If other primary parameters are filled in in the same Match brand call, they will be ignored.
nb_results No Number of brands 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 per brand in results. Example: you want only brands where at least 2 offers exist (2 sales proposals to buy the items with this brand). In that case, set min_offers to 2.

API Call Samples

GET : Querying the match brand service for keyword ‘Sony’
http://api.wtpn.twenga.co.uk/v2/match/brand?[...]&keyword=sony&nb_results=1

GET : Querying the match brand service for keyword ‘Sony’
http://api.wtpn.twenga.co.uk/v2/match/brand?[...]&keyword=sony&nb_results=1

JSON XML

{
   "code": 200,
   "infos": {
      "nb_tw_objects": 1
   },
   "tw_objects": [
      {
      "nb_results": 1,
      "confkey": "4fad3d414ce4c",
      "results": [
         {
         "name": "KitSound",
         "brand_id": 50333,
         "has_logo": false,
         "has_category": true,
         "categories": [
            {
               "name": "Audio headphones",
               "category_id": 136067,
               "twenga_url": null,
               "match_url": "http://demo.wtpn.twenga.co.uk/v2/match/category?cack=91b442b514c51f66f5e96bd37a51a60c31f1b5eb&e=eyJrIjoiNGU2ZTkxNDczYzUyOCIsImMiOiIxIiwibCI6IjE1IiwibyI6Impzb24ifQ%3D%3D&confkey=4fad3d414ce4c&category_id=136067"
            },
            {
               "name": "Hi-Fi",
               "category_id": 214,
               "twenga_url": null,
               "match_url": "http://demo.wtpn.twenga.co.uk/v2/match/category?cack=91b442b514c51f66f5e96bd37a51a60c31f1b5eb&e=eyJrIjoiNGU2ZTkxNDczYzUyOCIsImMiOiIxIiwibCI6IjE1IiwibyI6Impzb24ifQ%3D%3D&confkey=4fad3d414ce4c&category_id=214"
            },
            {
               "name": "MP3 and MP4 player",
               "category_id": 1472,
               "twenga_url": null,
               "match_url": "http://demo.wtpn.twenga.co.uk/v2/match/category?cack=91b442b514c51f66f5e96bd37a51a60c31f1b5eb&e=eyJrIjoiNGU2ZTkxNDczYzUyOCIsImMiOiIxIiwibCI6IjE1IiwibyI6Impzb24ifQ%3D%3D&confkey=4fad3d414ce4c&category_id=1472"
            },
            {
               "name": "iPhone accessories and parts",
               "category_id": 134990,
               "twenga_url": null,
               "match_url": "http://demo.wtpn.twenga.co.uk/v2/match/category?cack=91b442b514c51f66f5e96bd37a51a60c31f1b5eb&e=eyJrIjoiNGU2ZTkxNDczYzUyOCIsImMiOiIxIiwibCI6IjE1IiwibyI6Impzb24ifQ%3D%3D&confkey=4fad3d414ce4c&category_id=134990"
            }
         ]
         }
      ]
      }
   ]
}

<?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>Apple</name>
               <brand_id>24</brand_id>
               <has_logo>true</has_logo>
               <has_category>true</has_category>
               <logo>
                  <url>http://s0.c4tw.net/img/brands/24.png</url>
                  <width>87</width>
                  <height>26</height>
               </logo>
               <categories>
                  <category>
                     <name>Ordinateurs Apple</name>
                     <category_id>73963</category_id>
                     <twenga_url>http://www.twenga.fr/#&p=73963&u=p</twenga_url>
                     <match_url>http://demo.wtpn.twenga.fr/v2/match/category?cack=0f5e99fbeda053923a945d5a0be7619fc6652176&e=eyJrIjoiNGU2ZTkxNDczYzUyOCIsImMiOiI1IiwibCI6IjE1IiwibyI6InhtbCJ9&confkey=523ff8804d3fc&category_id=73963</match_url>
                  </category>
                  <category>
                     <name>Accessoires et pièces pour iPhone</name>
                     <category_id>134990</category_id>
                     <twenga_url>http://www.twenga.fr/#&p=134990&u=p</twenga_url>
                     <match_url>http://demo.wtpn.twenga.fr/v2/match/category?cack=0f5e99fbeda053923a945d5a0be7619fc6652176&e=eyJrIjoiNGU2ZTkxNDczYzUyOCIsImMiOiI1IiwibCI6IjE1IiwibyI6InhtbCJ9&confkey=523ff8804d3fc&category_id=134990</match_url>
                  </category>
               </categories>
            </result>
         </results>
      </tw_object>
   </tw_objects>
</root>

GET : Querying the match brand service for keyword "Samsung" with a specific category_id[]
http://api.wtpn.twenga.co.uk/v2/match/brand?[...]&keyword=samsung&nb_results=1&category_id=78103

GET : Querying the match brand service for the brand_id of Samsung
http://api.wtpn.twenga.co.uk/v2/match/brand?[...]&brand_id=226

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 (use the email indicated in the "Assistance" section or contact your account manager).

The infos parameter contains a list of information such as:

Generic parameters

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

  • 200: OK, data sent: 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 brands

The infos parameter contains a list of information such as:

  • nb_tw_objects: this is the number of containers for results: always one. Even if 0 offers are returned, there will be a tw_object.
  • tw_objects: It is the main results container.
  • nb_results: the number of brands sent Check this to verify that there is at least one brand.
  • 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 brands sent. Its format is defined below.

The output fo brand is split into different parts:

  • a. Global brand information
  • b. Logo information
  • c. Category information

The presence of a part depends on the brands. All brands have global information but sometimes for certain brands, some data are not available like, the category, etc. Example: if has_category: false, that means that the category name is not available.

a. Global information

The current version is 2.1.0. The following fields are always available for a brand.

Some are available for all versions, others not: please check the column Starting from version

Fields Starting from version Description
brand_id 1 Twenga internal brand reference.
name 1 Brand name. Examples: Apple, Sony, Levi's, Dolce & Gabbana, etc.
match_url 2.1 Match url to retrieve information on this particular brand
search_url 2.1 Search URL to retrieve directly the list of offers based on the brand provided by the Match Brand
has_logo 1 True returned if the brand has a logo
has_category 1 True returned if the brand has categorie(s)

b. Logo information

This corresponds to the logo of the brand. If a logo is available, you will have has_image: true.

If a logo exists, you will find the data in the logo field.

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

c. Category information

If the selected brand 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
search_url 2.1 Search URL to retrieve directly the list of offers based on the brand provided by the Match Brand