Products API

Overview

The Products API lets you access advertisers' product data through a REST API. As soon as you are connected to advertisers through Tradedoubler, you can access their products. All data is searchable and filterable.

The API allows you as a publisher to:

• Access fresh product data from top European advertisers.
• Query the information with powerful search functionality.
• Find the best price on a product.
• Retrieve structured information about millions of products.
• Download advertiser raw data.
• Build rich widgets with product data.

Do not have a publisher account? Register with Tradedoubler and get started today!

This documentation is intended for publishers. If you are an advertiser, go to the corresponding advertiser documentation.

Authentication

In order to access the Products API, you need a publisher account with Tradedoubler. Signing up for an account takes approximately 2 minutes by filling out this form.

Once you have an account and a site, you can pick up your unique token by logging on and going to "Account" > "Manage tokens". The token for Products API is under the system "PRODUCTS".

Tokens are 40 character hexadecimal SHA-1 strings.

CORS

The domain api.tradedoubler.com is CORS enabled, meaning that you can use client side XMLHttpRequest without getting cross-domain security issues.

Please note however that CORS is not yet fully implemented in all browsers, so you may want to go for JSONP for client side requests.

Matrix syntax

All services in Tradedoubler APIs use the matrix syntax .

However, top level and service irrelevant information is sent as regular URL parameters. Usually, these are token and jsonp.

Search service

This is the main search service of Products API. Use it to query the API for products.

The syntax of the search service is:

HTTP[S] GET http://api.tradedoubler.com/1.0/products[.xml|.json|empty][query keys]?token={token}[&jsonp=myCallback]

If you want your response as XML, simply add .xml as extention.

Query keys

You can add a query to your request if you want to filter the results. All data may not be available on products.

Example requests

Get all available products in JSON:

HTTP[S] GET http://api.tradedoubler.com/1.0/products?token={token}

Get products matching "laptop" in XML:

HTTP[S] GET http://api.tradedoubler.com/1.0/products.xml;q=laptop?token={token}

Get Weetos products costing at least £200 with price history enabled:

HTTP[S] GET http://api.tradedoubler.com/1.0/products;brands=Weetos;priceHistory=true;pricemin=200?token={token}

Get five football related products in a pretty JSON format with grouping enabled:

HTTP[S] GET http://api.tradedoubler.com/1.0/products;groupoffersbyproduct=true;pretty=true;limit=5;q=football?token={token}

Response expectations

As a response to your request, you can expect some of the following data. Please note that not all data is present for all products.

*Either tdCategoryName or name is always present.

JSON response

This is an example of a JSON response. It contains one product with lots of information.

{
  "productHeader" : {
    "totalHits" : 1
  },
  "products" : [ {
    "name" : "Symantec pcAnywhere Host & Remote - (versie 12.5 ) - volledig pakket - 5 gebruikers - CD - Linux, Win - International",
    "productImage" : {
      "url" : "http://snpi.dell.com/snp/images/products/mlrg/nl-nl~A6854908/A6854908.jpg"
    },
    "language" : "sv",
    "description" : "Symantec pcAnywhere is een uitgebreide, veilige oplossing voor remote besturing en beheer die is voorzien van functies voor het doorgeven van bestanden, zodat helpdesk- en supportkwesties snel kunnen worden opgelost, ook over meerdere platforms. De invitation-functie voor gateways en hosts is een oplossing voor typische connectiviteitsproblemen waarmee organisaties en het MKB mee te maken krijgt die meerdere remote apparaten ondersteunen. Doordat de gateway-functie de detectie van en de veilige verbinding met meerdere apparaten achter een firewall of NAT (Network Address Translation) in real time mogelijk maakt, kunnen helpdeskmedewerkers sessies met eindgebruikers initiëren,",
    "identifiers" : {
      "sku" : "A6854908"
    },
    "fields" : [ {
      "name" : "ManufacturerID",
      "value" : "14530209"
    }, {
      "name" : "HomeDelivery",
      "value" : "Yes"
    }, {
      "name" : "StaticSKU",
      "value" : "A6854908nlnl"
    }, {
      "name" : "VendorCode",
      "value" : "93"
    }, {
      "name" : "CategoryID",
      "value" : "5243"
    }, {
      "name" : "VendorName",
      "value" : "Symantec Corporation"
    }, {
      "name" : "Channel",
      "value" : "bsd"
    }, {
      "name" : "ArticleID",
      "value" : "14530209"
    } ],
    "offers" : [ {
      "feedId" : 8976,
      "productUrl" : "http://pdt.tradedoubler.com/click?a(2038177)p(41305)product(519de2b6e4b00d36c4c7e7c0)ttid(3)url(http%3A%2F%2Fwww.rf.nl%2Fdellspider%2Fredir.asp%3Fc%3Dnl%26l%3Dnl%26a%3Dbsd%26ProductID%3DA6854908%26redir%3Dhttp%253A%252F%252Flt%252Edell%252Ecom%252Flt%252Flt%252Easpx%253FCID%253D6511%2526LID%253D167791%2526DGC%253DAF%2526DGSeg%253DBSD%2526ACD%253D%5Btd_guid%5D%2526AID%253D%5Btd_affiliate_id%5D%2526DURL%253DDestinationURL)",
      "priceHistory" : [ {
        "price" : {
          "value" : "617.28",
          "currency" : "EUR"
        },
        "date" : 1378557168050
      } ],
      "modified" : 1381505376751,
      "availability" : "In Stock",
      "deliveryTime" : "Gebruikelijke verzending in: + 3 weken",
      "condition" : "New",
      "shippingCost" : "Kostenlos",
      "sourceProductId" : "A6854908nlnl",
      "programName" : "Wanten testzzzzzzzzzz",
	"id" : "519de2b6e4b00d36c4c7e7c0",
	"sourceProductUrl" : "https://accessories.euro.dell.com/sna/productdetail.aspx?c=nl&l=nl&s=bsd&cs=nlbsdt1&sku=A6854908"
    } ],
    "categories" : [ {
      "name" : "Software en downloads - Zakelijk & kantoor"
    } ]
  } ]
}

JSONP

If you defined the jsonp key in your query (for example jsonp=myCallbackFunction), the API will return a Javascript document with the result as an array in a function named as the callback:

function myCallbackFunction(result, statusCode, message)

JSONP callback function argument definitions:

If you did not define the jsonp key, the API will return actual JSON with Content-Type: application/json.

XML response

This is the same product as above, formatted as XML:

<result version="3.0" xmlns:ns2="urn:com:tradedoubler:pf:model:xml:common" xmlns="urn:com:tradedoubler:pf:model:xml:output">
    <productHeader>
        <totalHits>1</totalHits>
    </productHeader>
    <products>
        <product language="sv">
            <ns2:name>Symantec pcAnywhere Host & Remote - (versie 12.5 ) - volledig pakket - 5 gebruikers - CD - Linux, Win - International</ns2:name>
            <ns2:description>Symantec pcAnywhere is een uitgebreide, veilige oplossing voor remote besturing en beheer die is voorzien van functies voor het doorgeven van bestanden, zodat helpdesk- en supportkwesties snel kunnen worden opgelost, ook over meerdere platforms. De invitation-functie voor gateways en hosts is een oplossing voor typische connectiviteitsproblemen waarmee organisaties en het MKB mee te maken krijgt die meerdere remote apparaten ondersteunen. Doordat de gateway-functie de detectie van en de veilige verbinding met meerdere apparaten achter een firewall of NAT (Network Address Translation) in real time mogelijk maakt, kunnen helpdeskmedewerkers sessies met eindgebruikers initiëren,</ns2:description>
            <ns2:productImage>http://snpi.dell.com/snp/images/products/mlrg/nl-nl~A6854908/A6854908.jpg</ns2:productImage>
            <ns2:categories>
                <ns2:category name="Software en downloads - Zakelijk &amp; kantoor"/>
            </ns2:categories>
            <ns2:fields>
                <ns2:field name="ManufacturerID">14530209</ns2:field>
                <ns2:field name="HomeDelivery">Yes</ns2:field>
                <ns2:field name="StaticSKU">A6854908nlnl</ns2:field>
                <ns2:field name="VendorCode">93</ns2:field>
                <ns2:field name="CategoryID">5243</ns2:field>
                <ns2:field name="VendorName">Symantec Corporation</ns2:field>
                <ns2:field name="Channel">bsd</ns2:field>
                <ns2:field name="ArticleID">14530209</ns2:field>
            </ns2:fields>
            <ns2:sku>A6854908</ns2:sku>
            <offers>
                <offer dateFormat="epoch" modifiedDate="1381505376751" sourceProductId="A6854908nlnl" id="519de2b6e4b00d36c4c7e7c0">
                    <ns2:feedId>8976</ns2:feedId>
                    <ns2:productUrl>http://pdt.tradedoubler.com/click?a(2038177)p(41305)product(519de2b6e4b00d36c4c7e7c0)ttid(3)url(http%3A%2F%2Fwww.rf.nl%2Fdellspider%2Fredir.asp%3Fc%3Dnl%26l%3Dnl%26a%3Dbsd%26ProductID%3DA6854908%26redir%3Dhttp%253A%252F%252Flt%252Edell%252Ecom%252Flt%252Flt%252Easpx%253FCID%253D6511%2526LID%253D167791%2526DGC%253DAF%2526DGSeg%253DBSD%2526ACD%253D%5Btd_guid%5D%2526AID%253D%5Btd_affiliate_id%5D%2526DURL%253DDestinationURL)</ns2:productUrl>
					<ns2:programName>Wanten testzzzzzzzzzz</ns2:programName>
					<ns2:sourceProductUrl>https://accessories.euro.dell.com/sna/productdetail.aspx?c=nl&l=nl&s=bsd&cs=nlbsdt1&sku=A6854908</ns2:sourceProductUrl>
                    <priceHistory>
                        <ns2:price dateFormat="epoch" date="1378557168050" currency="EUR">617.28</ns2:price>
                    </priceHistory>
                    <ns2:availability>In Stock</ns2:availability>
                    <ns2:deliveryTime>Gebruikelijke verzending in: + 3 weken</ns2:deliveryTime>
                    <ns2:condition>New</ns2:condition>
                    <ns2:shippingCost>Kostenlos</ns2:shippingCost>
                </offer>
            </offers>
        </product>
    </products>
</result>

To get your response as XML, add xml as extension products.xml.

XML schemas

XSD files for the output format are available here:

CSV export

You may wish to export the results in CSV rather than JSON or XML. To do so, you need to modify the search service syntax as follows:

HTTP[S] GET http://api.tradedoubler.com/1.0/products[.xml|.json|empty][format=csv][csvSeparators][csvEmbrace][csvFlattenFields][query keys]?token={token}

CSV separators

Take this example of product data:

...
"categories" : [
	{
	  "name" : "Electronics",
	  "tdCategoryName" : "Electronics",
	  "id" : 40
	},
	{
	  "name" : "Projectors",
	  "tdCategoryName" : "Projectors",
	  "id" : 62
	}
]
...

The above extract shows a product with two categories (Electronics and Projectors). The separators are as follows:

• Categories - On line seven, after the closing } a comma is used to separate the first value of 'categories' from the second.
• Category - Within each category there are multiple attributes and values. Each attribute is seprated by a comma (e.g. at the end of lines four and five).
• Attribute - Attibutes are separated from their value with a semi-colon (e.g. "attribute" : "value").

Example requests

Use " as the embrace character, |:; as the separators and flatten the fields:

HTTP[S] GET http://api.tradedoubler.com/1.0/products;format=csv;fid=9612;csvSeparators=%7C%3A%3B;csvEmbrace=%22;csvFlattenFields=true?token={token}

Use " as the embrace character, ,;: as the separators and do not flatten the fields (these are all default setting so they do not need to be listed) :

HTTP[S] GET http://api.tradedoubler.com/1.0/products;format=csv;fid=9612;?token={token}

Limitations

Any search request is limited to a maximum of 1,000 products. That means that adding page=2;pageSize=1000 will not get any results since the cap has already been reached at page one.

Unlimited service

In addition to the search service, you can use the unlimited service to get all of your raw product data from a specific feed.

This service is intended to be used by technically advanced publishers who wish to save the data it their own database, and process it on their own.

Download Limit

In order to prevent excessive downloading of unchanged Unlimited files you are allowed to download each version of a file 3 times within a 24-hour window. If this threshold is exceeded the service will respond with http 429 – Too Many Requests, instead of providing the file. Here is a sample response for the same :

“code”: “429”,
“message”: “Request Quota exceeded. Feed has not been updated recently”

When a new version of a file is published you are immediately granted download permission again. You can use the endpoint Unlimited Last Updated service as described below to get the last updated time of a specific feed.

When an unlimited file is requested for the first time there is an initial grace period of 5 days from the download limit. During this period the limit does not apply so that you can experiment and ensure proper functionality of the integration.

The syntax of the unlimited service is:

HTTP[S] GET http://api.tradedoubler.com/1.0/productsUnlimited[.xml|.json|empty];fid={feedId}?token={token}[&jsonp=myCallback]

Query keys

These are the query keys available to unlimited requests:

Example requests

Get all products from feed ID 123 as JSON:

HTTP[S] GET http://api.tradedoubler.com/1.0/productsUnlimited;fid=123?token={token}

Unlimited feed last updated service

You can use the unlimited feed last updated service to get the last updated time for a specific feed.

It would be ideal to use this service before the unlimited search service. If the feed is not updated, you should avoid calling the unlimited search service for that feed.

This service is intended to be used by technically advanced publishers who wish to save the data it their own database, and process it on their own.

The syntax of the unlimited feed last updated service is:

HTTP[S] GET http://api.tradedoubler.com/1.0/productsUnlimited/lastUpdated[.xml|.json|empty];fid={feedId}?token={token}[&jsonp=myCallback]

Query keys

These are the keys you can use in your request:

Example request

Get last updated time for feed ID 123 as JSON:

HTTP[S] GET http://api.tradedoubler.com/1.0/productsUnlimited/lastUpdated.json;fid=123?token={token}

Example response

Response for feed ID 123 as JSON:

...
{
    "feedIds": [
        123
    ],
    "lastUpdatedTime": "2024-04-17T15:57:00.470742"
}
...

The above response shows last updated time for feed id 123. Below are the details for each response elements you can expect

• feedIds - a list of feed ids requested. Currently only one valid feed id is expected as part of the response as we are supporting only one feed id for each unlimited feed file.
• lastUpdatedTime - Time when an unlimited feed file was last updated in Tradedoubler system. The lastUpdatedTime support ISO-8601 formats and can be one of below formats:
• YYYY-MM-dd'T'HH:mm
• YYYY-MM-dd'T'HH:mm:ss
• YYYY-MM-dd'T'HH:mm:ss.SSS
• YYYY-MM-dd'T'HH:mm:ss.SSSSSS
• YYYY-MM-dd'T'HH:mm:ss.SSSSSSSSS

Categories Service

All products are mapped to a Tradedoubler category to ensure consistent naming conventions. The Categories service allows you to retrieve the Tradedoubler category tree together with the number of products available in each.

The category tree is available using the following syntax:

HTTP[S] GET http://api.tradedoubler.com/1.0/productCategories[.{json|xml|empty}][;language={language|empty}]?token={token}

These are the keys you can use in your request:

XML schema

An XSD file for the output format is available here:

Response

As a response to your request, you can expect the following information:

If a category has subcategories, these are presented as children in the JSON or XML.

Fetch JSON tree Click here to fetch the category tree in English as JSON:

Data not loaded

Fetch XML tree Click here to fetch the category tree in English as XML:

Data not loaded

Product feed service

The product feed service allows you to get general information about feeds connected with your token including name, status, number of products and unmapped categories.

The syntax of the productFeeds service is:

HTTP[S] GET http://api.tradedoubler.com/1.0/productFeeds{/feedId}[.xml|.json|empty]?token={token}[&jsonp=myCallback]

Query keys

These are the query keys available for productFeeds requests:

Example requests

Get all feeds as JSON:

HTTP[S] GET http://api.tradedoubler.com/1.0/productFeeds?token={token}

Get feed ID 123 as XML:

HTTP[S] GET http://api.tradedoubler.com/1.0/productFeeds/123.xml?token={token}

Filter feeds from program IDs:

HTTP[S] GET http://api.tradedoubler.com/1.0/productFeeds;programId=id1,id2;?token={token}

Response

Here is an example of a response in JSON:

{
  "feeds" : [ {
    "feedId" : 19750,
    "name" : "Carl Example Feed",
    "active" : true,
    "sendToNewPF" : false,
    "visible" : true,
    "currencyISOCode" : "GBP",
    "languageISOCode" : "sv",
    "secret" : false,
    "numberOfUnmappedCategories" : 0,
	"numberOfProducts" : 189905,
	"lastModifiedTime" : "2020-01-01T12:09:03.374+0200",
    "programs" : [ {
      "programId" : 231514,
      "name" : "Carl Example program UK"
    }, {
      "programId" : 228139,
      "name" : "Carl Example program SE"
    } ]
  }, {
    "feedId" : 20782,
    "name" : "Carl test",
    "active" : true,
    "sendToNewPF" : false,
    "visible" : true,
    "currencyISOCode" : "SEK",
    "languageISOCode" : "en",
    "secret" : false,
    "numberOfUnmappedCategories" : 7,
	"numberOfProducts" : 13727,
	"lastModifiedTime" : "2020-01-02T12:09:03.374+0200",
    "programs" : [ {
      "programId" : 50000,
      "name" : "Carl 50k party program"
    } ]
  } ]
}

Error management

When an error occurs in the API, we try to describe the problem in detail. Here are the available error messages.

Other than the above, you can get generic HTTP errors. These are described here by W3C

The most common HTTP errors are: