Managing item catalogs
There are two ways to import an item feed to Synerise:
- Create a catalog, prepare an XML file, and set the automatic import of the feed to a catalog (the imported element is later referred to as an item catalog).
- Import Google Merchant feed.
Before you submit your Google Merchant feed to Synerise, you can use external XML schema validator tools to make sure that the file does not contain errors
Enrichment of item feed
You can use a Metadata catalog to train the models for Section and Attribute recommendation types.
Metadata catalog is a standard catalog that enriches your item feed with additional data, such as brand logos, images, links to the products, descriptions of items. The catalog must include an itemId
column and the values in that column must correspond with the item’s identifier in the item feed you want to enrich.
Requirements for item catalogs
Limitations
-
The name of the item catalog must be an alphanumeric string without any special characters nor whitespaces, following this regex pattern:
[a-zA-Z0-9]*
. -
Item attribute names must be an alphanumeric string without whitespaces, following this regex pattern
^[_a-zA-Z0-9]+[\-_a-zA-Z0-9]*$
. -
Item attribute string values must be alphanumeric. They can’t contain following characters:
- " - quotation mark
- ’ - inverted comma
- . - dot
- , - comma
- space or any whitespace character
Therefore,
complex.name
is forbidden and you should rather use camelCase:complexName
(preferred) or underscore format:complex_name
. -
Synerise accepts any properly formatted JSON which contains
itemId
and with proper key names. Later, item attributes are being returned by the API without changing or parsing values, which also applies to HTML/XML tags as values. You should handle the raw data retrieved from API in a way that will avoid the risk of XSS attack. -
Attribute names are case sensitive.
Format
The format of an item is a JSON. Each object represents an item with its attributes, for instance:
{
"itemId": "Xa34ad3d",
"intAttribute": 5,
"floatAttribute": 2.5124,
"stringAttribute": "asfdqw",
"timestampAttribute": 1356846157,
"booleanAttribute": true,
"arrayOfStringsAttribute": ["A", "B", "C"],
"nestedObject": {
"a": 1,
"b": "value"
},
"nestedObjectsArray": [
{
"x": "y"
}
]
}
Accepted values of attributes
- string:
"foo"
- integer:
12
- float:
12.34
- boolean:
true/false
- nested objects:
{ "sub": { "a1": "v1", "a2": "v2" } }
- array (of strings, integers, floats, booleans, nested objects, arrays):
["foo", "bar"]
- timestamp: should be formatted as Unix timestamp, for example,
1356846157
- date: string dates are not interpreted/parsed - you should add a field which is formatted as a timestamp
Unique identifier
Each item (each JSON document) must contain an itemId
field which is a reserved key used as a unique item identifier. Its value type must be a string and it’s case sensitive. As itemId
is an item identifier it is specially treated:
- It is always returned by search API
- It is always returned by recommendations API
- Events (especially
page.visit
andtransaction.charge
) should contain matchingitemID
Special field
category
is a special attribute which is used to define the hierarchy of categories which an item belongs to. It must have the following format:
X > Y > Z
Where X
is a top level category and Z
is the lowest category level. For example, Electronics > Phone and Smartphones > Smartphones
. Category levels should be joined with >
(literally space>space). When you have an item which belongs to more than one category, you can pass the additionalCategories
field in the following format:
"additionalCategories": ["A > B > C", "D > E > F"]
Both category
and additionalCategories
are used when you filter by categories.
Requirements for Google Merchant feed
-
Build your feed according to Google Merchant Center Help recommendations. Synerise supports the tags described there.
-
In the XML Prologue, define two namespaces as follows:
"xmlns:g="http://base.google.com/ns/1.0" xmlns:c="http://base.google.com/cns/1.0"
-
All tags that are defined by Google Merchant Center must be preceded with a
g:
prefix. The only tags that do not use the prefix are:<title>
,<name>
and<link>
, and your custom tags that are not defined by Google Merchant Center Help. -
The list of the obligatory tags (written in angle brackets):
- g:id
- title
- g:availability
- g:product_type
- g:price
- link
- g:image_link
page.view
events, transactional events and in the feed, otherwise the recommendation frame will not display them at all or the system will not register the purchase and/or it won’t be counted towards revenue.c:
prefix.availability
will be automatically changed to false
for the items which have been removed from latest feed version.Feeds which are in Google Merchant XML format are automatically transformed into items format according to following rules:
Google Merchant | Item attribute | remarks |
---|---|---|
additional_image_links | additionalImageLinks | Array of strings |
additional_product_types | additionalCategories | Array of strings |
adult | adult | String |
availability: String | availability: Boolean | true ~ 'in stock', 'preorder'; false ~ 'out of stock' |
brand | brand | String |
channel | channel | String |
color | color | If an item has more than one color, they must be separated with `/`. The colors are converted into the `colors` array (see next row). |
- | colors | Array of strings, contains parsed values of "color", `XML.color.split('/')` |
condition | condition | String |
content_language | contentLanguage | String |
custom_attributes | attributes.attributeName | All elements from custom_attributes column are mapped into attributes object and placed on a top level i.e.: {"(fason,text,,Chusta)","(model,text,,Tortona)","(additionalPrice,text,,\"43.99 PLN\")"} All elements from custom_attributes column are mapped into: "attributes": { "fason": "Scarf", "model": "Tortona", "additionalPrice": { "value": 43.99, "currency": "PLN” } } |
custom_groups | attributes.groupName | All elements from custom_groups column are mapped into attributes object and placed as objects with the same name on a top level. All elements from a particular group are then moved into newly created objects in a same fashion as custom_attributes i.e.: custom_groups: {"(\"{\"\"(process_type,text,,SALE_OF_GOODS)\"\",\"\"(market,text,,b2c)\"\"}\",synerise_filtering)","(\"{\"\"(Rodzaj,text,,book)\"\"}\",Rodzaj_Etui)"} will be mapped into: "attributes": { "synerise_filtering": { "process_type": "SALE_OF_GOODS", "market": "b2c" }, "Rodzaj_Etui": { "Rodzaj":"book" } } |
custom_label0 custom_label1 custom_label2 custom_label3 custom_label4 |
"customLabel": { "1": "value1", "2": "value2" } |
|
description | description | String |
gender | gender | String |
google_product_category | googleProductCategory | String - joined with ' > ' so i.e. 'X > Y > Z' |
gtin | gtin | String |
image_link | imageLink | String |
item_group_id | itemGroupId | String |
kind | kind | String |
link | link | String |
offer_id | itemId | |
price_currency | price.currency | 'price': {'currency': 'PLN', 'value': 849.00} |
price_value | price.value | 'price': {'currency': 'PLN', 'value': 849.00} |
- | effectivePrice | Number, if (XML.sale_price isDefined) XML.sale_price else XML.price |
- | discountAmount | Number, XML.price - calculated.effectivePrice |
- | discount | (XML.price - effectivePrice) / price if price <> 0 else 0 |
product_type | category | |
sale_price_currency | salePrice.currency | 'salePrice': {'currency': 'PLN', 'value': 849.00} |
sale_price_value | salePrice.value | 'salePrice': {'currency': 'PLN', 'value': 849.00} |
sizes | sizes | Array of strings |
target_country | targetCountry | String |
title | title | String |