The JSON product list service gives you endless possibilities of displaying your products in any way you wish – with no constraints to design or functionality. The JSON product list also enables you to create multiple product lists and place them anywhere in the shop.

The JSON product list service produces a JSON formatted list of products. By making a call to the service, a JSON object is returned containing products and virtually all associated data. This means that you are able to display any information available about the products directly in the product list – for instance product name, product number, sales price(s), manufacturer, gross weight or expected delivery date. In the Fields section you see a full list of available product data when using the JSON product list service.

The product lists are cacheable, both server side, on a CDN and in the local browser cache which means that performance is excellent even for large product lists. JSON product lists may thus display stale date for at least 30 minutes after an update. It should be noted however that the adding a deleted product or a product with a stale price to the basket will result in correct prices in the basket.

Contents

• Why JSON?
• Services
  • Service: ProductList
  • Service: Products
  • Service: RelatedProducts
  • Service: ProductVariants
• ImageHandler
• SEO considerations when using the JSON product list
• Performance considerations when using the JSON product list
• Adding the JSON product list to a shop

Why JSON?

To the top

JSON (JavaScript Object Notation) is a lightweight human-readable syntax for storing and exchanging data. The JSON format is syntactically identical to the code for creating JavaScript object and hence can be parsed using standard JavaScript functions (or for instance jQuery) - however JSON is language independent and thus can be used with most of the modern programming languages.

JSON is hierarchical (values within values) and data consists of name/value pairs. JSON uses objects and arrays as data structures and numbers, strings, Booleans, and null as values.

Below is a simple example of the JSON syntax. Note that this example does not reflect the actual structure of data returned by the eSeller Cloud JSON product list service.

JSON example

{
“productID” : “KL2432”,
“productName” : “Hugo Boss men’s suit”,
“productPrice” :  2500, 
“productPriceFormatted” : “DKK 2.500,00” 
“inStock” : true, 
“relatedProducts”: [
      {“productID”: “KL2532”},
      {“productID”: “KL2341”}
]
}

Further information

Learn more about the JSON format here.

Services

To the top

The services accept HTTP GET requests. Note that some versions of Internet Explorer enforce a maximum request length of 2kb.

The currently available services are:

www.esellercloud.com/Services/ProductService.asmx/ProductList?v=VERSIONNUMBER

www.esellercloud.com/Services/ProductService.asmx/Products?v=VERSIONNUMBER

www.esellercloud.com/Services/ProductService.asmx/ProductVariants?v=VERSIONNUMBER

www.esellercloud.com/Services/ProductService.asmx/RelatedProducts?v=VERSIONNUMBER

Where VERSIONNUMBER is the desired format version number. Currently only one version number exists:

www.esellercloud.com/Services/ProductService.asmx/ProductList?v=1.0

A request to the JSON product service can be tailored to suit your needs by using the available parameters accordingly. Below is an overview of the parameters that the request consists of grouped by service.

Response

Headers

The response will have the following headers:
- Pragma: public
- Max-age: 21600
Cookies will never be set in the response

Data

Data will be formatted according to https://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml. The response will contain EITHER a data container OR an errors container but never both. The response may contain up to 1000 products. Products will be sorted according to sort order or the sorting directive given in the request (so parameter). Salesprices will be sorted by quantity ascending.

Service: ProductList

To the top

The "ProductList" service is generally used for retrieving products for the main product lists (e.g. lists of products in menus) or as the search result list. Only products that have at least one menu relation will be included in JSON results.

The table below displays all available parameters for the "ProductList" service. The service is located at www.esellercloud.com/Services/ProductService.asmx/ProductList?

Example requests

Get all products from a specific menu

/Services/ProductService.asmx/ProductList?v=1.0&so=1&cId=54&langId=1&countryId=11&locId=&customerId=r/PBJU4aAIz+OJ40XGWJnXjFTdjb2123456P2geSqRDk4sEdN8Hasg==&mId=6692&p=1&rp=25&imgSizeId=0

- Get all products from the product menu with menu ID 6692

Set multiple filters in one request

/Services/ProductService.asmx/ProductList?v=1.0&so=1&cId=54&langId=1&countryId=11&locId=&customerId=r/PBJU4aAIz+OJ40XGWJnXjFTdjb2123456P2geSqRDk4sEdN8Hasg==&mId=1302&p=1&rp=5&imgSizeId=0&fn1=ProductVariants&fv1=443^441^445&fn2=ProductPrice&fv2=1500~7000&fn3=CustomFields&fv3=Cotton&fk3=Material

- In this request a product variant filter is set to filter on the variant values with ID 443, 443 and 445 (note that “^” means “and”. Moreover, a price filter is set to all products with a price between 1500 and 7000 (note that "~" is used to specify a price range). Lastly, a filter is set to only show products that have the custom field “Material” with the custom field value “Cotton”.

Set range filters

/Services/ProductService.asmx/ProductList?v=1.0&so=1&cId=54&langId=1&countryId=11&locId=&customerId=r/PBJU4aAIz+OJ40XGWJnXjFTdjb2123456P2geSqRDk4sEdN8Hasg==&mId=1302&p=1&rp=25&imgSizeId=0&fn1=CustomFields&fk1=Length&fv1=125~658&fn2=CustomFields&fk2=Height&fv2=68.5~105.5

- In this request two custom field range filters are set; Length between 125 and 658 (both inclusive) and Height between 68.5 and 105.5 (both inclusive). Note that decimal values must use "." as decimal mark.

Perform a SMART search query

/Services/ProductService.asmx/ProductList?v=1.0&cId=54&langId=1&countryId=11&locId=&customerId=r/PBJU4aAIz+OJ40XGWJnXjFTdjb2123456P2geSqRDk4sEdN8Hasg==&p=1&rp=25&imgSizeId=0&maxSearchResults=100&search=ralph%20lauren%20polo

- Performs a SMART search of the query "ralph lauren polo" and returns the result as JSON (BETA).

Perform a SMART search query for a specific location

/Services/ProductService.asmx/ProductList?v=1.0&cId=54&langId=1&countryId=11&locId=1422&customerId=r/PBJU4aAIz+OJ40XGWJnXjFTdjb2123456P2geSqRDk4sEdN8Hasg==&p=1&rp=25&imgSizeId=0&maxSearchResults=100&search=coca%20cola

- Performs a SMART search of the query "coca cola" for the location with ID 1422 and returns the result as JSON (BETA).

Gets a list of products from a specific product collection

/Services/ProductService.asmx/ProductList?v=1.0&cId=54&langId=1&countryId=11&locId=1422&customerId=r/PBJU4aAIz+OJ40XGWJnXjFTdjb2123456P2geSqRDk4sEdN8Hasg==&p=1&rp=25&imgSizeId=0&pcEId=summer2016

- Gets all products from the product collection with ext. ID "summer2016".

Gets a list of products based on a product collection tag

/Services/ProductService.asmx/ProductList?v=1.0&cId=54&langId=1&countryId=11&locId=1422&customerId=r/PBJU4aAIz+OJ40XGWJnXjFTdjb2123456P2geSqRDk4sEdN8Hasg==&p=1&rp=25&imgSizeId=0&pcTag=bargains

- Gets all products from all product collections with the tag "bargains".

Response

Below you see all fields provided in the JSON response

Service: Products

To the top

Using the "Products" service you are able to generate lists containing specific products. Using the "pIds" parameter you are able to specify which products you want to be retrieved in the JSON result.

The table below displays all available parameters for the "Products" service. The service is located at www.esellercloud.com/Services/ProductService.asmx/Products?

Example requests

Get a list of specified products

/Services/ProductService.asmx/Products?v=1.0&cId=54&langId=1&countryId=11&locId=&customerId=r/PBJU4aAIz+OJ40XGWJnXjFTdjb2123456P2geSqRDk4sEdN8Hasg==&imgSizeId=0&pIds=113386;113387

- Gets a list that contains the products with ID 113386 and 113387. Semicolon divides the product IDs.

Response

Below you see all fields provided in the JSON response

Service: RelatedProducts

To the top

The "RelatedProducts" service returns a list of related products for a specified product ID. The "tag" parameter can be added to limit the result to related products with a specific tag - e.g. "sparePartsFor".

The table below displays all available parameters for the "RelatedProducts" service. The service is located at www.esellercloud.com/Services/ProductService.asmx/RelatedProducts?

Example requests

Get a list of related products with a specified tag

/Services/ProductService.asmx/RelatedProducts?v=1.0&cId=54&langId=1&countryId=11&locId=&customerId=r/PBJU4aAIz+OJ40XGWJnXjFTdjb2123456P2geSqRDk4sEdN8Hasg==&imgSizeId=0&pId=113386&maxResults=10

- Get all products related to the product with ID 113386 - maximum 10 results.

Get all related products for a product specified with external ID

/Services/ProductService.asmx/RelatedProducts?v=1.0&cId=54&langId=1&countryId=11&locId=&customerId=r/PBJU4aAIz+OJ40XGWJnXjFTdjb2123456P2geSqRDk4sEdN8Hasg==&imgSizeId=0&pEId=KL012Y

- Get all products related to the product with external ID KL012Y.

Response

Below you see all fields provided in the JSON response

Service: ProductVariants

To the top

The "ProductVariants" service returns all product variants of a main variant product.

The table below displays all available parameters for the "ProductVariants" service. The service is located at www.esellercloud.com/Services/ProductService.asmx/ProductVariants?

Example Requests

Get all product variants for a main variant product

/Services/ProductService.asmx/ProductVariants?v=1.0&cId=54&langId=1&countryId=11&locId=13&imgSizeId=0&pId=113381

- Get all variants of the product with ID 113381 (a main variant product).

Response

Below you see all fields provided in the JSON response

ImageHandler

To the top

The ImageHandler is a service that is able to provide productImages. The ImageHandler Service is referenced from the output of the JSON product list.

ImageHandler returns a product image encoded with mime type: image/jpeg if the provided imageid is found, otherwise a 404 page is shown.

The ImageHandler requires two case sensitive parameters: imgId and sizeId
imgId is an internal image id as provided by the json service
sizeId is the internal image size id

Possible image size ids can be found in the shop administration under Home >> Design >> Overall design >> Image Sizes.

The image size id can be found by hovering the mouse over one of the image sizes and making note of the parameter “isid” which is equivalent of the sizeId

Any other parameters added to the ImageHandler url will negatively affect the load speed and will be discarded by the CDN

SEO considerations when using the JSON product list

To the top

Previously, webcrawlers such as Googlebot, did not render javascript generated pages. This meant that it was necessary to use a special method to allow those crawlers to index the pages. This method, named _escaped_fragment_, has however been deprecated by recent advances in the abilities of crawlers. It is no longer necessary to take any special precautions to allow crawlers to index JSON based product list.

Shops that are using the _escaped_fragment_ method can continue to do so without any detrimental effect on ranking and indexing whereas new shops could and should omit implementation of the escaped fragment standard.

Performance considerations when using the JSON product list

eSeller Cloud uses extensive caching to ensure great performance when getting product lists, but naturally the number of products returned by the service has great influence on how well it performs in terms of response times.

We recommend being very observant of the number of products one tries to get using the service and do not recommend anyone attempting to get lists containing more than 5000 products, as performance may suffer.

Adding the JSON product list to a shop

To the top

If your webshop already has a product list, you can simply change the control that renders the product list. To do so, go to Design > Overall design > Other content design (in drop-down selector) and select the content design for your product list.

Go to the Definition tab and locate the product list control (the control with ControlType “ProductList”):

<eSeller:Control ControlType="ProductList" Controlid="ProductList" IsMainProductlist="True" /> 

Change the control to the following:

<eSeller:Control ControlType="JsonProductList" Controlid="JsonProductList" IsMainProductlist="True" TestMode="False" />

- which is the control rendering the JSON product list. If TestMode is set to “True”, the JSON result will be rendered as plain text in the content element. This mode is only suitable for testing – the script generating the plain text rendering (jsonProductList.js) should not be used for anything but testing. When TestMode is set to “False” all logic responsible for retrieving and displaying information must be provided by the designer.

Re-saving product sorting elements and product filters

The JSON product list works with product sorting elements and product filters, however it might be necessary to update the elements by re-saving them in the shop administration – note that this only applies to shops using product sorting and/or product filtering.

Re-save product filters by navigating to Stock > Product Filtering and click the “Manage product filtering menu” button – click “Save”.

Re-save the product sorting element by navigating to Stock > Product Sorting and click the “Manage product sorting element” button – click “Save”.