Product API

Note 1 : In order to use this solution :

  • You must be registered as a publisher on affinitAD. For further information please contact us.
  • Once registered, you will be provided with your own access to the preprod mode (your own API URL). This access is to be used for testing purposes only and helps you to validate your implementation of Twenga offers. Please make sure this implementation is compliant with Twenga User Guidelines
  • As soon as you are ready to use the prod mode (with the same API URL), please notify Twenga. Your implementation needs to be reviewed and approved before setting you live. It's just a simple technical and marketing certification

Note 2 : Any change or improvement the Product API will be indicated in the changelog.

Search Offer

1. Description

The Search Offer method for the Product API provides an API frontend to Twenga's offer catalogue.

An offer is a sales proposal for an identified item. It has specific terms & conditions, such as a defined price, a particular merchant, etc.

The Search Offer enables you to retrieve a list of the specific offers you want based on the parameters you defined.

Current version is :
2.1.0

2. API Call

In order to use the Search Offer 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 brand_id for apple "24", you will have no results.
  • For the keyword "skirt" and the category_id for Women's Skirts "138997, you will get no results.

In every instance, the quantity and quality of results depends on the quality of your calls. In particular, the keyword parameter must be e-commerce related. E-commerce is defined as all calls (or keywords) that correspond to products or references that lead to the act of purchase. More precisely, when reading the call, Twenga must be able to identify the intention to search for a physical e-commerce item. You can then expect to find relevant, converting offers in your API call results.

Examples of e-commerce keywords: 'Women's shorts', 'Samsung, 'Leather handbag', 'Clarks shoes', 'Christmas decorations' etc.

Examples of non-e-commerce keywords: 'Christmas' on its own (does not include the intention to look for or buy something), 'Godzilla' (same reasoning), 'Citroën' (very little conversion potential for automobiles on the web) etc.

A specific error code will be returned if the Product API considers a keyword as non-e-commerce.

The list of all parameters for the Search Offer 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.
keyword Primary Keyword used to search offers (ex. ipad, dresses, bed...)
category_id[] Primary Twenga internal identifier for an offer category. A category is the division in which ant offer is classified because it shares common characteristics with the other offers included in this category. Example of different lamp categories: Bedside lamp, Desk lamp, Clip lamp, etc. Use the Match Category to retrieve the category_id you need to refine your offer search by indicating a specific category.
Note: The call can be done with several categories.
Example: http://api.wtpn.twenga.co.uk/v2/search/offer[...]&category_id[]=139496&category_id[]=86820
brand_id Primary Twenga internal identifier for an offer brand. The 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 to refine your search by indicating a specific brand.
merchant_id Primary Twenga internal identifier for an offer merchant. The merchant is the person or the company that sells the item within the conditions described by the offer. Examples: Amazon, eBay, Asos etc. Use the Match Merchant to retrieve the merchant_id you need to refine your search by indicating a specific merchant.

API Call Samples

First sample:

GET : Querying the Offer service for keyword Skirt
http://api.wtpn.twenga.co.uk/v2/search/offer[...]&keyword=skirt&nb_offers=1

GET : Querying the Offer service for keyword Skirt
http://api.wtpn.twenga.co.uk/v2/search/offer[...]&keyword=skirt&nb_offers=1

JSON XML

"code": 200,
    "infos": {
        "info_code": 0,
        "nb_tw_objects": 1
    },
    "tw_objects": [
        {
            "nb_results": 1,
            "confkey": "4fad3d414ce4c",
            "results": [
                {
                    "name": "Samsung Galaxy Note 10.1 Tablet with Wi-Fi and 3G - Silver",
                    "description": "The Galaxy Note 10.1 is the perfect tablet for creative minds. With an embedded S Pen stylus, large 10.1 inch screen and integrated Adobe Photoshop software you can make notes, draw and sketch your ideas ready to share with others. Powered by a 1.4GHz quad core",
                    "click_url": "http://r.twenga.co.uk/g1.php?cp=VjYF3R_l6U9I5j18jEC9km8AMI2THjfDiXpddMMSOG3nx1eq_jvNCzRSgQeOEtDnncX6MJM_7uBih9kYqfDAHkG_F52J8c-62eGslZemc9FN6rRgTCRrZbqwRSIpzWR103mrW7GomEY4FpCMykW-5sF4g_q4lxBJL8Ok8R6hP7tr-xIxIW-xMA6TI85jOzqHLknB4JvG2a37IrqBOMe_8DRBNpRliHzxKZ6zIQiblfC1zTBRKq-riPKr9F1mrczo8ApnXURv0wcz-eBiwLvuMPmki11Rlinaf-khcr8jjpJWmyHxxhTy6be7OobwtqVgrt9iehgLDGk5RoHBnTuMVVJQZSQ3OqRG0y7RUOpkPhJr-0zlwdRpgvwdWUIRvG5kmYqjjd2RXg8QZrVlM3uRnLzqFiFtTbsImJKiWdlV9gGKYyT6Hzn6nm1kqv0-wDVEwm3Aw_NuF5Y6h3845AIWIbXT1o9u6AUHNOf4GEs5ZEtyyaQXM_st1XS9a4Tke8M2AVf6ZEPa0gbpaY3lEf6jn3NjgbLQg75IVPBFSXRiFl63jb6EMI0-LBz9Bk7z4vluGZWAUuo3tUXSXOLmysGxPWqBWfVjwhntFGpkL6bHKyIcFLlrCeXBRzyWj8AumEK1",
                    "has_image": true,
                    "has_merchant": true,
                    "has_brand": true,
                    "has_category": false,
                    "price": "£ 499.99",
                    "has_shipping_cost": true,
                    "shipping_cost": "£ 0.00",
                    "has_discount": false,
                    "image": {
                        "small": {
                            "url": "http://i30.twenga.com/tablet-pc/samsung-galaxy-note-10.1-tp_1832169280438475341.jpg",
                            "width": 100,
                            "height": 100
                        },
                        "medium": {
                            "url": "http://i30.twenga.com/tablet-pc/samsung-galaxy-note-10.1-tp_1832169280438475341b.jpg",
                            "width": 150,
                            "height": 150
                        },
                        "large": {
                            "url": "http://i30.twenga.com/tablet-pc/samsung-galaxy-note-10.1-tp_1832169280438475341vb.jpg",
                            "width": 290,
                            "height": 290
                        }
                    },
                    "merchant": {
                        "merchant_id": 42309,
                        "name": "Argos",
                        "match_url": "http://demo.wtpn.twenga.co.uk/v2/match/merchant?cack=91b442b514c51f66f5e96bd37a51a60c31f1b5eb&e=eyJrIjoiNGU2ZTkxNDczYzUyOCIsImMiOiIxIiwibCI6IjE1IiwibyI6Impzb24ifQ%3D%3D&confkey=4fad3d414ce4c&merchant_id=42309",
                        "has_logo": true,
                        "logo": {
                            "url": "http://s0.c4tw.net/1/42309.png",
                            "width": 87,
                            "height": 26
                        }
                    },
                    "brand": {
                        "brand_id": 226,
                        "name": "Samsung",
                        "match_url": "http://demo.wtpn.twenga.co.uk/v2/match/brand?cack=91b442b514c51f66f5e96bd37a51a60c31f1b5eb&e=eyJrIjoiNGU2ZTkxNDczYzUyOCIsImMiOiIxIiwibCI6IjE1IiwibyI6Impzb24ifQ%3D%3D&confkey=4fad3d414ce4c&brand_id=226",
                        "has_logo": false
                    }
                }
            ]
        }
    ]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <code>200</code>
   <infos>
      <info_code>0</info_code>
      <nb_tw_objects>1</nb_tw_objects>
   </infos>
   <tw_objects>
      <tw_object>
         <twenga_url>http://www.twenga.co.uk/samsung-mobile-phone-carrying-case.html</twenga_url>
         <nb_results>1</nb_results>
         <confkey>51b5c42bedf47</confkey>
         <results>
            <result>
               <name>Samsung Galaxy Note 3 S-View Case - Black</name>
               <description>For stylish coverage and protection, the black Samsung Galaxy Note 3 S-View Case has it all. Operate and check your Note 3 with the cover closed as it allows view-through access to alerts, status and other important information. Customise your wallpaper and mak</description>
               <click_url>http://r.twenga.co.uk/g1.php?cpz=RVDRTsMwDPwVlOduilOnTfo2tpcJIZBWPiAk6VbRtVmXIk2If8cJaLz57Dv7zl9sEwJrmOm6fuyjcaxgr_N0nM1571gDBdtOY5yNjRlyidR68jeSSEDQXlrLTYckew4u9kRiVdrxV4tSEtqezDj6gbDznVmGSL3D8p4Z_523ccgXd-kUKzUHLHWlldKCgFZE2bk8A6y0lEqBBIlclorXeXjwF9Zw2j0ts_WJiigKto_-_Nsi7dWb2Z6I_rj0g2uvySRdWnFcCfUAssGqKVOerYn-OM23tEZBJfCeI79CkdODvQeLYTShP13WwCsAkr98fE45TmLXWiOFAVGD4hqBk8n2FpKfNv2ij9ktaChrSE8PlkZ8zQX7_gE%2A</click_url>
               <has_image>true</has_image>
               <has_merchant>true</has_merchant>
               <has_brand>true</has_brand>
               <has_category>true</has_category>
               <price>£ 49.99</price>
               <has_shipping_cost>true</has_shipping_cost>
               <shipping_cost>£ 3.95</shipping_cost>
               <has_discount>false</has_discount>
               <image>
                  <small>
                     <url>http://i31.twenga.com/mobile-phone-carrying-case/samsung-galaxy-note-3-tp_799443912718094100.jpg</url>
                     <width>100</width>
                     <height>100</height>
                  </small>
                  <medium>
                     <url>http://i31.twenga.com/mobile-phone-carrying-case/samsung-galaxy-note-3-tp_799443912718094100b.jpg</url>
                     <width>150</width>
                     <height>150</height>
                  </medium>
                  <large>
                     <url>http://i31.twenga.com/mobile-phone-carrying-case/samsung-galaxy-note-3-tp_799443912718094100vb.jpg</url>
                     <width>290</width>
                     <height>290</height>
                  </large>
               </image>
               <merchant>
                  <merchant_id>42309</merchant_id>
                  <name>Argos</name>
                  <match_url>http://demo.wtpn.twenga.co.uk/v2/match/merchant?cack=576274328961f70185f036241b6970a6bcd01f8e&e=eyJrIjoiNTE0MTllNWNjMGFmNCIsImMiOiIxIiwibCI6IjE1IiwibyI6InhtbCJ9&confkey=51b5c42bedf47&merchant_id=42309</match_url>
                  <has_logo>true</has_logo>
                  <logo>
                     <url>http://s0.c4tw.net/1/42309.png</url>
                     <width>87</width>
                     <height>26</height>
                  </logo>
               </merchant>
               <brand>
                  <brand_id>226</brand_id>
                  <name>Samsung</name>
                  <match_url>http://demo.wtpn.twenga.co.uk/v2/match/brand?cack=576274328961f70185f036241b6970a6bcd01f8e&e=eyJrIjoiNTE0MTllNWNjMGFmNCIsImMiOiIxIiwibCI6IjE1IiwibyI6InhtbCJ9&confkey=51b5c42bedf47&brand_id=226</match_url>
                  <has_logo>true</has_logo>
                  <logo>
                     <url>http://s1.c4tw.net/img/brands/226.png</url>
                     <width>87</width>
                     <height>26</height>
                  </logo>
               </brand>
               <category>
                  <category_id>81624</category_id>
                  <name>Mobile phone protection</name>
                  <match_url>http://demo.wtpn.twenga.co.uk/v2/match/category?cack=576274328961f70185f036241b6970a6bcd01f8e&e=eyJrIjoiNTE0MTllNWNjMGFmNCIsImMiOiIxIiwibCI6IjE1IiwibyI6InhtbCJ9&confkey=51b5c42bedf47&category_id=81624</match_url>
                  <twenga_url>http://www.twenga.co.uk/#&p=81624&u=p</twenga_url>
               </category>
            </result>
         </results>
      </tw_object>
   </tw_objects>
</root>

3. 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 offers have been found for your call. This means that you can get the code 200 for a call return with offers or for a call returning 0 offers . 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 offers

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. Even if 0 offers are returned, there will be a tw_object.
  • tw_objects: It is the main results container.
  • confkey: 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 offers sent. Its format is defined below.

The output for offers is split into different parts:

  • a. Global information
  • b. Product information
  • c. Image information
  • d. Merchant information
  • e. Brand information
  • f. Category information

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

a. Global information

The following fields are always available for an offer.

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

Field Starting from version Description
item_id 2 This is the Twenga internal offer reference. Example: 1976607991699554600
name 1 The offer name that refers to the product. Example "White Leaves Print Skirt"
description 1 A detailed description of the product for this offer. Example "White Polyester Knee Length Pleated Street Print Skirts, size features are: Length: M:65cm, L:66cm"
click_url 1 Url you need to redirect when a click occurs
has_image 1 This field indicates that the image section exists below in the answer provided.
has_merchant 1 This field indicates that the merchant 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.
has_product 1 This field indicates that the product section exists below in the answer provided.
has_discount 1 This field indicates that the discount information exists below (in this Global information section). In that case, the discount percentage, the old_price and the old_price_raw are displayed.
has_shipping_cost 1 This field indicates that the shipping_cost information exists below (in this Global information section). In that case, the shipping_cost and the shipping_cost_raw are displayed.
price 1 The offer price. It is formatted: it means that the cents are separated by a comma and the currency symbol is displayed. Example: 129,95 €
price_raw 2 The offer price with only a full stop to separate the cents. Example: 129.95
currency 2 The currency for the price. Possible values are € and £.
old_price 2 If the offer includes a discount, this field appears. It indicates the price before the reduction. It is formatted which means that the cents are separated by a comma and the currency symbol is displayed. Example: 129,95 €
old_price_raw 2 If the offer includes a discount, this field appears. It indicates the price before the reduction. The amount is displayed with only a full stop to separate the cents. Example: 129.95
Discount 2 If the offer includes a discount, this field appears. It indicates the reduction percentage. Example: 20%
shipping_cost 1 The amount of fees for the delivery. It is formatted which means that the cents are separated by a comma and the currency symbol is displayed. Example: 6,50 €
shipping_cost_raw 2 The amount of fees for the delivery. The amount is displayed with only a full stop to separate the cents. Example: 6.5

b. Product information

If a product is identified on a certain offer (meaning has_product: true), more information is given in the product section:

  • product_id: Twenga internal product reference. Example: 717150
  • match_url: Match url to retrieve product information

c. Image information

This corresponds to an offer image. By default, all the offers 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 data in the image field.
This field 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, the following fields are provided.

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

d. Merchant information

You can also have merchant information if the has_merchant field is set to true.

In this case, a merchant field will contain related data.

Field Description
merchant_id Twenga internal merchant id. Example: "5802". If you need to see or search for a particular merchant_id, use the Match Merchant.
name Merchant name. Example: "Amazon.co.uk"
match_url Match url to retrieve merchant information
domain The merchant URL to go to his website. Example: http://www.amazon.co.uk/
has_logo True returned if the merchant 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

e. Brand information

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

Field Description
brand_id Twenga internal brand id. 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

f. Category information

If the selected offer 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 related page inside Twenga's website