Match Merchant

Description

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

A merchant is the person or the company that sells the product within the conditions described by the offer. Examples: Amazon, eBay, Asos, etc.

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

API Call

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

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

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

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 Merchant call with the primary parameter merchant_id filled in can be used to consult the detailed information of a particular merchant. If other primary parameters are filled in in the same Match Merchant call, they will be ignored.

The list of all parameters for the Match Merchant 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 merchant (Amazon, eBay, Asos...)
category_id[] Primary Twenga internal reference for the merchant categories, separated by commas
merchant_id[] Primary Twenga internal reference for the merchants needed, separated by commas. If other primary parameters are filled in in the same Match Merchant call, they will be ignored.
nb_results No Number of merchants 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 merchant in results. Example: you want only merchants who propose at least 2 offers (2 sales proposals for each of these merchants). In that case, set min_offers to 2.

API Call Samples

GET : Querying the match merchant service for keyword ‘iPAD’ and category ‘Apple computers & accessories’
http://api.wtpn.twenga.co.uk/v2/match/merchant?[...]&keyword=iPad&nb_results=1&category_id=73963

GET : Querying the match merchant service for keyword iPAD and category Apple computers & accessories http://api.wtpn.twenga.co.uk/v2/match/merchant?[...]&keyword=iPad&nb_results=1&category_id=73963

JSON XML

{
   "code": 200,
   "infos": {
      "nb_tw_objects": 1
   },
   "tw_objects": [
      {
         "nb_results": 1,
         "confkey": "4fad3d414ce4c",
         "results": [
            {
               "name": "Bizrusonline",
               "merchant_id": 4903711,
               "domain": "http://www.bizrusonline.co.uk",
               "has_logo": true,
               "has_category": true,
               "logo": {
                  "url": "http://s0.c4tw.net/2/4903711.png",
                  "width": 87,
                  "height": 26
               },
               "categories": [
                  {
                  "name": "Video gaming",
                  "category_id": 1949,
                  "twenga_url": null,
                  "match_url": "http://demo.wtpn.twenga.co.uk/v2/match/category?cack=91b442b514c51f66f5e96bd37a51a60c31f1b5eb&e=eyJrIjoiNGU2ZTkxNDczYzUyOCIsImMiOiIxIiwibCI6IjE1IiwibyI6Impzb24ifQ%3D%3D&confkey=4fad3d414ce4c&category_id=1949"
                  }
               ]
            }
         ]
      }
   ]
}

<?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>eBay</name>
               <merchant_id>1419</merchant_id>
               <domain>http://www.ebay.fr</domain>
               <has_logo>true</has_logo>
               <has_category>false</has_category>
               <logo>
                  <url>http://s1.c4tw.net/2/1419.png</url>
                  <width>87</width>
                  <height>26</height>
               </logo>
            </result>
         </results>
      </tw_object>
   </tw_objects>
</root>

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

GET : Querying the match merchant service for merchant_id of Argos
http://api.wtpn.twenga.co.uk/v2/match/merchant?[...]&merchant_id=42309

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).

Generic parameters

The code parameter is the first parameter 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 merchants

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 is split into different parts:

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

The presence of a part depends on the merchants. All merchants have global information but sometimes for certain merchants, 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 merchant.

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

Fields Starting from version Description
merchant_id 1 Twenga internal merchant reference. Example: “5802”
name 1 Merchant name. Example: "Amazon.co.uk"
match_url 2.1 Match url to retrieve information on this particular merchant
search_url 2.1 Search URL to retrieve directly the list of offers based on the merchant provided by the Match Merchant
domain 1 The merchant URL to go to his website. Example: http://www.amazon.co.uk/
has_logo 1 True returned if the merchant has a logo
has_category 1 True returned if the merchant has categorie(s)

Logo information

This corresponds to the merchant logo. If a logo is available, you will have has_logo: true.

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

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

Category information

If the selected merchant 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 information on this particular category
twenga_url Link to the category inside Twenga's website
search_url Search URL to retrieve directly the list of offers based on the merchant & category provided by the Match Merchant