Permalink
Fetching contributors…
Cannot retrieve contributors at this time
753 lines (565 sloc) 23.8 KB
---
title: feedspec
locale:
alve:
- 'en'
- 'tr'
skroutz:
- 'en'
- 'el'
---
<%= partial 'partials/page_locales' %>
<% if settings.feed_validator_domain.present? %>
> ##### Update
> You can use the <%= link_to "Data Feed Validator",
"http://#{settings.feed_validator_domain}" %> to validate your XML feed
according to <%= settings.site_name.capitalize %> standards.
{: .alert-success }
<% end %>
# XML Data Feed Specification <%= edit_link %>
This document describes the structure of the XML file provided by merchants to
<%= settings.site_name.capitalize %>. We do not require a specific document
template as long as the **required** product attributes are included
(<a href="#attributes">see attributes description</a>).
<%= partial 'partials/toc' %>
## Requirements
In general, the XML file must meet the following requirements:
* Clearly defines the document's encoding
* XML validates according to standards (you can check your XML's validity
<a href="http://validator.w3.org/">here</a>)
* Doesn't repeat the same products more than once (<a href="#unique-id">see Unique ID</a>)
* Includes V.A.T. in prices
<a href="#xml-example">Follow this link</a> for a valid XML example or
<a href="#xsd">read</a> the XSD definition of the XML.
<% if settings.feed_validator_domain.present? %>
Alternatively, <%= link_to "validate your XML feed",
"http://#{settings.feed_validator_domain}" %> against
<%= settings.site_name.capitalize %> standards.
<% end %>
## Technical Specifications
### <%= settings.site_name.capitalize %>Bot
<%= settings.site_name.capitalize %> uses a web crawler to download XML feeds.
It is identified with the HTTP header "User-Agent: <%= settings.site_name.capitalize %>Bot".
Although we call it a bot, it does not comply to the standard definition
(<%= link_to "www.robotstxt.org", "http://www.robotstxt.org/" %>).
<%= settings.site_name.capitalize %>Bot does not crawl the whole shop's site but
only the following URLs:
* the feed URL
* the feed file images URLs: <%= settings.site_name.capitalize %> downloads all products' images
* the feed file products URLs: <%= settings.site_name.capitalize %> downloads a sample of
the products for quality control
<%= settings.site_name.capitalize %>Bot originates from the follοwing IPs:
* **IPv6: 2a03:e40::/32**
* **IPv4: 185.6.76.0/22**
Make sure that the <%= settings.site_name.capitalize %>Bot IPs have always access
to the aforementioned URLs, without any rate limit.
> ##### Note
> It might be necessary to whitelist <%= settings.site_name.capitalize %>Bot’s
> URLs on some rate-limiting tools like BitNinja, Cloudflare etc.
>
><%= settings.site_name.capitalize %>Bot will maintain a reasonable rate of requests.
<%= settings.site_name.capitalize %>Bot accepts https links, but only those that
have an intermediate certificate signed by a CA(Certificate Authority) root certificate.
You can verify your certificate
<%= link_to "here", "https://www.ssllabs.com/ssltest/analyze" %> or
<%= link_to "here", "https://whatsmychaincert.com/" %>.
<%= settings.site_name.capitalize %>Bot does not do basic HTTP authentication or
any other kind of authentication.
The preferred method is to use IP access control lists.
<%= settings.site_name.capitalize %>Bot does not send an `Accept-Encoding` header
but it can handle gzip and zip compression. The shop's server should not deny access
to <%= settings.site_name.capitalize %>Bot if it uses exclusively gzip or zip compression.
> ##### Note
> An easy way to emulate the <%= settings.site_name.capitalize %>Bot is to use
> the linux program curl, for example: `curl -A "<%= settings.site_name.capitalize %>Bot v1.0" -i -L`
### Data Feed
For a Data Feed to be accepted all required attributes must be included
according to the standards described below.
## XML Declaration
The XML declaration head **must** include the encoding of the file
as well as the date it was created. The latter is used to determine if a feed is
outdated or not.
##### Example
~~~ xml
<?xml version="1.0" encoding="UTF-8"?>
<mywebstore>
<created_at>2010-04-08 12:32</created_at>
...
</mywebstore>
~~~
> ##### Note
> The encoding included in the XML header must correspond to the actual encoding
of the file otherwise your data feed may not be valid and your products will not
be updated. For example, a *UTF-8* declaration means that the file is encoded in
UTF-8.
> ##### Note
> If your data feed is not created on demand then you should take care that the
cached file is invalided and regenerated at least once a day.
## Attributes
The table below summarizes the product attributes recognized by
<%= settings.site_name.capitalize %>:
<div class="alert alert-danger">
<p>
You cannot include HTML notation in <strong>any</strong> of the product's
attributes.
</p>
</div>
Name | Type | Length | Required | Example
------------------------------------------------------ | ------------------------------ | ---------| --------------------------------------------
[Unique ID](#unique-id) | String | <span class="mono">200</span> | Yes | `322`
[Name](#name) | String | <span class="mono">300</span> | Yes | `Samsung Galaxy S4 16GB`
[Product Link](#product-link) | String | <span class="mono">1000</span> | Yes | `http://www.someurl.co.uk/products/322.html`
[Image Link](#image-link) | String | <span class="mono">400</span> | Yes | `http://www.someurl.co.uk/images/322.jpg`
[Additional Image Link](#additional-image-link) | String | <span class="mono">400</span> | No* | `http://www.someurl.co.uk/images/322/front_view.jpg`
[Category Name](#category-name) | String | <span class="mono">250</span> | Yes | `Mobile phones`
[Price](#price) | Decimal | <span class="mono">-</span> | Yes | `23.22`
[Availability](#availability) | String | <span class="mono">60</span> | Yes | `In 2 days`
[Manufacturer](#manufacturer) | String | <span class="mono">100</span> | Yes | `Samsung`
[MPN / ISBN](#mpn--isbn) | String | <span class="mono">80</span> | Yes | `GF322234`
[EAN / Barcode](#ean--barcode) | Integer | <span class="mono">13</span> | No | `9780471117094`
[Size](#size) | String | <span class="mono">500</span> | No* | `4,4.5,5-6,6 1/2`
[Weight](#weight) | Decimal | <span class="mono">-</span> | No** | `3200`
[InStock](#instock) | List | <span class="mono">-</span> | No | `Y`
[Shipping Costs](#shipping-costs) | Decimal | <span class="mono">-</span> | No | `3.22`
[Color](#color) | String | <span class="mono">100</span> | No*** | `Black`
<small>* Required by all fashion items with sizes, additional images</small><br />
<small>** Required by all shops that use weight in shipping cost rules</small><br />
<small>*** Required by all fashion items</small>
#### Unique ID
This attribute represents the **unique** identifier of a product in your
database. **The value of this field must remain the same through a product's
lifecycle and cannot be reused in other products**.
> If the title of a product **changes between updates** so that it
no longer refers to the same product (e.g. from *Sony LDF700* to *Sony LDF800*)
then the product will be **disabled**. It is important to note that
Unique IDs must always refer to the same product.
> A Unique ID cannot refer to **more than** one product. In such a
case the product will be updated only the first time it's encountered in the
data feed.
> In case your e-commerce application supports more than one languages your
data feed should only include definitions in the English language to avoid
duplication.
##### Example
~~~ xml
<UniqueID>32</UniqueID>
<product id="44">...</product>
<PRODUCTID>232AD</PRODUCTID>
~~~
#### Name
The title of the product. It is essential for the title to include all
necessary attributes of the product even though some of those attributes maybe
included in other parts of the XML as well (i.e. manufacturer, model, color,
version, part number, etc). The more accurate the title, the quicker the product
will be classified.
> The title of products that are second hand or refurbished must clearly state
their **condition** otherwise they will be disabled from the content team.
##### Example
~~~ xml
<Name>Nokia 5800 XpressMusic</Name>
<title>Nokia 5800 XpressMusic</title>
~~~
> Your product title should not include information about the product guarantee,
shipping costs, payment methods, special bundles or marketing actions.
#### Product Link
The URL that links to your shop's page for the specified product. It must be a
valid URL starting with `http` or `https`.
> Product links **should not** be URL-encoded.
> This link must only point to a product page and not a category page or a
collection of products page.
##### Example
~~~ xml
<link>http://www.mydomain.com/products/1</link>
<url>http://www.mydomain.com/products/product.php?itemid=1</url>
<url><![CDATA[http://www.mydomain.com/products/product.php?itemid=1&amp;somevar=3]]></url>
<url>http://www.mydomain.com/products/product.php?itemid=1&amp;amp;somevar=3</url>
~~~
#### Image Link
The product's image location. It must be a valid URL starting with `http` or
`https`. Links to scripts that generate images should be avoided as it may cause
download errors.
It's better to include high resolution images in your data feed. Images are
downloaded by <%= settings.site_name.capitalize %> and proper thumbnails are
created.
<div class="alert alert-danger">
<p>Images must not be watermarked.</p>
</div>
> Image links **should not** be URL-encoded.
> Avoid adding <code>No Image</code> template images because if you later change
it <%= settings.site_name.capitalize %> might not update it. If a product doesn't
have an image yet, you can just send an empty image link. If you later change it
the image will be updated normally.
> Images should have at least one dimension bigger than 400 pixels.
##### Example
~~~ xml
<image>http://www.mydomain.com/photos/1.jpg</image>
<imageurl>http://www.mydomain.com/photos/b&amp;amp;b.jpg</imageurl>
<url><![CDATA[http://www.mydomain.com/photos/b&amp;b.jpg]]></url>
~~~
#### Additional Image Link
It is used for additional photographs of the product. Additional
photos of the same product from different angles or with a different
presentation or combinations of the above add value to the presentation
of the product in <%= settings.site_name.capitalize %>.
This field is optional but recommended, except for fashion categories
where additional images are required. It can occur multiple times
in the feed, once for each different photograph. It has the same
limitations as [Image Link](#image-link).
> Images should have at least one dimension bigger than 400 pixels.
##### Example
~~~ xml
<image>http://www.mydomain.com/photos/1.jpg</image>
<imageurl>http://www.mydomain.com/photos/b&amp;amp;b.jpg</imageurl>
<additional_imageurl>http://www.mydomain.com/photos/product1/front.jpg</additional_imageurl>
<additional_imageurl>http://www.mydomain.com/photos/product1/sides.jpg</additional_imageurl>
<additional_imageurl>http://www.mydomain.com/photos/product1/packaged.jpg</additional_imageurl>
<url><![CDATA[http://www.mydomain.com/photos/b&amp;b.jpg]]></url>
~~~
#### Category Name
The product's category path. It is essential that this attribute includes the
full path of the product's category. For example, if the product is an `External
Hard Drive` then the category name attribute should look like
`Computers > External Hard Drives`
> Avoid ambigious categories containing different products (e.g. Printers and
Scanners) as it will slow down the classification process of your products.
##### Example
~~~ xml
<category>Mobile Phones > Bluetooth</category>
<category_path>Computers - Hardware - CPUs</category_path>
~~~
#### Price
It's the products retail price **including V.A.T**.
> The price of the product must apply to everyone without any special conditions
(e.g. offers, discounts pending on location etc).
#### Availability
This product's shipping availability as used throughout your shop.
<%= settings.site_name.capitalize %> uses a fixed set of availability
descriptions that will be crosslinked to the ones provided in your feed.
Available in store / Delivery 1 to 3 days
: refers to products that are available for pick up at your outlet.
Delivery 1 to 3 days
: refers to products that can be delivered to your customer within 1 to 3 days.
Delivery 4 to 10 days
: refers to products that can be delivered to your customer within 4 to 10 days.
Upon order
: refers to products that are ordered upon customer request.
#### Manufacturer
The manufacturer of the product
> The manufacturer name must be also include in the title regardless if it is
included in this attribute.
> The manufacturer attribute must point to the actual manufacturer of the product
and not the manufacturer this product is used for in cases of spare parts or
accessories.
#### MPN / ISBN
The unique manufacturer identifier of the product. It is used to identify a
product and classify it.
> This attribute is required for categories where the Manufacturer Product Number
is required to identify a product with different configurations (e.g. storage,
color, etc)
If the product is a **Book** then this field must include the `ISBN` of the book.
> Books without their ISBN information will not be classified
#### EAN / Barcode
The international article number
([EAN](https://en.wikipedia.org/wiki/International_Article_Number_(EAN)))
used for the identification of retail products.
> This attribute is optional but is strongly recommended for categories where
retail products have the same product brand but variations in weight, colour etc.
A unique EAN is allocated to each separate retail product.
#### Size
If the product comes in sizes you can include all available sizes in this
attribute seperated by commas.
For example, a sport shoe available in 5.5, 6, and 6.5 your `XML` will include
the following attribute
~~~ xml
<size>5.5,6,6.5</size>
~~~
You can also use `1/2` as a half size indicator
~~~ xml
<size>5 1/2,6,6 1/2</size>
~~~
In case of clothes, sizes can be in one of the following formats:
~~~ xml
<size>XXS, XS, S, M, L, XL, XXL, XXXL</size>
<size>Extra Small, Small, Medium, Large, Extra Large</size>
<size>00, 0, 2, 4, 6, 8, 10, 12, 14, 16</size>
~~~
If a product fits a size range (e.g. socks) then you can declare the size as a
*range* using the dash (-). e.g.
~~~ xml
<size>5.5-6.5</size>
~~~
Finally, if a product is identified by two sizes you can include them using the
forward slash. (/) e.g.
~~~ xml
<size>5.5/42,5.5/45</size>
~~~
> Products that are identified by sizes and the size information is not provided
will **not** be classified.
#### Weight
<% if flavor == 'alve' %>
The metric used by your platform to calculate shipping costs. This value is considered to
be in desi.
##### Example
For a product of `3.2 desi`, the value of the weight field should be:
~~~ xml
<weight>3.2</weight>
~~~
<% else %>
The product's weight used by your platform to calculate shipping costs in grams. If you wish to provide
it in kilograms you can do so by adding `kg` to the value string.
##### Example
For a product with a weight of `3.2kg`, the value of the weight field can be:
~~~ xml
<weight>3200</weight>
~~~
or
~~~ xml
<weight>3.2 kg</weight>
~~~
<% end %>
#### InStock
Stock status of the product
`Y`
: means that the product is in stock at your outlet or your warehouse and can be
picked up immediately.
`N`
: means that the product is not available in stock.
> When no information is provided the value of this attributed is considered as
`N` (no stock).
#### Shipping Costs
The product's shipping cost regardless of the customer's location. If the
product shipping cost is known beforehand you can include the shipping cost here.
If this product is eligible for free shipping, you can indicate it by providing
`0` as a value for this attribute.
> Shipping costs included here should be **independent** of the shipping
location. If this is not the case , then this attribute should be blank.
> Shipping costs will be displayed along with your other product information as
long as they are accurate every time. If, even for one product, shipping costs
are not accurate then they will be removed from all products in your data feed.
#### Color
The color of the product. The color attribute functions as a property of the
specific product and cannot cover multiple product entries.
It should contain the color of the product as depicted in the product image.
> In case multiple colors for a given model exist, they should be submitted
as different products with separate Unique IDs.
##### Example
~~~ xml
<color>Black</color>
<color>green</color>
~~~
<% if settings.feed_validator_domain.present? %>
## Data Feed Validator
<div class="row">
<div class="col-sm-12 col-md-8 text-justify">
<p>
You can use the <%= link_to "Data Feed Validator",
"http://#{settings.feed_validator_domain}" %> to check your XML feed for
compatibility with <%= settings.site_name.capitalize %> standards.
</p>
<p>
You can upload your XML file and the validator checks to confirm that it is
well-formed, according to the XML specification, tries to identify the XML
element corresponding to each one of your products and then scans the products'
attributes to ensure that <%= settings.site_name.capitalize %> requirements are met.
</p>
</div>
<div class="col-sm-12 col-md-4 text-center">
<% link_to "http://#{settings.feed_validator_domain}", class: 'btn btn-primary btn-lg btn-cta' do %>
Validate your XML
<i class="fa fa-append fa-angle-double-right"></i>
<% end %>
</div>
</div>
<% end %>
## XML Example
The XML excerpt below is an example of a compatible XML data feed.
~~~ xml
<?xml version="1.0" encoding="UTF-8"?>
<mywebstore>
<created_at>2010-04-08 12:32</created_at>
<products>
<product>
<id>322233</id>
<name><![CDATA[MadBiker 600]]></name>
<link><![CDATA[http://www.mywebstore.co.uk/product/322233]]></link>
<image><![CDATA[http://www.mywebstore.co.uk/product/322233.jpg]]></image>
<additionalimage><![CDATA[http://www.mywebstore.co.uk/product/322233/front.jpg]]></additionalimage>
<category><![CDATA[Outdor > Extreme Sports]]></category>
<price_with_vat>322.33</price_with_vat>
<manufacturer><![CDATA[SuperGlasses]]></manufacturer>
<mpn>ZHD332</mpn>
<ean>9780471117094</ean>
<instock>N</instock>
<availability>Pre Order</availability>
<size>5.5,6</size>
<weight>360</weight>
<color>Black</color>
</product>
...
...
...
</products>
</mywebstore>
~~~
## XSD
~~~ xml
<?xml version="2.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<!-- required elements -->
<!-- created at -->
<xs:element name="created_at" type="xs:dateTime" />
<!-- unique id -->
<xs:element name="uid">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="200" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<!-- name -->
<xs:element name="name">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="300" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<!-- link -->
<xs:element name="link">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="400" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<!-- image -->
<xs:element name="image">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="400" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<!-- additional image -->
<xs:element name="additional_image">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="400" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<!-- price -->
<xs:element name="price" type="xs:decimal" />
<!-- category -->
<xs:element name="category">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="300" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<!-- manufacturer -->
<xs:element name="manufacturer">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="100" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<!-- manufacturer part number -->
<xs:element name="mpn">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="100" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<!-- ean -->
<xs:element name="ean">
<xs:simpleType>
<xs:restriction base="xs:integer">
<xs:totalDigits value="13" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<!-- instock -->
<xs:element name="instock">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Y" />
<xs:enumeration value="N" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<!-- shipping -->
<xs:element name="shipping" type="xs:decimal" />
<!-- availability -->
<xs:element name="availability">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="100" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<!-- size -->
<xs:element name="size">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="100" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<!-- weight -->
<xs:element name="weight" type="xs:decimal" />
<!-- color -->
<xs:element name="color">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="50" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<!-- basic structure -->
<xs:element name="storedata">
<xs:complexType>
<xs:sequence>
<!-- created at -->
<xs:element ref="created_at" minOccurs="0" />
<!-- products -->
<xs:element name="products">
<xs:complexType>
<xs:sequence>
<!-- product -->
<xs:element name="product" maxOccurs="unbounded">
<xs:complexType>
<xs:all>
<!-- required fields -->
<xs:element ref="uid"/>
<xs:element ref="name"/>
<xs:element ref="link"/>
<xs:element ref="image"/>
<xs:element ref="price"/>
<xs:element ref="category"/>
<xs:element ref="manufacturer" />
<xs:element ref="mpn" />
<xs:element ref="availability" />
<xs:element ref="instock" />
<!-- optional fields -->
<xs:element ref="additional_image" minOccurs="0"/>
<xs:element ref="ean" minOccurs="0"/>
<xs:element ref="size" minOccurs="0"/>
<xs:element ref="weight" minOccurs="0"/>
<xs:element ref="shipping" minOccurs="0"/>
<xs:element ref="color" minOccurs="0"/>
</xs:all>
</xs:complexType>
</xs:element>
<!-- end product -->
</xs:sequence>
</xs:complexType>
</xs:element>
<!-- end products -->
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
~~~