Vous êtes sur la page 1sur 13

Open Catalog Interface (OCI): CSV interfaces

Document versions
Author
Alexandr Kravtsov
Alexandr Kravtsov
Alexandr Kravtsov
Alexandr Kravtsov

Date
25.06.13
28.08.13
10.09.13
15.01.14

Version
1.0.
1.1.
1.2.
1.3.

Sergey Ermolaev
Alexandr Kravtsov

24.06.14
19.03.15

1.4.
1.5.

Alexandr Kravtsov

20.05.15

1.6.

Alexandr Kravtsov
Alexandr Kravtsov
Alexandr Kravtsov

09.07.15
03.08.15
17.09.15

1.7.
1.8.
1.9.

Comments
First version of RT CSV interface description
Changes related to new CSV structure.
Description of access to rich media type of content.
Changed document structure.
Extension of documentation by adding a description of
new features and interfaces.
Changes in the specs and gallery images publication
Described few improvements in personalized index file
and rich product CSV files.
Added more detailed description of ReasonsToBuy
content type in CSV interface
Link to personalized index file has been added
Missing columns in product CSV has been added
Structural changes (split of MultimediaObjects column)

Icecat NV . De Liesbosch 12d . 3439 LC Nieuwegein . The Netherlands . t +31(0) 30 711 4700 . f +31(0) 84 838 5468 . info@icecat.biz . www.icecat.biz
COC:30259744 . Bank ABN Amro:402903846 . IBAN:NL64ABNA0402903846 . BIC:ABNANL2A . VAT:NL820687091B01 . PayPal: info@icecat.biz

1 / 13

1. Subject of this document


This document describes Open Catalog CSV Interface: a set of standards, structure, files content and
functionalities. It gives the basics of how to use and generate personalized files or request product
details of product(s) using CSV interface.
Icecat provides customers with an ability to generate personal files and download product-data sheets
using real-time URL-based interface in CSV (comma-separated values) format.
If you are interested in other interface please read these documents:
XML - icecat.biz/forum.cgi?post=3331
URL - icecat.biz/forum.cgi?post=2715
In case if you need more information please contact us.

1.1. Our mission


It is our mission to provide channel partners and buyer orientation websites with high-quality product
information via our Open Catalog Interface (OCI). More and more manufacturers work together with
Icecat to take care of their product content; this makes it possible for Icecat to distribute their product
content for free. Here, you can always find the latest overview of sponsoring (free) brands in Open
Icecat: http://icecat.biz/menu/partners/index.htm.
However attractive the free Open Icecat database is, the Full-Icecat database still contains many, many
more brands: 7800+ (see http://icecat.biz/menu/vendors/index.htm). If you are interested in
subscribing to the Full-Icecat database, please contact us via the website. If you want specific brands
to be included into free Open Icecat: please, recommend Icecat to your manufacturer contacts.

1.2. Open Icecat Fair Use Policy


The user of Open Icecat product data (in a free Open Icecat subscription or as part of the Full Icecat
data) is required to respect the Open Icecat Fair Use Policy, which can be found in the forum:
http://Icecat.biz/forum.cgi?tmpl=view_message.html;message_id=3004;thread_id=17
Explicitly relevant for website development is:
- to mention explicitly the (c) Icecat.biz copyright notice (or Source: Icecat.biz) on all product data
sheets, with a link to the Icecat.biz web site;
- include explicitly the Icecat "AS IS" disclaimer which can be found here:
http://www.icecat.biz/menu/disclaimer/index.htm (and is available in several languages).

1.3. Advantages of upgrading to Full Icecat


What are the main advantages of Full Icecat over Open Icecat?
All product data of all 10300+ brands (see http://www.icecat.biz/menu/vendors/index.htm; if you see
the brand logo the brands product data is also available in free Open Icecat).
Coverage guarantees when we monitor your stock portfolio.
Support for producing missing data-sheets, categories and brands on request.
Icecat NV . De Liesbosch 12d . 3439 LC Nieuwegein . The Netherlands . t +31(0) 30 711 4700 . f +31(0) 84 838 5468 . info@icecat.biz . www.icecat.biz
COC:30259744 . Bank ABN Amro:402903846 . IBAN:NL64ABNA0402903846 . BIC:ABNANL2A . VAT:NL820687091B01 . PayPal: info@icecat.biz

2 / 13

If you want to upgrade to Full Icecat, you can contact us via the contact form, or click on the request
Full Icecat access link after the User Login (http://www.icecat.biz/en/menu/openIcecat/index.htm),
or fill in and fax the Full Icecat registration form: http://icecat.biz/forum.cgi?
tmpl=view_message.html;message_id=3191;thread_id=1
that you can find as an attachment. You will also find in the attached form (pdf) the standard Full
Icecat tariffs.

Icecat NV . De Liesbosch 12d . 3439 LC Nieuwegein . The Netherlands . t +31(0) 30 711 4700 . f +31(0) 84 838 5468 . info@icecat.biz . www.icecat.biz
COC:30259744 . Bank ABN Amro:402903846 . IBAN:NL64ABNA0402903846 . BIC:ABNANL2A . VAT:NL820687091B01 . PayPal: info@icecat.biz

3 / 13

2. Personal CSV files


To simplify implementation process Icecat provides an ability to generate personal files in CSV format
with basic information and details of matched product data-sheets between catalog and your
portfolio.
Types of personal CSV files:
Personal index file (PIF) - personal index file that contains information about matched product datasheets like product identifiers (internal product ID, part number and GTIN (EAN/UPC) code) and paths
to XML or URL (based on your subscription) URLs.
Personal catalog file - personalized file with detailed information per each matched product.
My catalogs rich media assets - CSV file with links to media assets per each product data-sheet that
were matched between your feed and Icecat catalog.
Please check out more structural review of this file in paragraph 1.2. Types of personalized CSV files
2.1. CSV structure
Column separator: , (comma)
Line break: \n
Quote symbol: "
Escape symbol: "
Optional quotation: N
Value separators:
- Links separator pale (|)
- ReasonsToBuy contains with headline (text), picture link (URL) and RTB itself (text) that
separated with pale (|) symbol. Different RTBs are separated with line break between each
other.
- GTIN (EAN/UPC), image galleries and product multimedia objects comma
- Specifications colon + space
2.2. Main requirements to input file
To generate unique personalized CSV files Icecat system requires a products list from a user. It could
be a CSV, XML or Excel (XLS or XLSX) file with main product identifiers:
- Manufacturer part number (alphanumerical value)
- Brand name (alphanumerical value)
or
- GTIN (EAN/UPC) code (numerical value)
Quality of input file is one of the factors that determines the level of matched positions. Here you can
read more about input file formats and structures:
CSV: http://en.wikipedia.org/wiki/Comma-separated_values

Icecat NV . De Liesbosch 12d . 3439 LC Nieuwegein . The Netherlands . t +31(0) 30 711 4700 . f +31(0) 84 838 5468 . info@icecat.biz . www.icecat.biz
COC:30259744 . Bank ABN Amro:402903846 . IBAN:NL64ABNA0402903846 . BIC:ABNANL2A . VAT:NL820687091B01 . PayPal: info@icecat.biz

4 / 13

XML: http://www.w3schools.com/xml/xml_syntax.asp
Excel: http://en.wikipedia.org/wiki/Microsoft_Excel_file_format#File_formats
Based on product identifiers described above system make a matching between your feed and Icecat
database. Icecat automatically add necessary information to matched data and generate personal files
that can be downloaded from My Icecat page in CSV or XLS and used for your purposes.
Paragraph 1.4. Interface description describes the interface and related helpful features.
2.3. Types of personalized CSV files
Icecat generates following personal CSV files:
Personal index file (PIF) - personal index file that contains basic information about matched product
data-sheets like product identifiers and paths to XML or URL (based on your subscription) URLs.
File content:
Column title

Description

prod_id
supplier_name
ean_upc
Path
Timestamp
Your product ID

unique manufacturer product identifier


name of products supplier
column that contains GTIN (EAN/UPC) numerical product code(s)
link to product data-sheet
the date of last product update
Internal identifier of item (product) from your database*

*- Internal product identifier is optional, but its presence in the PIF simplifies the process of data
processing. It allows you to match the ID from your database with specific data-sheet in Icecat catalog.
Last column contains a link to product data-sheet that system generates based on subscription type of
your account (URL / XML) and assignments to local repositories.
Personal catalog file (PCF) - personalized file that contains detailed information per each matched
product. This type of file is available only to users with XML subscription.
File content:
Column title

Description

Requested_prod_id
Requested_GTIN(EAN/UPC)
Requested_Icecat_id

Manufacturer's product identifier used in your price file


Requested numerical GTIN (EAN/UPC) code from your price file
Requested numerical internal Icecat identifier from your file

First three columns contains the information for your information that allows you to understand on
what basis Icecat system found a matching between an item from your file and product from Icecat
database.

Icecat NV . De Liesbosch 12d . 3439 LC Nieuwegein . The Netherlands . t +31(0) 30 711 4700 . f +31(0) 84 838 5468 . info@icecat.biz . www.icecat.biz
COC:30259744 . Bank ABN Amro:402903846 . IBAN:NL64ABNA0402903846 . BIC:ABNANL2A . VAT:NL820687091B01 . PayPal: info@icecat.biz

5 / 13

ErrorMessage
Supplier
Prod_id
Icecat_id
GTIN(EAN/UPC)
Category
CatId
ProductFamily
ProductSeries
Model
Updated
Quality
On_Market
Product_Views
HighPic
LowPic
Pic500x500
ThumbPic
Folder_PDF
Folder_Manual_PDF
ProductTitle
ShortDesc
ShortSummaryDescription
LongSummaryDescription
LongDesc
ProductGallery
ProductGallery Resolution
360
EU Energy Label
EU Product Fiche
PDF
Video/mp4
Other multimedia
ReasonsToBuy
Spec

Contains a textual explanation (not an error code!) why the system


did not provide information on requested identifiers
Products supplier name
Manufacturer part number
Internal numerical product identifier used in Icecat Database
GTIN (EAN/UPC) codes that corresponds to a product
Category name
Numerical identifier of products category
Family name
Series name
Model name
The date of the most recent change of product data-sheet in Icecat
Data-sheet quality
On market indicator
Numerical value that shows number of data-sheet views in Icecat
Link to high resolution of main product image
Link to low resolution picture
Link to medium (500px) product image
Link to image thumbnail
Link to PDF leaflet
Link to PDF manual
Product title
Short editorial description of product data-sheet
Automatically generated short summary description
Automatically generated Long summary description
Marketing text
Gallery images
Resolution of product gallery images (separated with | symbol, if
several)
Content type with a 360 degree (or so called 3D) product view
EU Energy Label
EU Product Fiche (PDF or html data-sheet)
PDF files
Product videos
Other multimedia content types
Reasons to buy (feature bullet descriptions)
Column contains feature name, feature value and measure unit (if
present)

My catalogs rich media assets - CSV file with links to media assets per each product data-sheet that
were matched between your feed and Icecat catalog. This type of file is available only to users with
XML subscription.
File content:
Column title

Explanation

Requested_prod_id
Requested_GTIN(EAN/UPC)
Requested_Icecat_id
ErrorMessage

Manufacturer's product identifier used in your price file


Requested numerical GTIN (EAN/UPC) code from your price file
Requested numerical internal Icecat identifier from your file
Contains a textual explanation (not an error code!) why the system
did not provide information on requested identifiers

Icecat NV . De Liesbosch 12d . 3439 LC Nieuwegein . The Netherlands . t +31(0) 30 711 4700 . f +31(0) 84 838 5468 . info@icecat.biz . www.icecat.biz
COC:30259744 . Bank ABN Amro:402903846 . IBAN:NL64ABNA0402903846 . BIC:ABNANL2A . VAT:NL820687091B01 . PayPal: info@icecat.biz

6 / 13

Supplier
Prod_id
Icecat_id
GTIN(EAN/UPC)
HighPic
ProductGallery
ProductGallery Resolution
360
EU Energy Label
EU Product Fiche
PDF
Video/mp4
Other multimedia
ReasonsToBuy

Products supplier name


Manufacturer part number
Internal numerical product identifier used in Icecat Database
GTIN(EAN/UPC) codes that corresponds to a product
Link to high resolution of main product image
Links to gallery images separated by comma
Resolution of product gallery images (separated with | symbol, if
several)
Content type with a 360 degree (or so called 3D) product view
EU Energy Label
EU Product Fiche (PDF or html data-sheet)
PDF files
Product videos
Other multimedia content types
Reasons to buy (feature bullet descriptions)

2.4. Interface description


This paragraph provides description of CSV-related interface that located in My Icecat panel. Every
Icecat user have access to that panel where Icecat hosts many useful features and functionalities.
To get to My Icecat user panel please open our website and click Login at the upper right corner.
Please enter your login name and password or click Register as new new user (free) to register. User
panel contains a tab that visible to every Icecat user My downloads. For XML users this tab
separated on two parts.

Left block called XML content and contains a general information of your XML subscription:
- Indication of subscription level

Icecat NV . De Liesbosch 12d . 3439 LC Nieuwegein . The Netherlands . t +31(0) 30 711 4700 . f +31(0) 84 838 5468 . info@icecat.biz . www.icecat.biz
COC:30259744 . Bank ABN Amro:402903846 . IBAN:NL64ABNA0402903846 . BIC:ABNANL2A . VAT:NL820687091B01 . PayPal: info@icecat.biz

7 / 13

- Paths to assigned repositories


- Resources: links to documents
Right block called CSV personalized content and consist of following information:
- Introductory text
- Link to personal index file (PIF) in CSV format including indication of import and file generation
progress
- Link(s) to personal catalog file (PCF) including timestamp and size indication, also XLS icon.
Click on that icon will generate an XLS file from previously generated CSV file;
- Link(s) to personal catalog with rich media assets including timestamp and size indication, also
XLS icon. Click on that icon will generate an XLS file from previously generated CSV file;
- Inform me about updates function, please activate it if you want to receive a notification as
soon as personalized files were generated;
- Button Regular updates. If you want to receive updates regularly, please push that button.
Next paragraph provides a step-by-step guide of what has to be done in order to create personal CSV
files.
2.5. How to create a personal CSV files
-

Please login to your user panel;


Choose My pricelist and upload your price list in Matching Your Price list tab from PC or URL;
Click Preview button;
When preview is ready, please choose a column mapping between your file and our system like in
example below, so then Icecat may automatically parse and import your data and start generation
of personal CSV files;

Icecat NV . De Liesbosch 12d . 3439 LC Nieuwegein . The Netherlands . t +31(0) 30 711 4700 . f +31(0) 84 838 5468 . info@icecat.biz . www.icecat.biz
COC:30259744 . Bank ABN Amro:402903846 . IBAN:NL64ABNA0402903846 . BIC:ABNANL2A . VAT:NL820687091B01 . PayPal: info@icecat.biz

8 / 13

Please also select the column with internal unique product identifier in your database, if applicable.
If you preview is not visible please check if price file format is correct or contact us.
- Click Save button when you finish with column assignments;
- After that you may check a status of file processing in Import status tab;
- As soon as import results are ready and visible in Import status, please open My downloads
tab to check if personalized CSV files are ready. Please be aware, that generating of such file may
take some time, so in case if CSV is not ready you will see a status message.
- In order to access or download your PIF without login in the User Panel, please use the link
below: https://icecat.biz/index.cgi?login_form=user_import_report;type=match;layout=csv;login=
XXXXX;password=XXXXX where XXXXX should be a the login name and password of your Icecat
account. Using this link, you may automate and simplify the process of data processing.

Icecat NV . De Liesbosch 12d . 3439 LC Nieuwegein . The Netherlands . t +31(0) 30 711 4700 . f +31(0) 84 838 5468 . info@icecat.biz . www.icecat.biz
COC:30259744 . Bank ABN Amro:402903846 . IBAN:NL64ABNA0402903846 . BIC:ABNANL2A . VAT:NL820687091B01 . PayPal: info@icecat.biz

9 / 13

3. Real time CSV interface


3.1. Output description
Output CSV product data-sheet consists of following columns:
Column title

Explanation

Requested_Prod_ID
Requested_GTIN_(EAN/UPC)
Requested_Icecat_id
ErrorMessage

Manufacturer part number from original user request


GTIN (EAN/UPC) numerical code from original request
Internal numerical Icecat product identifier from original request
Textual error message that indicates a reason of product/content
unavailability
Brand name
Manufacturer part number
Internal product identifier used in Icecat
GTIN (EAN/UPC) numerical code
Category name
Numerical category identifier
Product family name
Product series name
Model name
The date of the most recent change of product data-sheet in Icecat
Product quality indication
On market indicator
Numerical value that shows number of data-sheet views in Icecat
Link to high resolution product image
Main product image resolution
Link to low resolution product image
Link to medium (500px) resolution image
Link to thumbnail image
Link to PDF leaflet
Link to PDF manual
Product title
Short editorial description of product data-sheet
Automatically generated short summary description
Automatically generated Long summary description
Marketing text
Link to gallery image(s)
Resolution of product gallery images (separated with | symbol, if several)
Content type with a 360 degree (or so called 3D) product view
EU Energy Label
EU Product Fiche (PDF or html data-sheet)
PDF files
Product videos
Other multimedia content types
Reasons to buy (feature bullet descriptions)

Supplier
Prod_id
Icecat_id (product_id)
GTIN (EAN/UPC)
Category
CatId
ProductFamily
ProductSeries
Model
Updated
Quality
On market
Product Views
HighPic
HighPic Resolution
LowPic
Pic500x500
ThumbPic
Folder_PDF
Folder_Manual_PDF
ProductTitle
Short desc
ShortSummaryDescription
LongSummaryDescription
LongDesc
ProductGallery
ProductGallery Resolution
360
EU Energy Label
EU Product Fiche
PDF
Video/mp4
Other multimedia
ReasonsToBuy

Important: grey marked columns contain local dependent content.

Icecat NV . De Liesbosch 12d . 3439 LC Nieuwegein . The Netherlands . t +31(0) 30 711 4700 . f +31(0) 84 838 5468 . info@icecat.biz . www.icecat.biz
COC:30259744 . Bank ABN Amro:402903846 . IBAN:NL64ABNA0402903846 . BIC:ABNANL2A . VAT:NL820687091B01 . PayPal: info@icecat.biz

10 / 13

Columns with product specifications are included with column headers such as Spec #, so that each
new specification (feature) is a new column in the output CSV file. Number of specifications depends
on the number of described feature values in product data-sheet. A cell with specification value
consists of feature name, feature value and measure unit (if present).
Those columns also contain feature group names. Feature groups consist of multiple features which
are listed under the related feature group name.
Example:
Column header - Spec 1
Value - Processor
Column header - Spec 2
Value - Processor clock speed: 3.2 GHz
Column header - Spec N (where N is any spec number)
Value - Display
Column header - Spec N+1
Value Display diagonal: 17
Where:
Processor, Display spec groups
Processor clock speed, Display diagonal feature names
3.2, 17 - feature values
GHz, units

Example string from CSV (feature groups Design , Processor and Memory are marked in red):
"Design","Product type: Notebook","Colour of product: Black, Silver","Form factor:
Clamshell","Processor","Processor clock speed: 1.3 GHz","Processor family: AMD E","Processor model:
E2-3800","Processor cores: 4","Processor threads: 4","Processor cache: 2 MB","Memory","Internal
memory: 8 GB","Internal memory type: DDR3-SDRAM","Maximum internal memory: 16 GB","Memory
form factor: SO-DIMM",..
3.2. URL call details
Icecat real-time CSV interface support URL requests by:
- GTIN (EAN/UPC) code(s)
- GTIN (EAN/UPC) code(s) + category (id)
- MPN(s) + Brand (vendor name)
- MPN(s) + Brand (vendor name) + category (id)
- Icecat internal numerical product identifier(s) (icecat_id)
- Icecat internal numerical product identifier(s) + category (id)
Please find more detailed description of each parameter below:
ean_upc - GTIN (EAN/UPC) code (one or several separated by comma)
Icecat NV . De Liesbosch 12d . 3439 LC Nieuwegein . The Netherlands . t +31(0) 30 711 4700 . f +31(0) 84 838 5468 . info@icecat.biz . www.icecat.biz
COC:30259744 . Bank ABN Amro:402903846 . IBAN:NL64ABNA0402903846 . BIC:ABNANL2A . VAT:NL820687091B01 . PayPal: info@icecat.biz

11 / 13

prod_id - manufacturer part code or comma separated list of part codes (or alternative product code
that came from sources into Icecat db and became m_prod_id based on mapping database)
vendor - manufacturer brand name (or manufacturer brand name from supplier mappings)
icecat_id (product_id) - unique internal Icecat identifier of product data-sheet, also can be listed with
comma separation
lang - language identifier (Icecat return EN data-sheet by default if no lang is selected in URL request)
cat - optional but suggested parameter where user may put Icecat numerical identifier of category
output - type of output (Icecat return productxml if no output is selected)
Important: Red marked parameters are mandatory. A request only with ean_upc or icecat_id
(product_id) without vendor and brand name is recognizable by the system and will return a datasheet.
Below you may find examples of URL calls:
http://data.icecat.biz/xml_s3/xml_server3.cgi?prod_id=<list of product
codes>;vendor=Philips;lang=<lang>;output=productcsv
http://data.icecat.biz/xml_s3/xml_server3.cgi?ean_upc=8711500354532,8711500354501;lang=EN;out
put=productcsv
http://data.icecat.biz/xml_s3/xml_server3.cgi?prod_id=4347B007,8576B064;vendor=canon;lang=IT;ou
tput=productcsv
3.3. Access to rich content
Icecat provide authorized resellers with access to special type of content rich media - via XML,
xml_s3 and real-time CSV interfaces.
CSV with rich media content can be requested by assigned reseller (assigned on brand level) with
special output parameter: output=richproductcsv
Examples:
http://data.icecat.biz/xml_s3/xml_server3.cgi?product_id=17727188;lang=NL;output=richproductcsv
http://data.icecat.biz/xml_s3/xml_server3.cgi?ean_upc=8710103608011;lang=NL;output=richproduct
csv
This type of CSV contains rich media assets that has special restriction requested by respective
brand.
3.4. URL symbols encoding

Since some manufacturer codes may consist of special symbols like +, #, !, %, _ or space Icecat may
process these only if URL encoding of such symbols is included in the URL request.
Examples:
WBE3321A+NFSM = WBE3321A%2BNFSM
3580S4X BNDL = 3580S4X%20BNDL

Icecat NV . De Liesbosch 12d . 3439 LC Nieuwegein . The Netherlands . t +31(0) 30 711 4700 . f +31(0) 84 838 5468 . info@icecat.biz . www.icecat.biz
COC:30259744 . Bank ABN Amro:402903846 . IBAN:NL64ABNA0402903846 . BIC:ABNANL2A . VAT:NL820687091B01 . PayPal: info@icecat.biz

12 / 13

3.5. Access rules


CSV interface may be accessed by all Icecat XML users on DEMO stage.
Open Icecat users can access the data of sponsored brands.
Full Icecat users can access the data of all brands in Icecat database.

3.6. Limitations and restrictions


Icecat sets up a limit on number of simultaneous requests from each IP to ensure the stability of the
service. Icecat users cannot send more than 25 simultaneous CSV URL requests.
Full Icecat users can request CSV URL data only from IP addresses in Icecat account profile. Requests
from unregistered IPs are not processed. In such cases system returns an error message.

Icecat NV . De Liesbosch 12d . 3439 LC Nieuwegein . The Netherlands . t +31(0) 30 711 4700 . f +31(0) 84 838 5468 . info@icecat.biz . www.icecat.biz
COC:30259744 . Bank ABN Amro:402903846 . IBAN:NL64ABNA0402903846 . BIC:ABNANL2A . VAT:NL820687091B01 . PayPal: info@icecat.biz

13 / 13