Entries with tag announcement .

EAN and merchant category filters in the product search API

As the beta phase of the new product search aproaches the end, we continue rolling out the features. Today, we are happy to present you two latest additions to the API interface - the EAN and the merchant category filters.

EAN filter

You can now search for products using the unique international article number - the EAN. It's a great filter for all those barcode scanner applications, which don't have any other keywords to use. EAN can be passed as a query parameter and will limit the results to matching products only. Even though EAN uniquely identifies a product, it is possible that you will get multiple results if several merchants have the same item for sale. Here's an example request to find the Galaxy Note 10.1 (ean 8806085308091):

http://api.zanox.com/xml/2011-03-01/products?[...]&ean=8806085308091

Response contains two products from different merchants (cropped for readability):

<productItem id="b3d8b8ac4dd085a5b7a239b61ce5beb6">
    <name>Samsung Galaxy Note 10.1 WiFi TM 16GB white (GT-N8020ZWADBT)</name>
    <manufacturer>Samsung</manufacturer>
    <ean>8806085308091</ean>
    <category id="7000000">Computers & Software</category>
    <merchantCategory>Computer + Büro</merchantCategory>
</productItem>
<productItem id="9cf344f049b0289e5016dff4262b75ff">
    <name>Samsung Galaxy Note 10.1 N8020 LTE white</name>
    <manufacturer>Samsung</manufacturer>
    <ean>8806085308091</ean>
    <merchantCategory>Tablets</merchantCategory>
</productItem>
 

Please note that not all merchants provide EANs for their product data feeds, therefore not all products in our database can be found using their article number.

Merchant category filter

Most shops use their own category tree to organize products. They are different from merchant to merchant, but make good and reliable search criteria if you want to get the best possible search result for a specific merchant. We are therefore adding the functionality to filter products by the merchant category or several categories. Like EAN, merchant category can be passed via REST URL query parameter. You can also pass multiple categories, from the same or different merchants by repeating the query parameter. For example, if you wanted to search for Samsung tablets and notebook PCs, you could formulate a query like this:

http://api.zanox.com/xml/2011-03-01/products?[...]&merchantcategory=Tablets&merchantcategory=Notebooks&q=samsung

It returns multiple products from both categories, two of which you can see below (cropped for readability):

<productItem id="92544ec116ba54cf87175675521e88a4">
    <name>Samsung Notebook NP370R5E-S01CH</name>
    <manufacturer>Samsung</manufacturer>
    <ean>8806085381797</ean>
    <merchantCategory>Notebooks</merchantCategory>
</productItem>
<productItem id="e1cb94e83497cf8c11760871c56847bf">
    <name>Samsung Galaxy TAB2 7.0” WIFI 8GB</name>
    <manufacturer>Samsung</manufacturer>
    <ean>8806085047013</ean>
    <merchantCategory>Tablets</merchantCategory> 
</productItem>

We will be extending our API in the near future to allow you to download merchant-defined category trees, in order to enable you to use the full potential of this feature.

Both of the new filters are also documented in the Publisher API 2011 reference.

 

Updated: retrieving all merchant's categories

We have also added an API resource that returns all product categories for a selected merchant. For example you can get categories for Fab.com EU (ID 13299) like this:

http://api.zanox.com/xml/2011-03-01/products/merchantcategories?connectid=50AEB484E9C877FFF538&program=13299

Response at the time of writing is (cropped for readability):

<GetMerchantCategoriesResponse>
    <page>0</page>
    <items>158</items>
    <total>158</total>
    <categories>
        <category>Women / Necklaces</category>
        <category>Home / Unframed Prints</category>
        <category>Home / Workspace</category>
        <category>Home / Kitchen Tools</category>
        <category>Home / Bed Linens</category>
        [...]
        <category>Home / Serveware</category>
        <category>Women / Watches</category>
        <category>Women / Bangles</category>
    </categories>
</GetMerchantCategoriesResponse>

Currently we have identified a few programs that provide low quality category data or do not provide it at all. Therefore this resource will not return categories where it detects that data is not correct. We will be working with advertisers to improve EAN and category data quality over time.

Retiring zanox product category tree

With merchant category filters now active in our product search API, we will be discontinuing our old zanox product category tree and the related API filter on January 1st, 2014.

Background

First, a bit of background on how current categorisation works. Products are assigned to a zanox category automatically, using a machine-learning algorithm, which makes this decision based on keywords in the product name, description and other fields. This approach allows us to categorise products independently of how much information is provided and does not force merchants to adopt (or map to) the zanox category tree. But as with all machine-learning algorithms - it is not perfect, especially when it comes to recognising same items in different languages or spotting a difference between a real item and its accessory (e.g. iPad and iPad case).

Changes and solutions

To address these shortcomings, we have already introduced result filtering by merchant categories and today we are announcing discontinuation of the current zanox product categorisation. Existing clients will continue working without changes until the 1st of January 2014. After that, queries using the old category IDs will return an empty resultset without errors. 

We advise you to rely on search keywords and merchant categories if you need better filtering.

New in the REST API: sales basket items

We are happy to present you the latest addition to our API resource family - the sale basket. As you might know a single sale can contain multiple products, which can belong to different categories and have different commissions. While the Publisher API has always had a resource to get sales or an individual sale, the response included an undefined commission and a "basket" as tracking category in case of multiple products in a single sale.

To cover this gap, we now introduce a new basket resource, which, among other properties, returns products in the sale basket, their respective tracking categories and commissions. A basket item looks like this:

  <basketItem>
   <posId>1</posId>
   <productName>Apple iPad 4</productName>
   <productNumber>123456789</productNumber>
   <productPrice>607</productPrice>
   <quantity>1</quantity>
   <trackingCategoryId>654321</trackingCategoryId>
   <commission>24.28</commission>
   <commissionAmount>0.0</commissionAmount>
   <commissionPercent>4.0</commissionPercent>
  </basketItem>

To get the basket, you will have to provide the sale ID as a REST URL path parameter. Sale IDs are returned by the aforementioned sales resource. The basket resource is protected, so you will need to generate the zanox OAuth signature as described in the authentication documentation. This functionality is implemented in REST API only, with the usual XML or JSON response formats to choose from.

For more information, please refer to the sales basket documentation page.

Maintenance work on 19th/20th and 26th/27th October 2013

There is an announcement on the main zanox blog, about maintenance work that we will be carrying out over the last two weekends of October. I wanted to make it a bit more transparent on the developer blog about what effect this will have on our APIs.

Publisher and Connect APIs

Due to maintenance, we are going to set these APIs into read only mode for a couple of hours on the first weekend and if necessary, on the second weekend as well. For all you Publisher REST API users, this means that POST, PUT and DELETE requests will be returning HTTP 503 - Service unavailable. Publisher SOAP API will also deny all create, update and delete operations returning an HTTP 503 too.
The Connect SOAP API will deny promoting and closing sessions, creating new connects and getting UI URL.

All Publisher REST API GET methods and SOAP API get* operations will continue to work as expected. The essential for apps "getSession" and "getOfflineSession" in the Connect SOAP API will not be affected either.

Data API

Data API is not affected.

ERP API

Unfortunately, access to the ERP API will have to be blocked during maintenance - you will not be able to log into the service.

Please note, that no data will be lost during the maintenance, and you will be able to catch up with your retrieve, update and create requests after the maintenance window.

Rebuilding the search

The shut-off of the zanox Shop@ network in November of last year made searching products and AdMedia in the API much more complex. Without the pool of freely available ads and products, each search query now requires a list of program IDs where the publisher is confirmed. No results are returned if this list is not provided. This is often cumbersome, as getting your confirmed program IDs requires making another API call, or a number of them if you are accepted to more programs than the maximum result page size.

Based on this feedback we decided to improve a thing or two to make lives of our developers easier. As it happens, a small feature request evolved into a full-scale rebuild of zanox search infrastructure and today I am happy announce that we are nearly there!

Without going too much into detail, I can still provide some insight for the tech-savvy. Parallel to not-the-latest-version Lucene, which drives our current product search, we have built up a fully-automated Solr 4 environment.

So what can you expect? Well, several things, actually.

Near real-time product availability in search

The first thing we improved on is delay between importing products from the Advertiser to their availability in search results. While current system refreshes its index once a day - at midnight, the new search will continuously index new products as they come in. So the delay will be reduced from the maximum of 24h to around the maximum of 45m. That's how long it takes us to index our biggest product feed. Averages should be much lower though - 10-20m.

Search in all confirmed programs without providing program IDs

The default behaviour of search was changed to automatically search all confirmed programs if no program IDs are provided in the search query. This way, developers will save the before-mentioned API call(s) to retrieve all program IDs.

Search products of all zanox programs without applying

Have you ever wondered which programs have products relevant to you? Now you can search within all programs with the URL query parameter partnership=all. Note, that no tracking links will be returned for programs, that have not confirmed you.

Fixing known bugs

Many of you are familiar with API returning less than 50 items in one page, even though total results is much bigger than 50. This behaviour is also described in the known bugs section of the product search documentation.

<page>0</page>
<items>4</items>
<total>21528</total>

This issue has been addressed in the new search version.

One important feature that is NOT in the current Beta is product categories. We are still working on improved machine learning algorithms that categorize the products, and we will add it in the near future.

We see the above features as must-haves for the rollout. But the new technology will enable us to add more bells and whistles in the future development iterations. What we have in the "pipe" is improved product categorization, better performance and in the long-term - also moving admedia search and program search onto the new backend.

Looks good, so when is it going into production? Well, actually it is live already, first accessible via our REST API. The main stream of requests is still chanelled to the old search, but if you append the query parameter solr=true to the resource URL, your results will come from the Solr cluster. The developer team is still measuring and tuning the performance, writing automated tests and fixing any "teething issues", but it is there for everyone who wants to test it out.

When we are sure that the new search meets our quality expectation, we will start switching more and more requests to the new backend. The good news for you, the developers? You don't have to add a single line of code, the API interface remains the same. If you want to switch over to the new search before we do it for you - you can use the solr=true parameter. Additionally, you don't have to provide any program IDs, unless you want to limit results to those particular programs. Here's an example:

http://api.zanox.com/xml/2011-03-01/products?connectid=43EEF0445509C7205827&programs=7408&q=nike&solr=true

Having said that, we would be very happy to hear from the early adopters, trying out our search. What are your impressions? What works, what doesn't and what can we improve? Head to the documentation section to read about the new parameters and their usage.

 

Showing 1 - 5 of 6 results.
Items per Page 5
of 2