Products Open API

Programmatically access fresh product data from Tradedoubler advertisers.

Overview

The Products Open 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 to Tradedoubler and get started today!


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

Demo website

This demo website is based on the Tradedoubler Products Open API. You simply search among products which are presented in a nice Bootstrap manner. Check it out for inspiration.

Authentication

In order to access the Products Open 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 Open API is under the system "PRODUCTS".

Examples in this document use {token} as placeholder to where you should place your token when building a request.

Also on the Manage tokens page, you will find your Voucher related tokens. Read more about the Vouchers Open API here.

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 Open API 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 Open 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.

Name Description Type Multiple
token Your unique token, identifying you. This is the only required key. String No
q Generic keyword search. Matches intelligently against title and description. String Yes
fid Search among feed IDs. Integer Yes
currency Matches against the currency of products. String No
minPrice Search for products with a minimum price. Float No
maxPrice Search for products with a maximum price. Float No
minUpdateDate Search for products updated after a certian point in time. Date No
maxUpdateDate Search for products updated before a certian point in time. Date No
tdCategoryId Matches against the Tradedoubler category ID Integer Yes
category Matches against the advertiser category name String Yes
brand Matches against the brand of products String Yes
spId Matches against the advertiser product ID. String Yes
tdId Matches against the Tradedoubler ID of products String Yes
ean Matches against the european article number of products String Yes
mpn Matches against the manufacturer part number of products String Yes
sku Matches against the stock keeping unit of products String Yes
upc Matches against the universal part number of products String Yes
isbn Matches against the international standard book number of products String Yes
language Matches against the language of the feed containing products String No
field Search among custom information on a product. For example field=colour%3Dblack String No
orderBy Set the order in which products are returned. Choose between priceAsc, priceDesc, modificationDateAsc and modificationDateDesc. String No
page Which page of result to return, given limit and pageSize is set. Integer No
pageSize The maximum number of items to return. Integer No
limit Global limit of the returned document. Set to pageSize*page+pageSize in order to use pagination. Integer No
groupOffersByProduct Set to true if you want the same product from different advertisers to be grouped. Boolean No
priceHistory Set to true to enable price history which gives you a list of previous prices for products. Boolean No
dateOutputFormat Set to iso8601 to use ISO8601 dates, otherwise dates will be output as unix time in milliseconds. String No
availability Matches against the availability of products String Yes
minInStock Miminum number of products in stock. Integer No
maxInStock Maximum number of products in stock. Integer No
condition Matches against the condition of products String Yes
model Matches against the model of products String Yes
manufacturer Matches against the manufacturer of products String Yes
shippingCost Matches against the shipping cost of products String Yes
promoText Matches against the promoText of products String Yes
warranty Matches against the warranty of products String Yes
deliveryTime Matches against the delivery time of products String Yes
weight Matches against the weight of products String Yes
size Matches against the size of products String Yes
techSpec Matches against the technical specification of products String Yes
pretty Set to true for nice line breaks in the output. Boolean No
jsonp If you are requesting JSON, you can define a callback name. The API will return a Javascript document with the result as an array in a function named as the callback. String No
Manifold: If you want to enter multiple values for a key, use either one key for each value brands=Cheerios&brands=Weetos or comma separate values brands=Cheerios,Weetos. Make sure that the key really support multiple values first.

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.

Name Description Type Required
name Title of the product String Yes
description A long description of the product. String Yes
imageUrl An URL to an image of the product. May contain width and height. String Yes
categories Categories of the product. tdCategoryName is Tradedoubler's category name, tdCategoryId is Tradedoubler's category ID and name is the your category name. String Yes*
feedId Primary key of the feed owning the product. Integer Yes
productUrl URL to the product. Use this to link to the product and earn commission. If publisher token is used, the product URL is prefixed with Tradedoubler's tracker URL. String Yes
programname Name of the program of the feed this product belongs to. String Yes
programlogo Url to the logo of the program of the feed this product belongs to. String No
price Price of the product. Currency is picked up from your affiliate program. Float Yes
sourceProductId Your identifier of the product. String Yes
modified Date of the last modification in ISO-8601 or unix time depending on the dateOutputFormat parameter. For example 2012-12-24T15:00+0100 or 1356357600000 Date Yes
id Tradedoubler's internal identifier of the product. May be used as GUID. String Yes
groupingId The identifier Tradedoubler use to group this product. String Yes
ean International article number of the product. Used for grouping and can be used as product identifier. Integer No
sku Stock-keeping unit of the product. Used for grouping and can be used as product identifier. String No
upc Universal Product Code. Used for grouping and can be used as product identifier. String No
isbn International Standard Book Number. Used for grouping and can be used as product identifier. String No
mpn Manufacturer part number. Used for grouping and can be used as product identifier. String No
availability Information on the availablity of the product. String No
inStock Number of items you have in stock. Integer No
condition Condition of the product. For example used or new. String No
brand Brand of the product. For example "Apple". String No
model The product's model. For example "iPhone" String No
manufacturer Manufacturer of the product. For example "Samsung" String No
shippingCost Cost of getting the product delivered. For example "Free" or "11.95". String No
shortDescription Description of the product in fewer words. String No
promoText Promotional text of the product String No
warranty Warranty information about the product String No
deliveryTime The amount of time it takes to get the product delivered. String No
weight Weight of the product. String No
size Size of the product. String No
techSpecs Technical specification of the product. String No
fields Advertisers can add any other information to a product. These are presented in "fields". See examples below for details. String No

*Either tdCategoryName or name is always present.

Heads up! Only information set as "required" above is present on all products. Other types of information is not mandatory for advertisers to provide.

JSON response

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

{
  "productHeader" : {
    "totalHits" : 2315
  },
  "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"
    }, {
      "name" : "productLink",
      "value" : "http://accessories.euro.dell.com/sna/productdetail.aspx?c=nl&l=nl&s=bsd&cs=nlbsdt1&sku=A6854908"
    } ],
    "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"
    } ],
    "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:

Name Description Type
result The result JSON as an evaluated javascript object. See example JSON above. object/array
statusCode HTTP status code. Undefined if successful. int
message Error message. Undefined if successful. string

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


JSONP, really? Well, api.tradedoubler.com is CORS enabled, so you may not want to use JSONP at all. Learn more.

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>2318</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:field name="productLink">http://accessories.euro.dell.com/sna/productdetail.aspx?c=nl&l=nl&s=bsd&cs=nlbsdt1&sku=A6854908</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>
                    <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:

Name File Documentation (HTML)
Common format ProductsFeedCommon_v3_0.xsd ProductsFeedCommon_v3_0.xsd.html
Output format ProductsFeedOutput_v3_0.xsd ProductsFeedOutput_v3_0.xsd.html

Limitations

Any search request has a limit of max 10000 first products returned. That means that adding page=2;pageSize=10000 will not net 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. Use this service to get raw product data from a specific advertiser 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 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:

Name Description Type Required
token Your unique token, identifying you as an advertiser. String Yes
fid Primary key of the feed you are requesting. Integer Yes
minUpdateDate Only return products which has been modified after this point in time. Integer/Date No
maxUpdateDate Only return products which has been modified before this point in time. Integer/Date No
includeDeleted Set to true to include deleted products in the reponse. Boolean No
pretty Set to true for nice line breaks in the output. Boolean No
Be aware! Unlimited responses can get huge and contain hundreds of thousands of products. Browsers may crash.

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}

Get all products modified after 1372237605168 from feed ID 1337 as XML with deleted products included:

HTTP[S] GET http://api.tradedoubler.com/1.0/productsUnlimited.xml;fid=1337;minUpdateDate=1372237605168;includeDeleted?token={token}

Product categories

All products belong to at least one type of category. However, most products belong to both an advertiser category and a Tradedoubler category.

Normally, advertisers provide their own category when pushing products to Tradedoubler. This category is then mapped to a Tradedoubler category so publishers get consistent category naming conventions.

This is how mapping of advertiser categories is done:

  1. The advertiser provides the Tradedoubler category (in addition to their own) when posting the product. This type of mapping is instant and we encourage all advertisers to do so.
  2. If the advertiser does not supply Tradedoubler's categoryId, they have the ability to map categories via the API.
  3. If mapping is not done by the advertiser, Tradedoubler personnel manually map the advertiser category to a Tradedoubler category as soon as possible.

Categories service

The Tradedoubler category tree is available in a separate service in the API. The service is called productCategories and this is its 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:

Name Description Required
token Your unique token, identifying you as an advertiser. Yes
language ISO 639-1 code of the language to use in the response. For example en for English or sv for Swedish. No
jsonp If you are requesting JSON, you can define a callback name. The API will return a Javascript document with the result as an array in a function named as the callback. No
The API will return categories in English by default. If you enter a language that the categories have not been translated to, the API also returns English category names.

XML schema

An XSD file for the output format is available here:

Name File Documentation (HTML)
Output format CategoryTree_v1_0.xsd CategoryTree_v1_0.xsd.html

Response

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

Name Description
language Language of the category name.
name Name of the category in the language you specified. Defaults to English.
id Category identifier which does not change.

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


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

Data not loaded

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

Data not loaded
Stay current and use the productCategories service to get an up to date tree, instead of using a static tree.

Product feed service

The product feed service allows you to get information on all feeds available to you. It returns general information about feeds, 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 to productFeeds requests:

Name Description Type Required
token Your unique token, identifying you as an advertiser. String Yes
pretty Set to true to get nice line breaks in the response. Boolean No
To lookup a specific feed, add its ID as a path to the URL. For example: /1.0/productFeeds/11111?token={token}

Example requests

Get all feeds as JSON:

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

Get feed ID 11111 as XML:

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

Response

Here is an example of a response in JSON:

{
  "feeds" : [ {
    "feedId" : 19750,
    "name" : "Carl Example Feed",
    "deleted" : false,
    "active" : true,
    "sendToNewPF" : false,
    "visible" : true,
    "currencyISOCode" : "GBP",
    "languageISOCode" : "sv",
    "secret" : false,
    "numberOfUnmappedCategories" : 0,
    "numberOfProducts" : 189905,
    "programs" : [ {
      "programId" : 231514,
      "name" : "Carl Example program UK"
    }, {
      "programId" : 228139,
      "name" : "Carl Example program SE"
    } ]
  }, {
    "feedId" : 20782,
    "name" : "Carl test",
    "deleted" : false,
    "active" : true,
    "sendToNewPF" : false,
    "visible" : true,
    "currencyISOCode" : "SEK",
    "languageISOCode" : "en",
    "secret" : false,
    "numberOfUnmappedCategories" : 7,
    "numberOfProducts" : 13727,
    "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.

Module Error code HTTP code HTTP status Description
Open API1 400 Bad Request Missing token
Open API 2 403 Forbidden Invalid token
Open API 3 404 Not Found Invalid API version
Open API 4 404 Not Found Invalid module version
Open API 5 500 Internal Server Error Service not responding
Open API 6 404 Not Found Missing version
Open API 7 404 Not Found Missing module
Products Open API PF_200 400 Bad Request Parameters is missing
Products Open API PF_210 400 Bad Request No parsable content received
Products Open API PF_220 400 Bad Request Country parameter is not a valid ISO code
Products Open API PF_230 400 Bad Request An error not expected and not known
Products Open API PF_240 400 Bad Request Value not set on a parameter, e.g. a Category of a Product
Products Open API PF_250 400 Bad Request Our system is experiencing internal problems and cannot serve the request passed at this moment in time
Products Open API PF_260 400 Bad Request Value expected to be numeric but was not
Products Open API PF_270 400 Bad Request Value expected to be comma separated
Products Open API PF_280 400 Bad Request Price could not be parsed from posted data
Products Open API PF_290 400 Bad Request The currency of the Price is not a valid ISO currency
Products Open API PF_300 400 Bad Request Token request is not valid
Products Open API PF_391 400 Bad Request A malformed URL was supplied
Products Open API PF_430 400 Bad Request Parameter has illegal value

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

The most common HTTP errors are:

HTTP code HTTP status Description
400 Bad Request Invalid XML, Json or date format
404 Not Found The URL does not exist
405 Method Not Allowed Invalid HTTP method (e.g. GET instead of POST)
406 Not Acceptable Requesting invalid content type (e.g text/plain instead of application/xml)
415 Unsupported Media Type Sending invalid content type
500 Internal Server Error Service down