Manual for Icecat CSV Interface

By
Manual for Icecat CSV Interface

This document describes the manual for Icecat CSV interface (Comma-Separated Values) variant of Icecat’s Open Catalog. A set of standards, data structures, files, and functionalities for the exchange of product data.

Icecat provides customers with the ability to download CSV product data by:

  1. using a real-time call based (URL) interface to access product data-sheets
  2. generating personalized or customized CSV files based on your catalog
  3. through direct access to our Icecat Data indexes and repositories

In this post, we describe only (1) the real-time calls to CSV data-sheets. Generating personalized files is discussed separately. In the case of 3, check out the documentation for the Icecat XML Data Interface, as the same directories also contain CSV variants of index files, which can be used to retrieve product data-sheets in CSV format.

Other available interfaces are:

In general, we advise using the XML (or JSON) interfaces for downloading Icecat data-sheets. Interfaces based on these data formats are most robust, provide you with the most flexibility, and provide you with the most complete data set per product. However, sometimes the use of a CSV format is easier and more pragmatic, depending on the capabilities of the e-business infrastructure of your company.

Please, note that some brands have a restrictive syndication policy, in which they allow access to certain digital assets or other product data only to authorized resellers. In general, it is therefore good to request authorization from brands with which you have established formal relations via the Icecat website.

In case you need more information or have questions, don’t hesitate to contact us.

Advantages of upgrading to Full Icecat

The CSV interface may be accessed by all Icecat Data (XML) users using at least an Open Icecat account. Open Icecat users can access the data of the sponsoring brands. Full Icecat users can access the data of all brands in the Icecat database, and get a free Vendor Central (PIM) service included.

However attractive the free Open Icecat database is, the Full-Icecat database still contains more than 10,000s brands. If you want specific brands to be included in free Open Icecat, please, recommend Icecat to your manufacturer contacts.

Read more about the main advantages of Full Icecat over free Open Icecat. In case you need higher catalog coverage, you will need Full Icecat. For more information, see the Icecat Subscription Plans.

If you want to upgrade to Full Icecat, please contact us via the contact form, or click on the “request Full Icecat access” link after the User Login.

International Standards Supported

Apart from JSON, Icecat is compliant with an increasing number of international standards. See, the quick overview of such supported standards.

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.

Explicitly relevant for website development is:

  • First, mention explicitly the “Specs Icecat” on all product datasheets, with a link to the Icecat.biz web site
  • Secondly, include explicitly an “AS IS” disclaimer, an example is available in several languages.

1. Real-time CSV interface

The Icecat CSV product data-sheet consists of following columns:

Column titleExplanation
Requested_prod_idManufacturer’s product identifier used in your product feed
Requested_GTIN(EAN/UPC)Requested numerical GTIN (EAN/UPC) code from your product feed
Requested_Icecat_idRequested numerical internal Icecat identifier from your product feed
ErrorMessageContains a textual explanation (not an error code!) why the system did not provide information on requested identifiers
SupplierProduct’s brand or manufacturer name
Prod_idManufacturer part number
Icecat_id (product_id)Internal numerical product identifier used in the Icecat database
GTIN(EAN/UPC)GTIN(EAN/UPC) codes that corresponds to a product
CategoryCategory name
CatIdNumerical category identifier
ProductFamilyProduct family name
ProductSeriesProduct series name
ModelProduct or model name
UpdatedThe date of the most recent change of product data-sheet in Icecat
QualityProduct quality indication
On marketOn market indicator
Product viewsNumerical value that shows number of data-sheet views in Icecat
HighPicLink to high resolution of main product image
HighPic ResolutionMain product image resolution
LowPicLink to low resolution product image
Pic500x500Link to medium (500px) resolution image
ThumbPicLink to thumbnail image
Folder_PDFLink to PDF leaflet
Folder_Manual_PDFLink to PDF manual
ProductTitleProduct title
Short descShort editorial description of product data-sheet
ShortSummaryDescriptionAutomatically generated short summary description
LongSummaryDescriptionAutomatically generated long summary description
LongDescMarketing text
ProductGalleryLinks to gallery images separated by comma
ProductGallery ResolutionResolution of product gallery images (separated with | symbol, if several)
360Content type with a 360 degree (or so called 3D) product view
EU Energy LabelEU Energy Label
EU Product FicheEU Product Fiche (PDF or html data-sheet)
PDFPDF files
Video/mp4Product videos
Other multimediaOther multimedia content types
ReasonsToBuyReasons to buy (feature bullet descriptions)

Columns with product specifications are included and have column headers such as “Spec #” so that each new specification (feature) is included in a new column in the output CSV file. The number of specifications depends on the number of spec values in the respective product data-sheet. A cell with a specification value consists of a spec name, spec value, and a measuring unit, if present. Those columns also contain spec group names. Spec groups consist of multiple specs, which are grouped under its respective spec group, to make reading a spec table easier for a buyer.

If an user wants to get CSV file in the format when the feature names are in the header, he/she should use the a specific key: “wide_features_format=1” at the end of the URL that calls CSV file.

An 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, where the spec groups “Design” , “Processor” and “Memory” are marked 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",……..

See also Digital Asset Types as Represented in Icecat’s Open Catalog Interfaces.

2. URL call format

The Icecat real-time CSV interface, supports URL requests by:

  • GTIN (EAN/UPC) code(s)
  • GTIN (EAN/UPC) code(s) + category (id)
  • Brand Product Code + Brand (vendor name)
  • Brand Product Code + Brand (vendor name) + category (id)
  • Icecat internal numerical product identifier(s) (icecat_id)
  • Icecat internal numerical product identifier(s) + category (id)

Please, find a more detailed description of each parameter below:

  • ean_upc – GTIN (EAN/UPC) code (one or several separated by comma)
  • prod_id – manufacturer product code or comma separated list of product codes or alternative manufacturer product codes that are on the market and are mapped to an Icecat data-sheet (m_prod_id)
  • brand – the manufacturer’s brand name (including alternative brand names present in the Icecat supplier mappings)
  • icecat_id (product_id) – unique internal Icecat identifier of a product data-sheet, which can also be provided as a comma separated list
  • lang – the language identifier (Icecat returns the EN data-sheet by default if no lang is selected in the URL request)
  • cat – an optional, but advised parameter, where user may add the Icecat numerical identifier of a product category to reduce the probability of unexpected data-sheets
  • output – the type of output (Enter “productcsv”Icecat returns product XML if no output type is provided)

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:
https://data.icecat.biz/xml_s3/xml_server3.cgi?prod_id=;brand=Philips;lang=;output=productcsv
https://data.icecat.biz/xml_s3/xml_server3.cgi?ean_upc=8711500354532,8711500354501;lang=EN;output=productcsv
https://data.icecat.biz/xml_s3/xml_server3.cgi?prod_id=4347B007,8576B064;brand=canon;lang=IT;output=productcsv

In case user wants the feature names to have as titles of the columns: https://data.icecat.biz/xml_s3/xml_server3.cgi?prod_id=4347B007,8576B064;brand=canon;lang=IT;output=productcsv;wide_features_format=1

3. Access to rich content

Icecat provides access to special type of content – rich media – via XML, xml_s3 and real-time CSV interfaces. Rich media content can be requested by  the special output parameter: output=richproductcsv

Examples:
https://data.icecat.biz/xml_s3/xml_server3.cgi?product_id=17727188;lang=NL;output=richproductcsv
https://data.icecat.biz/xml_s3/xml_server3.cgi?ean_upc=8710103608011;lang=NL;output=richproductcsv

Note: for certain brands rich media can be restricted to their Authorized Resellers. Contact Icecat, if you think that you miss certain rich media assets that you expected to receive.

4. URL symbols encoding

Since some manufacturer product 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

5. IP Access Limits

Icecat sets up a limit on the 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 listed in their Icecat account profile. Requests from unregistered IPs are not processed. In such cases system returns an error message.

  • commented on October 5, 2016 by Dan Ciocirlan

    Cool enough!

  • commented on September 15, 2020 by Viktoriya

    Hello
    we have a problem. We have full ice cat subscription. BUT
    When we are trying to get a request for a file with prod_id , message appears “The requested XML data-sheet is not described in the Ice cat database” . But on the web-site its exist
    why ?
    and sometimes we have such message “the requested product exist only in Full Ice cat ” But we have access to full ice cat
    why it happens also ?

  • commented on February 8, 2021 by Massimo

    Same problem with me
    Full icecat subscription

    • You are matching products based on the brand name + the product code and GTIN. In case the respective GTIN is attached to a different product (not described one) in the Icecat database, the system gives you the result based on the GTIN identifier. So you get the message that product is not described. We are working now to improve this logic. Meanwhile, you can try to match your product feed based only on the brand name + the product code.

  • commented on May 24, 2021 by Kai

    Hi, I am trying to import the gallery via link – do I need any special permissions? I’ve whitelisted my server IP but it seems to fail at this stage, can you advise please? I am trying to import data fields into WordPress which works, EXCEPT gallery. Thank you.

  • commented on June 12, 2022 by Jamie

    Hi there!
    How do you find a list of Brand (vendor name) that can be used please?

    We have a list of products and their associated vendor name, eg HP. However you use HP while we use HP Inc. so we would need a list that we can create a cross reference table for.

    Thanks in advance.

    • commented on June 13, 2022 by Wouter Maatman

      Hi Jamie,
      Thanks for your response. Which country are you established in? Based on that a responsible country manager will contact you.
      Regards,
      Wouter

  • commented on February 15, 2023 by Marcel

    Hi,
    We host the webshop of one of your Spanish customers. For some reason images aren’t displayed.
    For example:
    /images.icecat.biz/img/gallery/2226_4159158186.jpg is displayed
    /images.icecat.biz/img/gallery/36687746_3478561051.jpg isn’t displayed

    Do you have any thoughts about this.

    Looking forward to your answer.

    Regards,
    Marcel

Leave a Reply

Your email address will not be published. Required fields are marked *

Icecat xml

Open Catalog Interface (OCI): Manual for Open Icecat XML and Full Icecat XML

This document describes the Icecat XML method of Icecat's Open Catalog Inte...
 November 3, 2019
Manual

Manual for Icecat Live: Real-Time Product Data in Your App

Icecat Live is a (free) service that enables you to insert real-time produc...
 June 10, 2022
Manual for Icecat CSV Interface

Manual for Icecat CSV Interface

This document describes the manual for Icecat CSV interface (Comma-Separate...
 September 28, 2016
 October 4, 2018
LIVE JS

How to Create a Button that Opens Video in a Modal Window

Recently, our Icecat Live JavaScript interface was updated with two new fun...
 November 3, 2021
Addons plugins

Icecat Add-Ons Overview. NEW: Red Technology

Icecat has a huge list of integration partners, making it easy for clients ...
 October 27, 2023
Manual

Manual for Open Icecat JSON Product Requests

JSON (JavaScript Object Notation) is an increasingly popular means of trans...
 September 17, 2018
 January 20, 2020
New Standard video thumbnail

Autheos video acquisition completed

July 21, Icecat and Autheos jointly a...
 September 7, 2021
Manual

Manual Personalized Interface File and Catalog from Icecat

With Icecat, you can generate personalized or customized CSV or Excel files...
 May 3, 2022