News

Product Web Services - Next Generation

Contents:

We are pround to announce the deploy of the new generation of our product web services. They take the way we deliver product data to a whole new level!

Here's what's new

Besides standard fields like price, brand or product name, the new version also delivers so called "product properties" - absolutely flexible data fields through which advertisers can specify custom data fields. E.g. clothes retailers can specify size or colour, hardware retailers can provide information like "capacity" or "Operating System" or mobile phone companies can specify "amount of SMS included" etc... Advertisers can specify any amount of such additional fields of information.
With our new service, you cannot only request these product properties, but you can also filter on them. You can e.g. only request those products in the 'Notebooks' category, which have the operating system 'Windows 7' or which are of brand 'Sony'. We call those filter criteria "filter queries".
On all product properties and on a range of standard fields, you can build facets, that is: you can group the found results by these fields. So if e.g. 700 products were found in the 'Notebooks' category, our service can construct things like these:
- Operating System:
  - Microsoft Windows 7 Home 32 Bit: 211 records
  - Microsoft Windows 7 Home 64 Bit: 187 records
  - Microsoft Windows 7 Professional 64 Bit: 154 records
  - etc...
- RAM:
  - 4096 MB: 198 records
  - 3072 MB: 165 records
  - 2048 MB: 76 records
  - etc...
- USB 3.0 ports:
  - 0 ports: 387 records
  - 1 ports: 128 records
  - 2 ports: 38 records
  - etc...
...and the user can drill down on these criteria!
Important especially in Germany: our new service displays the base price. So if a 0.7 litres bottle of wine costs 7.99 EUR, we not only display this information, but also the price per litre (in this case 11.41 EUR). This makes especially price comparison extremely convenient.
Like version 2, you can request version 3 via SOAP, but now also via GET. And what's more - in the case of GET, you can get the results either in XML or in JSON format.
We increased both the response speed and the search relevance.
Like before, you can either search across all your partner programs or only within single programs. But now you can also search across all your partner programs except for single programs. This way you can e.g. exclude programs with erotic content, unless someone searches within the erotic category.
You can request different image and logo sizes at once.
Now you can search without a keyword - e.g. if you only want to display only products of a certain brand or within a single category (incl. or excl. sub categories).
The new service displays for each product, when the product list has last been updated - so you and your customers have full transparency, how up-to-date the displayed product data is - especially important for the price.
You can obtain any amount of products from our API - max. 500 products at a time, but through paging, any amount of products can be delivered.
Our new product web service has been rolled out internationally - you can use this service for product data in D/A/CH, UK, FR, NL and ES.
The former version of our product web service will remain operational for another 12 months and is planned to be switched off in February 2013.

Methods & examples

Below you will find a bunch of example requests, all of which are directed to the live database - no sandbox DB. The publisher which is used in these examples (PublisherId 580442) has only a single partnership - namely with the affilinet showcase program. This program has a set of example product data. If you wish to adapt the example requests for your account, just exchange the PublisherId, the publisher web service password (you can find yours under "Account > Technical Settings > Web Services") and the ShopId.

SearchProducts

(Documentation)

Let's jump right into it - here is a short example request to our live API:

Besides these two request options, our new service also works under SOAP. But for reasons of simplicity, we concentrate on the GET version in this introduction. If you want to learn more about the SOAP version, check out the documentation or take a look at our sample application.

Let's pretend you want to know the most common brands of the products found in the example above. Facets are there for your help. Just tell our API that you would like to obtain the facet "Brand" and how many facet values you want to see, then look out for the object "Facets" in the output:

You can specify up to 4 facets at once. E.g. for the standard field "Brand" and the properties "Colour", "Origin" and "Material":

Now let's say you have displayed these facets to your customer and he clicked on Brand "Connvers". Then you simply add this as a filter query and we deliver only products matching this additional filter criteria:

Note that the numbers behind the facet values have changed over the last request: our API calculates the facets only among the products matching all given search criteria.

You can specify several filter queries at once, e.g. Brand="Connvers", Colour="Blue" and Material="Leather":

Apart from those Facets and FilterQueries, you can specify the usual filter criteria like MaximumPrice, MinimumPrice, CategoryIds, ShopIds, etc... Here is a longish example:
"Give me all products of shop 1748, which match the keyword 'shirt', have the property 'Origin: Made in France', cost between 10 and 50 EUR and are in category 'Women' (Id 34758754) or any of its subcategories. And build the facets over the colour and the brand."

GetProducts

(Documentation)

Like in version 2, "GetProducts" lets you access products directly, by their ProductId. The returned products have the same structure like the products returned by SearchProducts. You can request up to 50 products at a time.

GetShopList

(Documentation)

This method returns all active shops, with which the requester has an accepted partnership. It tells you for each shop its name, its ShopId, its ProgramId (*), the timestamp when this shop had last been fully updated and the amount of property fields, which this shop has. You can specify a keyword, to which the shops have to be related, you can specify the size of the logo, which shall be returned, and you can even specify a date, so the method returns only shops which have been updated since that date.

(*) Several advertisers send us more than one shop list. E.g. a clothes retailer might send us his shoes and his sportswear in separate feeds. In such a case, both feeds would have separate ShopIds, but the same ProgramId.

GetCategoryList

(Documentation)

This method returns all categories of a given ShopId, e.g.:

If you wish to obtain the categories of the affilinet product category tree, send a request with ShopId="0.

GetPropertyList

(Documentation)

As explaind above, SearchProducts lets you facet and filter on product properties - the method GetPropertyList tells you, which properties a given ShopId has, and for how many of this shop's products have this property set.

Example Application

We have created a little example on what our new API can do. It is programmed in PHP and sends requests to our API via SOAP. The PHP code is probably not the smartest or most performant one, but we concentrated on easy-to-read code. You can test this example on our server and you can download the package to inspect and alter the code as you wish. Please note that we don't take any responsibility for this PHP code if you install it on your server and/or use it or parts of it in a production environment. It is purely intended as an example on the functionalities of our new API - especially the facets and filter queries.