Basic Format

The PersonaClick product feed is based on YML (Yandex Market Language), a more detailed description of which is available in the Yandex help section at the link: https://yandex.com/support/partnermarket/yml/about-yml.html

Supported Encodings

UTF-8
Windows-1251

Main elements

Element	Required	Description
xml	required	Standard XML header. The header should start from the first line with the null character.
yml_catalog	required	Any XML document can contain only one root element. The YML format uses the `yml_catalog` element as the root element.
shop	required	This element contains a description of the store and its products.

"xml"

Available attributes:

Attribute	Required	Description
version	required	XML language version. Version "1.0" must be used.
encoding	required	XML encoding used.

Example:

<?xml version="1.0" encoding="UTF-8"?>

"yml_catalog"

Available attributes:

Attribute	Required	Description
date	required	The date attribute of the `yml_catalog` element must match the date and time the YML file was generated on the store side. The date should be in the `YYYY-MM-DD hh:mm` format.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-04-26 17:19">
    ...
</yml_catalog>

"shop"

shop's child elements:

Element	Required	Description
name	required	The short name of the store.
company	required	Full name of the company that owns the store.
url	required	URL of store's home page.
currencies	required	List of store's exchange rates.
categories	required	List of store's categories.
locations	optional	List of store's locations.
offers	required	List of store's products.

"name"

Example:

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-04-26 17:19">
    <shop>
        <name>My store</name>
        ...
    </shop>
</yml_catalog>

"company"

Example:

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-04-26 17:19">
    <shop>
        ...
        <company>My company</company>
        ...
    </shop>
</yml_catalog>

"url"

Example:

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-04-26 17:19">
    <shop>
        ...
        <url>https://my-store.com</url>
        ...
    </shop>
</yml_catalog>

"currencies"

The currencies element sets a list of the store's exchange rates. Each currency is described in a separate currency element.

The currency element attributes are:

Attribute	Required	Description
id	required	The `id` attribute of the `currency` element specifies the code of a particular currency that can be used in the YML file.
rate	required	The `rate` attribute specifies the exchange rate between the selected currency and the main currency taken as a unit (currency for which `rate="1"`). All numbers in YML use the dot as the decimal separator, regardless of regional settings (never use the comma).

Example:

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-04-26 17:19">
    <shop>
        ...
        <currencies>
            <currency id="TRY" rate="1"/>
            <currency id="USD" rate="6.45"/>
            <currency id="EUR" rate="7.12"/>
            ...
        </currencies>
        ...
    </shop>
</yml_catalog>

"categories"

The parent element categories describes the list of store categories in YML format. Each category is described in a separate category element.

The category element attributes are:

Attribute	Required	Description
id	required	The category identifier.
parentId	optional	The parent category identifier.
url	optional	Category page URL.
alias	optional	Wordy category identifier

Example:

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-04-26 17:19">
    <shop>
        ...
        <categories>
            <category id="2" url="http://my-store.com/categories/discount/">Sale</category>
            <category id="8" url="http://my-store.com/categories/men/">Men</category>
            <category id="13" parentId="8" url="http://my-store.com/categories/men/shoes/">Shoes</category>
            <category id="97" parentId="13" alias="men/shoes/leather" url="http://my-store.com/categories/men/shoes/leather">Leather Shoes</category>
            ...
        </categories>
        ...
    </shop>
</yml_catalog>

"locations"

The locations element sets a list of the store's locataions. Each location is described in a separate location element.

The location element attributes are:

Attribute	Required	Description
id	required	The location identifier.
parentId	optional	The parent location identifier.
type	optional	The location type. Available values are: city, store.
name	optional	The location name.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-04-26 17:19">
    <shop>
        ...
        <locations>
            <location id="1" type="city" name="Los Angeles" />
            <location id="2" type="city" name="Istanbul" />
            <location id="145" parentId="1" type="store" name="Central District store" />
            ...
        </locations>
        ...
    </shop>
</yml_catalog>

"offers"

The offers element sets a list of the store's products. Each offer is described in a separate offer element.

Please note, the offer element cannot contain a product variant, only the product itself. If in your store all variants of product are on the same page and there is no common product identifier then you need to use one of the variant as the main one - its identifier, price and other data. Usually, the low cost variant is chosen as the main one and the availability flag in this case should fit into the following logic: if at least one variant is in stock then the product should be marked as available.

The offer element attributes are:

Attribute	Required	Description
id	required	The product identifier.
available	required	The product availability. Available values are: true, false.
leftovers	optional	Rough number of the products left in stock. Available values are: one - one product few - 2-10 products lot - over 10 products

offer's child elements:

Element	Required	Description
name	required	Full offer name that includes: product type, manufacturer and product name. See the following elements for separate use: typePrefix, vendor, model.
picture	required	Product image URL.
price	required	Base product price.
url	required	URL of the product page on the store's website.
categoryId	required	Product category ID assigned by the store. It's possible to use several of these elements.
locations	optional	Element describing the properties of a product in different locations: availability, price. See table and example below.
accessories	optional	Element describing the list of accessories for the current product. See example below.
customerRecommendations	optional	Element describing the list of custom recommended products for the current product. See example below.
oldprice	optional	The old price of the product should be higher than the current one.
price_margin	optional	Relative marginality (priority) of the product (from 0 to 100).
barcode	optional	Product manufacturer's barcode in one of the following formats: EAN-13, EAN-8, UPC-A, or UPC-E.
typePrefix	optional	Type/category of product (for example: "mobile phone", "washing machine", "corner sofa").
vendor	optional	Manufacturer/brand.
vendorCode	optional	Manufacturer product code.
model	optional	Model and product name.
seasonality	optional	Product seasonality. The sequence number of the month (from 1 to 12) is used as the value. These elements may be several.
is_new	optional	It can take only one value - "1", which means that the product is new.
rating	optional	Product rating. Integer value from 0 to 5, where 0 is a product without a rating, 1-5 is a rating.
description	optional	Product description.
stock_quantity	optional	The available quantity of products. Integer value from 1 and more.
tags	optional	Element describing the tags associated with the product, for accurate search. See the table and example below.
param	optional	Element describing any custom parameter. See the table and example below.

"locations"

The locations element contains a list of locations, includes the current product availability and price in locations. Each location is described by a separate location element.

The location element attributes are:

Attribute	Required	Description
id	required	Locations identifier. Must match one of the locations (identifier) described in `shop`/`locations` list. More information about the location, see the subsection above and in the example below.

Please note, the product will be considered available for purchase only in the locations listed in the offer element, in all other known but not listed locations the product will be considered unavailable for purchase.

Child elements:

Element	Required	Description
price	optional	Product price in location. The product will use the base price if this element is missing.
oldprice	optional	Product old price in location. The product will use the base old price if that exists and this element is missing.

"tags"

The tags element contains a list of tags that relate to the product. Each value is described by a separate tag element.

Element	Required	Description
tag	optional	Tag value.

"param"

One param element describes one characteristic. The offer element can contain any number of param elements.

<param name="ANY_NAME" unit="MEASUREMENT_UNIT">VALUE</param>

Item	Property type	Required	Description
name	attribute	required	In this attribute, specify the parameter name.
unit	attribute	required for numeric values	In this attribute, specify the measurement units.

Full Basic Example

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-04-26 17:19">
    <shop>
		<name>My store</name>
		<company>My company</company>
		<url>https://my-store.com</url>
		<!-- list of store currencies and exchange rates -->
        <currencies>
            <currency id="TRY" rate="1"/>
            <currency id="USD" rate="6.78"/>
            <currency id="EUR" rate="7.56"/>
        </currencies>
		<!-- list of all store categories, their hierarchies and links -->
        <categories>
            <category id="2" url="http://my-store.com/categories/apple/">Apple</category>
            <category id="13" parentId="2" alias="apple/phones" url="http://my-store.com/categories/apple/phones/>Phones</category>
        </categories>
		<!-- list of all store locations -->
        <locations>
            <location id="1" type="city" name="Los Angeles" />
            <location id="2" type="city" name="Istanbul" />
			<location id="3" type="city" name="London" />
        </locations>
		<offers>
			<offer id="395532" available="true" leftovers="few">
				<url>http://my-store.com/items/395532</url>
				<price>50000</price>
				<oldprice>55000</oldprice>
				<price_margin>67</price_margin>
				<!-- list of categories hierarchies in which this product is present -->
				<categoryId>2</categoryId>
				<categoryId>13</categoryId>
				<!-- Seasonality list. Priority months for this product: January, March, April, June. -->
				<seasonality>1</seasonality>
				<seasonality>3</seasonality>
				<seasonality>4</seasonality>
				<seasonality>6</seasonality>
				<!-- product locations list and the price in the location -->
				<locations>
					<location id="1">
						<price>70000</price>
						<oldprice>75000</oldprice>
					</location>
					<!-- id="2" location is not specified, it means this product isn't available in this location -->
					<!-- price for id="3" location is not set, it means the price is equal to the base price -->
					<location id="3"></location>
				</location>
				<!-- list of product IDs that are accessories for the current product -->
				<accessories>
					<accessory id="5574" />
					<accessory id="131" />
					<accessory id="99444" />
					<accessory id="334411" />
				</accessories>
                <tags>
                    <tag>phone</tag>
                    <tag>smartphone</tag>
                </tags>
				<customerRecommendations>18,21,146,100500</customerRecommendations>
				<barcode>123456</barcode>
				<picture>https://my-store.com/items/395532.jpg</picture>
				<name>Apple Iphone 7 128 gb</name>
				<typePrefix>Smartphone</typePrefix>
				<vendor>Apple</vendor>
				<vendorCode>APPL</vendorCode>
				<model>iPhone 7 128Gb</model>
				<is_new>1</is_new>
				<rating>5</rating>
				<param name="display" unit="inch">5.5</param>
				<param name="material">aluminum</param>
				<param name="Wi-Fi">true</param>
				<description><![CDATA[The moment you connect with iPhone 7, you will know you've never felt anything like it. With a single press, 3D Touch lets you do more than ever before. Live Photos bring your memories to life in a powerfully vivid way. And that's just the beginning. Take a deeper look at iPhone 7, and you'll find innovation on every level.]]></description>
			</offer>
			<offer id="395533" available="false">
				...
			</offer>
			...
		</offers>
    </shop>
</yml_catalog>

Additional Niches Data

Additional niche parameters of products allow studying user preferences and calculating recommendations more accurately. If there are products from the niches listed below in the product catalog, you should add this extended data to the product feed.

Niche	Description
Apparel & Accessories	Allows filling the product feed with niche features of apparel and accessories.
Auto Products	Allows filling the product feed with vehicle niche features.
Baby & Children	Allows filling the product feed with niche features of products for children and babies.
Construction & Repair	Allows filling the product feed with niche features of products for construction and repair.
Cosmetics & Perfumes	Allows filling the product feed with niche features of cosmetics and perfumes.
Fast-Moving Consumer Goods (FMCG)	Allows filling the product feed with niche features of Fast-Moving Consumer Goods (FMCG).
Jewelry	Allows filling the product feed with jewelry niche features.
Pet Products	Allows filling the product feed with niche features of pet products.
Real Estate	Allows filling the product feed with niche features of real estate.

Creating the XML file

If you create the XML file on request, you should make sure that the time to creating the file and download it by the system doesn't take more than 10 minutes. Otherwise, you should create a static XML file at specified intervals and give it to the system when the product feed is requested. Additionally, you can use GNU GZIP file compression. If the time limit is still not enough, you should use HTTP API to import the product catalog.

Multiple Requests

The system makes multiple simultaneous requests to download product feed and product images. It's necessary to whitelist the IPs below if any request limiting is applied on your side.

IP	User-Agent	Requests Rate
88.99.209.134	PERSONACLICK Fetcher 1.0	50/sec
88.99.217.82	PERSONACLICK Fetcher 1.0	50/sec
94.130.90.232	PERSONACLICK Fetcher 1.0	50/sec

XML Product Feed

Basic Format

Supported Encodings

Main elements

"xml"

"yml_catalog"

"shop"

"name"

"company"

"url"

"currencies"

"categories"

"locations"

"offers"

"locations"

"tags"

"param"

Full Basic Example

Additional Niches Data

Creating the XML file

Multiple Requests