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.

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)
    • commented on December 5, 2017 by Martijn Hoogeveen

      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 September 24, 2018 by Laura van der Blom

      Hi Marco,

      Thanks for your interest in our service. A colleague of mine will contact you shortly via email.

      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.

open-live-optimized

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 300 m...
 June 1, 2016
World map

Iceclog: Our Content Log and Playground for Testing New Ideas

“Iceclog” (Icecat content log) is the Icecat blog, where you will find...
 August 26, 2016
http url

Manual for Icecat URL: Links to Product Data-sheets and Images

Version: 1.20, October 4, 2016.The purpose of this post is to explain the Icecat URL method to ...
 October 4, 2015
open-csv-optimized

Manual for Icecat CSV Interface

This document describes the CSV (Comma-Separated Values) variant of Icecat's Open Catalog Interface...
 September 28, 2016
wall-writer-in-action

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
open-personalized-csv-optimized

Manual for Personalized Interface File and Catalog

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

Manual for Open Icecat JSON Product Requests

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

Icecat Add-ons for Magento, PrestaShop and other Popular Solutions

Icecat has a huge list of integration partners, that make it easy for clients and free users, to mak...
 October 15, 2018
apple_watch_series1

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

Manual for Testseek Product Reviews Integration via Icecat

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