Reference Guide - Feeds

From SRP API Docs

Feeds

This section defines general StructuredRetailProducts.com API feed functionality.

Available feeds are:

<protect>

</protect>

Feed formats

Feeds can be returned in 2 formats:

  • XML

<protect>

  • JSON

</protect>

By default XML format is used. To specify format manually use format option:

Option name Possible values Description
format json/xml Specifies return format

Sample:

format=xml

XML

XML 1.0 version is used with UTF-8 encoding.

Every XML document will have a root element. All data will be inside the root element. Root element will be named accordingly to the requested functionality. E.g. for product feed it will be products.

Response also will have a status element which will contain status code and status message. Depending on the status code warning and/or errors will be provided. Status codes are defined here.

If debugging is switched to on debug element will be included.

Feed will always return a collection of items as list element, even if only one item is in collection

Sample:

<?xml version="1.0" encoding="UTF-8"?>
<products>
  <status code="StatusCode">StatusMessage</status>
  <debug>
    ...
  </debug>
  <list count="500" from="0" to="499" total="900">
    ...
  </list>
  ...
<products>

<protect>

JSON

Not implemented </protect>

Navigation

StructuredRetailProducts.com API will return only a certain number of items per request. By default it is 500 first records. Feed will include navigation information which will have this information:

  • count - number of returned items
  • from - position of first returned item
  • to - position of last returned item
  • total - total number of found records

Sample:

<list count="500" from="0" to="499" total="900">
...
</list>

First item position and number of items to return can be specified using from and count options:

Option name Possible values Description
count signed integer. Minimum 1, maximum 500 Specifies number of items per feed
from signed integer, Minimum 0, no maximum Specifies first item position in feed

Request sample:

count=100&from=100

Response when 150 items are found:

<list count="50" from="100" to="150" total="150">
...
</list>

When no items are found matching search criteria, empty feed will be returned:

<list count="0" from="0" to="0" total="0">
</list>

Getting more than 500 products

Maximum number of records per request is 500. If you need to retrieve more products, you will have to make several calls.

E.g. 1500 products can be retrieved in 3 requests:

/v1/products/products?market=MK0013&count=500&from=0
/v1/products/products?market=MK0013&count=500&from=500
/v1/products/products?market=MK0013&count=500&from=1000

Ordering

By default latest items comes first in the feed. To specify a different ordering please use order and direction options:

Option name Possible values Description
order Depends on feed. See Product ordering and Product group ordering Specifies ordering column for feed
direction asc/desc Specifies ordering direction for feed

Sample:

order=maturity&direction=desc

<protect>

Debugging

TODO: this is not implemented yet

By default debugging information will not be included in response. To include it use debug option.

Option name Possible values Description
debug yes/no Includes or not debugging information in response.

Debug data will include

  • request uri
  • filters provided in request
  • order by option provided in request
  • limit option provided in url

XML debug block structure

<debug>
  <uri>RequestUri</uri>
  <filters>
    <filter>
      <name>FilterName</name>
      <value>FilterValue</value>
    </filter>
    ...
  </filters>
  <limit>
    <count>NumberOfItemsPerRequest</count>
    <from>PositionOfFirstItem</from>
  </limit>
  <order>
    <name>OrderByName</name>
    <direction>OrderByDirection</direction>
  </order>
</debug>

Request sample:

/v1/products/products?market=MK0012&order=maturity&direction=desc&from=100&count=10&debug=yes

Response sample

<debug>
  <uri>/v1/products/products?market=MK0012&order=maturity&direction=desc&from=100&count=10&debug=yes</uri>
  <filters>
    <filter>
      <name>market</name>
      <value>MK0012</value>
    </filter>
  </filters>
  <limit>
    <count>10</count>
    <from>100</from>
  </limit>
  <order>
    <name>maturity</name>
    <direction>desc</direction>
  </order>
</debug>

</protect>