Manual for Open Icecat JSON Product Requests

Avatar for Alexandr Kravtsov
By
Manual

JSON (JavaScript Object Notation) is an increasingly popular means of transferring data, comparable to XML. Under the hood, we use it in Icecat Live’s JavaScript applications. The main advantages of JSON are that it’s more efficient in data transfer and compatible with JavaScript applications requiring JSON. This manual explains the Open Icecat JSON product requests (Pull-API) call formats and the output. For Full Icecat JSON, we refer to the general Icecat JSON manual.

Other Integration Methods

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

Do you want to add product reviews? Then check out our reviews manual. If you’re looking to push brand product data to Icecat, check out the Push-API (JSON) manual. Further, check out the Add-On page for popular platforms already integrating Icecat data.

Important Notes about Icecat JSON

  1. Our JSON interface is relatively new, and certain aspects of our JSON interface 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 more in-depth insight into the Icecat data model, we refer to the XML document.
  3. In the 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 the 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 the data is not accessible or correctly available on our side. In case you experience any problems, contact us via the contact form.
  5. 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, requesting authorization from brands with which you have established formal relations via the Icecat website is good.
  6. The use of our data APIs, like JSON, requires and enables the user to host data and media assets in its own cloud environment.

Advantages of upgrading to Full Icecat

You can access the JSON interface 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 more brands. If you want to include specific brands in free Open Icecat, please, recommend Icecat to your manufacturer contacts.

Read more about the main advantages of Full Icecat over free Open Icecat and 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.

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, requires 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 website
  • to include explicitly an “AS IS” disclaimer, an example is here: https://www.icecat.biz/menu/disclaimer/index.html (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 on the generic JSON structures, it’s good to look into examples. Below are 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. More information regarding index files can be found here. 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 (take from Icecat index files):

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

The general URL structure is:
– product code & the brand’s name:

https://live.icecat.biz/api?UserName=&Language=&Content=&Brand=&ProductCode=

– GTIN (EAN, UPC or JAN code):

https://live.icecat.biz/api?UserName=&Language=&Content=&GTIN=

– Icecat ID:

https://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.
DescriptionThe 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:

https://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:
https://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:
https://live.icecat.biz/api?UserName=openIcecat-live&Language=en&Content=Multimedia&Brand=hp&ProductCode=RJ459AV

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

2. Working with JSON Output

Once you enter any request, for example,
https://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
 }
 }

In case the user wants to download JSON files of the Full Icecat product(s), he needs to make sure that his IP is whitelisted for the relevant Full Icecat user, and he requests the JSON files using App-Key. IP can be whitelisted by the user himself via the Icecat website. App-Key is the Icecat internal entity that we can provide on-demand for Full Icecat users. Users can request it from the relevant Icecat manager or general contact form

URL structures to request Full Icecat products JSON files are the same as for Open Icecat products described above, the only difference is that in the case of the Full Icecat products, URL structure should end with  &app_key=…. 

Full Icecat users can get app_key from the Icecat portal on “My Profile”

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.

Possible Error Messages

You can see all the error messages that you can get while using JSON files from Icecat via the following link

  • 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).

    • 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.

  • commented on July 25, 2018 by Marco

    How can I make request with a valid username?

    • 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.

    • commented on July 25, 2020 by Perin Raphaël

      Hello,
      I have exactly the same question :
      How can I make request with a valid username in JSON? (No problem with the XML)
      In your Manual, you talk about UserName but never about password :
      http(s)://live.icecat.biz/api/?UserName=&Language=&Content=&GTIN=
      it’s work but i read in the json object “Demo user…please get un account…”

      In Xml we use a context for the authentication.. But in json it’s doesn’t work :o(

      Is there a Manual somewhere on your site ? I found this : https://iceclog.com/manual-for-icecat-json-product-requests/ but no password.. only userName :o(

      Can you help me ?

      Thanks,

      Sorry for my broken english

      • commented on July 27, 2020 by Vazha Abramishvili

        Dear Perin
        In case of JSON call password is not required. You can use Open Icecat products data with only the user name. However, not sponsored products (Full Icecat) should be requested using App-Key. This is our internal entity which we can provide on demand once user signs Full Icecat contract.

  • 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

    • commented on February 20, 2019 by Laura van der Blom

      Dear Jani,

      One of my colleagues will contact you shortly to help you solve the problem.

      Kind Regards,
      Laura

  • 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.

    • commented on June 14, 2019 by Laura van der Blom

      Dear Javier,

      The responsible account manager for this will contact you soon to answer your questions.

  • 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

  • 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

  • commented on August 8, 2020 by Samaresh Ghosh

    What is sts code of philips HTD5520/94

  • commented on September 15, 2020 by Dmitry

    Good afternoon. I bought access to full cat. but when a request is formed, for example, for a product Huawei S1700-28FR-2T2P-AC switch, “he requested XML data-sheet is not described in the Icecat” is returned, although the product is in the ice cat. what could be the problem?

  • commented on October 14, 2020 by Anna

    Is there a way to add or list products with Icecat API or XML? Not only get or fetch data, also add products and listings.

  • commented on October 23, 2020 by John

    Hi

    I’m trying the JSON command in combination with the EAN code e.g. https://live.icecat.biz/api/?UserName=openIcecat-live&Language=en&GTIN=0882780751682
    This works fine but not for all EAN codes, eg. https://live.icecat.biz/api/?UserName=openIcecat-live&Language=en&GTIN=5060301694013 does not work,(error: {“statusCode”:4,”message”:”Product identifier(s) is not correct”}) altough the ean code exist in your database. How come?

  • commented on January 20, 2021 by A

    Hello,

    http://live.icecat.biz/api/?UserName=XXXXXX&Language=en&Brand=Silicon%20Power&ProductCode=SP032GBUF2810V1B

    gives “msg”: “OK” and some correct data, but in data -> dictionary
    “demo_insert_desc”: “This is a demo of a seamless insert of an Icecat LIVE product data-sheet in your website. Imagine that this responsive data-sheet is included in the product page of your webshop.”,
    “demo_msg_part1”: “You are using now a Demo account. Please, use your own Icecat account”,
    “demo_msg_part2”: “your Icecat login name”,
    “demo_msg_part3”: “If you don’t have an Icecat account, please register here for free.”,

    Is it ok? How to fix it? Thanks!

  • commented on February 21, 2021 by kleistu

    Hi,

    I am using free version now. Is there a way to check whether a specific product is included in the paid version but is not included in the free version?

  • commented on February 22, 2021 by kleistu

    Thanks for your quick answer. Is there a way to do this via api? Using free version for many items I get response (using ean to match):
    {“statusCode”:4,”message”:”Produkt Identifikator(en) sind nicht korrekt”}

    I would like to have a way to check via api if I upgrade to full version, will there be data for this product or not.

    • Dear

      We store information if the brand is the sponsor (Open Icecat) or not in the SuppliersList.xml.gz. This file can be found via the following link: https://data.Icecat.biz/export/freexml/refs/

      Further, the country manager of Germany at Icecat will contact you to help you in analyses of your portfolio, so you will know per product which product is in Open Icecat and which one in Full.

    • Status code “9”, which implies that the respective data-sheet can only be accessed through Full Icecat subscriptions.

  • commented on June 25, 2021 by Ricardo Castro

    Hi.
    Is there a way to make a request with many products and get the response through the API?

    Thanks in advance

    • Dear Ricardo

      It is impossible to make one request and get JSON files for several products but you can make requests simultaneously for up to 100 product data sheets and get JSON files for these products.

      Kind regards

      Vazha Abramishvili

  • commented on January 4, 2022 by Gatis

    Can we get EPREL product ID via Ice Cat?

    • commented on January 5, 2022 by Wouter Maatman

      Hello Gatis,

      It is possible to exclude it from EPREL link which is available in XMLs. For example:
      LabelType=”rescaled” EprelLink=”https://eprel.ec.europa.eu/qr/293144″/>

      In case of any further questions please contact your local country manager.

      Regards,
      Wouter

  • commented on August 30, 2022 by Peer

    Comparing the JSON with the XML request: for the JSON request the ProductPicture in the ProductGallery is not available in the raw format (XML attribute “Original”). Is it planned to add this to JSON and when?

    • commented on August 30, 2022 by Wouter Maatman

      Hi Peer, thanks for your comment. A country manager will contact you asap. Regards, Wouter

  • commented on December 17, 2022 by wineloy

    Does anyone know if it’s normal that even replacing the name openIcecat-live with my account name in the URL, it still shows up in some dictionary node properties?
    “demo_msg_part1”: “You are now using a demo account. Use your own Icecat account” ?

    In theory I already have my own account

    • commented on December 19, 2022 by Wouter Maatman

      Hi Wineloy, thanks for reaching out. A country manager will contact you asap. Regards, Wouter

  • commented on March 26, 2023 by Hannibal

    Hello, I encountered the same problem that @Wineloy. any solution please?

    Is it possible to batch download the images associated with the product ?

    Best regards,
    Hannibal

    • commented on March 27, 2023 by Wouter Maatman

      Hello Hannibal, thanks for your question. Can you please share the product you are trying to test and your username? Then our support team can look into the issue.

      Regarding the batch download, there is the possibility to download the bach images per product only via PCF.

      Regards,
      Wouter

  • commented on May 4, 2023 by Udeep

    May I know how to make a HTTP Get Request for a give EAN number ? Also is there a pre-defined XSD that IceCat provides based on which we can create our model ? Please can you direct me. Thank you in advance.

    • commented on May 5, 2023 by Wouter Maatman

      Hello Udeep, thanks for your comments. Our country manager will contact you today. Regards, Wouter

  • commented on October 26, 2023 by Ben Brown

    Hello,

    is it possible to get more then one language per request ? Currently i have to make a call for each Language which slows down the whole process a bit.

    Regards
    Ben

  • commented on October 26, 2023 by Ben Brown

    Thanks for the fast answer, is there any ETA when this will be Supported through JSON API ?
    We are currently using a extremly modified Version of your Pimcore Bundle Plugin and this worked with JSON from the beginning , so switching from json to xml would have too much impact

    • Sorry, Ben, we have no ETA for combined multilingual data through JSON. It’s a known wish though. When we have it planned, we will message this.

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