Manual for Open Icecat JSON Product Requests

Alexandr Kravtsov
By

JSON (JavaScript Object Notation) is an increasingly popular means of transferring to data, comparable to XML. Under the hood, it’s used by Icecat Live‘s JavaScript applications. Main advantages of JSON are that it’s more efficient in terms of data transfer, and that it’s compatible with JavaScript applications requiring JSON.

This manual explains the Open Icecat JSON call formats and the output. For Full Icecat JSON, we refer to the general Icecat JSON manual, which will be reworked for the blog as well.

Other Integration Methods

If you want to integrate product data without frames, conforming your CSS, then use Icecat Live, which is the modern variant of the good-old URL integration method. If you want to have full control over the data, then make use of the XML, or CSV download methods. See the overview of methods and manuals.

Further, check out the Add-On page for popular platforms already integrating Icecat data.

Are you interested in adding product reviews? Then check out our reviews manual.

Important Notes about Icecat JSON

  1. Our JSON interface is relatively new, and certain aspects of our JSON interfaces might be subject to upgrades.
  2. The current use of JSON is limited to the retrieval of individual product data-sheets. For the use of indexes and repositories, and a more in-depth insight in the Icecat data model, we refer to the XML documentation.
  3. In case of Full Icecat data access or retrieval of private brand assets, authorization may be required, and a proper server certificate is to be used. We’re working on simplifying the authorization process in case of JSON data, making it comparable with the Full Icecat XML data access.
  4. The links and files in the download directories are to be downloaded with scripts (from server to server). If you try to download them via your browser, you may sometimes experience memory problems. This does not mean that on our side the data is not accessible or correctly available. In case you experience any problems, contact us via the contact form.

Our Global Mission

Icecat’s global mission is to provide e-commerce partners with high-quality product information that helps their buyers make better purchase decisions, in any world language, in any country and on any device or media.

Advantages of upgrading to Full Icecat

The JSON interface may be accessed by all Icecat Data (XML, CSV  or JSON) users, with 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.

However attractive the free Open Icecat database is, the Full-Icecat database still contains many, many more brands: 10,000s (see https://icecat.biz/menu/vendors/index.htm). If you want specific brands to be included into free Open Icecat, please, recommend Icecat to your manufacturer contacts.

Read more about the main advantages of Full Icecat over free Open Icecat.

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.

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:

  • to mention explicitly the “Specs Icecat” on all product datasheets, with a link to the Icecat.biz web site
  • to include explicitly an “AS IS” disclaimer, an example of which can be found at https://www.icecat.biz/menu/disclaimer/index.htm (available in several languages).

International Standards Supported

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

1. JSON Examples for Instant Use

Before elaborating the generic JSON structures, it’s good to look into examples. Below some examples of real-time Icecat JSON product requests based on different product identifiers. You can dynamically construct such links for your applications using your Icecat user name and the product identifiers known by your system.

1. ProductCode & Brand = Brand product code + the brand name:

https://live.icecat.biz/api/?UserName=openIcecat-live&Language=en&Brand=hp&ProductCode=RJ459AV

2. GTIN = the GTIN (EAN, UPC or JAN) bar code:

https://live.icecat.biz/api/?UserName=openIcecat-live&Language=en&GTIN=0882780751682

The third method, will require a bit more complex integration, as you have to read first the Icecat index files to obtain the Icecat product IDs. Recommended in case of large-scale integrations in which you want to predict for which products Icecat has product data or not.

3. icecat_id = Numerical product identifier in Icecat catalog (to be taken from Icecat index files):

https://live.icecat.biz/api/?UserName=openIcecat-live&Language=en&icecat_id=1198270

The general URI structure is:
With product code & the brand’s name:

http(s)://live.icecat.biz/api/?UserName=&Language=&Content=&Brand=&ProductCode=

With GTIN (EAN, UPC or JAN code):

http(s)://live.icecat.biz/api/?UserName=&Language=&Content=&GTIN=

With Icecat ID:

http(s)://live.icecat.biz/api/?UserName=&Language=&Content=&icecat_id=

Query parameters:

Query ParameterDescription
ProductCode + Brand or GTINThe unique product identifier: Brand + Manufacturer Part Code or GTIN (EAN, UPC or JAN)
Languagethe language code or locale code (in case of ambiguity) that is used
ContentContent parameter. If the Content parameter is absent in the URL request, the system will return all products content that is available.
UserNamethe Icecat user name as registered and authorized for certain repositories

Generally, the JSON REST service operates with the following Content parameters:

Content parameterDescription
AllAll content of the product
GeneralInfoThe general info of a product, which includes: Product title, Brand, Product name, Brand product code, category, virtual category, product family, product series, GTIN
ImageThe main image of a product (IsMain)
Multimediaall multimedia files related to a product: videos, PDFs, 360o/3D demos, and etc.
Galleryall gallery images of product
FeatureLogosfeature is enriched with a feature logo, and this logo is provided.
DescriptionsThe marketing text and long summary description
ReasonsToBuyThe main arguments to buy products, formatted as reasons to buy (RTB): RTB image + RTB title + RTB description
ReviewsThe expert or user reviews of a product, which are mainly provided by Testseek.
RelatedThe related products (this data is not used now)
Dictionary (Imports for dictionary: Brand, Сategory, Product_Family, Product_Series, ReasonsToBuy, UserManual, ProductName, Product code)The translation of content elements into the local language

Here is the request structure:

http(s)://live.icecat.biz/api/?icecat_id=12462305&UserName=openIcecat-live&Language=EN&Content={content parameter}*

* you should enter the content parameter you need

Examples:

  • With ‘all’ content parameter
    The method GET is to be used. For all content parameter the following is to be entered:
http(s)://live.icecat.biz/api/?UserName=openIcecat-live&Language=en&Content=All&Brand=hp&ProductCode=RJ459AV
  • With ‘multimedia’ content parameter
    The method GET is to be used. For multimedia content parameter the following is to be entered:
http(s)://live.icecat.biz/api/?UserName=openIcecat-live&Language=en&Content=Multimedia&Brand=hp&ProductCode=RJ459AV

2. Working with JSON Output

Once you enter any request, for example,
http(s)://live.icecat.biz/api/?icecat_id=12462305&UserName=openIcecatlive&Language=EN&Content=Multimedia
you can get two results:

  1. the request succeeds
  2. the request fails.

If the request succeeds, the server responds with a 200 OK HTTP status code and the data properties:

  JSON
 ____________________________________________________________________
 200 OK
 {
 message: ‘OK’,
 ‘data’ :
 {
 ‘multimedia’:
 [
 {
 ‘ID’: , // product identifier
 ‘URL’: ,
 ‘Type’: ,
 ‘ContentType’: ,
 ‘KeepAsUrl’: ,
 'Description': ,
 ‘Size’: , (optional) // in bytes
 ‘IsPrivate’: , (optional) // 0/1 or true/false
 ‘Updated’ : , (optional)
 ‘Language’: , // language code or locale code (if ambiguous)
 `isVideo`: // 0/1 or true/false
 },]
 },
 }

If mandatory fields weren’t filled in, the server responds with 404 HTTP status and the corresponding error message:

JSON
 ____________________________________________________________________
 404 Not Found
 {
 Status code:1
 Message: "Error: UserName, lang are mandatory fields"
 }

When content, for example, multimedia object (MMO), is absent and product is sponsored
(Open catalog), the server responds with a 200 OK HTTP status code:

 
 JSON
 ____________________________________________________________________
 200 OK
 {
 message: ‘OK’,
 ‘data’ :
 {
 'Multimedia': []
 }
 }

If the request is failed due to any reason mentioned above (see ‘Data retrieving algorithm’),
the server responds with 404 HTTP status and with the corresponding error message:

 JSON
 ___________________________________________________________________
 404 Not Found
 {
 message : “Shop The Icecat user is unknown”
 }

This is a live example from our database:

JSON
 ___________________________________________________________________
 message:"OK",
 • data:
 {
 • Multimedia:
 [
 • {
 • IcecatID:"1978657",
 • URL:"https://objects.icecat.biz/objects/12462305_1978657.mp4",
 • Type:"video/mp4",
 • ContentType:"video/mp4",
 • KeepAsUrl:0,
 • Description:"Video",
 • Size:"14623468",
 • IsPrivate:0*,
 • Updated:1426261310,
 • Language:"EN",
 • isVideo:1
 },
 • {
 • IcecatID:"1978658",
 • URL:"https://objects.icecat.biz/objects/12462305_1978658.mp4",
 • Type:"video/mp4",
 • ContentType:"video/mp4",
 • KeepAsUrl:0,
 • Description:"Video",
 • Size:"22487335",
 • IsPrivate:0,
 • Updated:1426261310,
 • Language:"EN",
 • isVideo:1
 },
 • {
 • IcecatID:"1978659",
 • URL:"https://objects.icecat.biz/objects/12462305_1978659.mp4",
 • Type:"video/mp4",
 • ContentType:"video/mp4",
 • KeepAsUrl:0,
 • Description:"Video",
 • Size:"20575036",
 • IsPrivate:0,
 • Updated:1426261310,
 • Language:"EN",
 • isVideo:1
 },
 • {
 • IcecatID:"2142148",
 • URL:"https://objects.icecat.biz/objects/12462305_2319.swf",
 • Type:"360",
 • ContentType:"application/x-shockwave-flash",
 • KeepAsUrl:0,
 • Description:"360",
 • Size:"776006",
 • IsPrivate:0,
 • Updated:1426261310,
 • Language:"EN",
 • isVideo:0
 }
 ],
 • demoAccount:false
 }
 }

Note!:  ‘IsPrivate:1′ means that this (asset) belongs to our private database, which is
accessible for authorized resellers only. ‘IsPrivate:0’ means that no further authorization is required to access the asset(s) involved.

Likethumbsup(7)Dislikesthumbsdown(0)

  • commented on December 2, 2017 by Henry

    Can we get examples or point us to it for retrieving products specifications of a product based on group (design, processortype, package containing, etc).

    Likethumbsup(0)Dislikesthumbsdown(0)
    • You will have first to download the specs of all products in a given category to populate your database, before you can run queries on single attributes.

      Likethumbsup(0)Dislikesthumbsdown(0)
  • commented on July 25, 2018 by Marco

    How can I make request with a valid username?

    Likethumbsup(0)Dislikesthumbsdown(0)
  • commented on February 20, 2019 by Jani Malin

    Hi,

    Currently all you examples just return: {"statusCode":1,"message":"UserName, lang are mandatory fields"}

    In your examples you have "language" as required field, but even switching between lang/language does not fix the situation.

    Br,
    --Jani

    Likethumbsup(0)Dislikesthumbsdown(0)
  • commented on May 29, 2019 by javi

    hi,

    i have one DB with Product code or Part number for example D-Link -> DGS-1210-24
    How can i get the Icecat code to this part number for example?
    i have the possibility the get code with URL or JSON.

    Likethumbsup(0)Dislikesthumbsdown(0)
  • commented on August 22, 2019 by Martin Horvath

    Hi Icecat,

    do you have plans to support multiple languages in a single request? Currently, I need to work around that with one call per language but that's neither efficient nor nice 🙂

    Best,
    Martin

    Likethumbsup(0)Dislikesthumbsdown(0)
  • commented on September 10, 2019 by Jeroen

    Hi Icecat,

    Is there a way to determine of I receive dutch or english texts, when requesting a product with the dutch language code.

    For example, when I try to get dutch texts for a specific product
    http://live.icecat.biz/api/?UserName=openIcecat-live&Language=nl&icecat_id=33593119

    I get english texts for the fields LongDesc and the Description field of some of the Features. (for example feature with ID:292392349, CategoryFeatureId: 50596 and CategoryFeatureGroupID: 6675.

    The texts are in english, but there is no Language field/flag available to determine if they are in English or in Dutch.

    Hope to hear from you soon,
    Kind regards,
    Jeroen

    Likethumbsup(0)Dislikesthumbsdown(0)

Leave a Reply

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Manual for Icecat URL: Integrating Links to Product Data Sheets and Images

Version: 1.21, August 28, 2019.The purpose of this post is to explain the Icecat URL method to get...
 October 4, 2018

Iceclog: Content Log and Playground for New Ideas like a Free Vendor Central and Social Media Functions

“Iceclog” (Icecat content log) is the Icecat blog, where you will find...
 June 26, 2019

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

Icecat Live is a (free) service that enables you to insert real-time product content from some hundr...
 June 1, 2018

Manual for Icecat CSV Interface

This document describes the CSV (Comma-Separated Values) variant of Icecat's Open Catalog Inter...
 September 28, 2016

Manual for Open Icecat JSON Product Requests

JSON (JavaScript Object Notation) is an increasingly popular means of transferring to data, comparab...
 September 17, 2018

Iceclog Editor Guidelines: Writing Compelling Posts

The Iceclog Editor Guidelines are a quick guide for contributors to the Iceclog blog or "cl...
 August 17, 2016

Manual for your Personalized Interface File and Catalog from Icecat

Via the Icecat website and login area, a user can generate personalized or customized CSV or Excel f...
 October 5, 2016

Icecat Add-ons including Magento, PrestaShop, Oracle, SAP Hybris, Google Shopping. NEW: Drupal.

Icecat has a huge list of integration partners, that make it easy for clients and free users, to mak...
 June 25, 2019

Manual for Testseek Product Reviews Integration via Icecat

Icecat provides aggregated expert reviews from its activity Testseek, as an add-on service for both ...
 October 19, 2015

Apple Watch: a Useful Tool or a Smart Toy?

After six months spent with my Apple Watch, I am still not sure if I consider it a useful tool or "j...
 September 30, 2016