Summary
To set up FactFinder with your product information, the product data must be provided in a uniform structure. A CSV text file provides an appropriate format. Other file formats, like XML and JSON, are supported as well, please contact us for more details.
Fundamental Concepts
File Format and Encoding
The product data must be exported in CSV text format with fields separated by a designated character (e.g., semicolon
;
)UTF-8 encoding is recommended. If using a different encoding, notify us in advance.
File Compression
To reduce transmission bandwidth, files can be compressed in ZIP format.
Other supported compression formats: GZip, BZip, GZip+TAR.
RAR and other archive formats are not supported for automatic data updates
File Naming and Multi-Shop Support
If FactFinder is used simultaneously in multiple shops or in different languages, a separate file must be created for each channel (shop and/or language).
The channel name must be included in the filename (e.g.,
FFF_export_en.csv
).Multiple files can be included in the same archive or separate archives.
Data Structure Guidelines
Each product (record) must appear in a separate row.
No line breaks within a field (e.g., product descriptions).
Each row must contain the same number of fields.
Field separators: Use tabs or semicolons (
;
), not|
(pipe) or#
(hash).Field delimiters: If separators appear in data, enclose values in quotation marks
""
).
Handling Fields
A separator must be included for empty fields (e.g.,
content1;content2;;content4;
has five fields, in which fields three and five are empty.)The first row must contain field names, structured identically to data rows.
Maximum fields per row: 128 (consider using multi-attribute fields if exceeding this limit).
Character and Size Limitations
Individual field content is not limited in length.
Maximum size of the complete data record: 100,000 characters (removable in special cases via custom FactFinder package).
Data Structure Examples
Without Field Delimiters
ProductID;ProductName;Description;Price
000002101;LG T-6000;HD-Ready LCD-TV with cable tuner;699.00
000002102;Samsung P-4000;HD-Ready LCD-TV with cable tuner;499.00
With Field Delimiters
"ProductID";"ProductName";"Description";"Price"
"000002101";"LG T-6000";"HD-Ready LCD-TV with cable tune";"699.00"
"000002102";"Samsung P-4000";"HD-Ready LCD-TV with cable tune";"499.00"
Field Requirements
Mandatory Field
ProductID or Article Number
Description/rules: Must be the first field in the export file.
Developer info: The field should be named as one of the following:
Artikelnummer
,ArtikelNr
,ArticleNumber
,ProduktNummer
,ProductNumber
.
Recommended Fields
Master Article Number
Description/rules: Needed for variant products (e.g., color, size) to prevent duplicate display when searched
Developer info:
If no variants exist, populate this field with the
ProductID
.The field should be named in the same way as “Article Number”, but prefixed with
Master
: (e.g.MasterArticleNumber
)
Product Name
Description/rules: Short, concise product title
Developer info: The field should be named as one of the following: Name
, Title
, Titel
Developer info: The field should be named as one of the following:
Name
,Title
,Titel
Example: Brand Name; Organic Cotton Sweater
Price
Description/rules:
Numeric value;
Use a dot
.
as the decimal separator;Do not use currency symbols
Developer info:
The field should be named as one of the following:
Price
,Preis
.Use individual fields for separate prices (
Price_EUR; Price_US
orPrice_Dealer; Price_Final_Customer
)
Example: |EUR=32.34|USD=40.32|GBP=23.54|
Optional Fields
Short Description
Description/rules: Concise, keyword-rich text to improve search results.
Developer info: The field should be named as one of the following:
ShortDescription
,KurzBeschreibung
.
Long Description
Description/rules: Detailed marketing text (not recommended for direct search indexing).
Developer info: The field should be named as one of the following:
Description
,Beschreibung
.
Manufacturer
Description/rules: Useful for filtering and ranking by brand.
Developer info: The field should be named as one of the following:
Manufacturer
,Brand
,Hersteller
,Marke
Filter Attributes
Description/rules:
Defines characteristics such as color, size, or genre.
Use multi-attribute fields in the following format:
|Attribute1=Value|Attribute2=Value|
|
must appear between attributes as well as at the beginning and end of the field contentAttributes have multiple values (e.g. colors or sizes), must be stored multiple times in the field (they can be strung together by using the
#
sign or written completely one after the other)To specify a unit separate the attribute name and the unit with double tilde
~~
. There can be only one unit per attribute name.
Developer info:
The field should be named as one of the following:
Attribute
,MultiAttribute
A multi-attribute field is treated as a "text field". For later use in your filter display in the store, you can assign an individual data type such as text, integer or decimal number to each individual attribute. Depending on the data type, different display formats can be selected for the filter.
Examples: |Capacity=50|Speed=7200|
, |Color=Red#Yellow#Blue|
or |Color=Red|Color=Yellow|Color=Blue|
Search Attributes
Description/rules: Additional keywords or technical terms to refine search results.
Developer info: The search attributes should be separated by a single consistent character
Category
Description/rules:
Used for filtering and navigation
Use a slash
/
for category levels.Use a pipe
|
to separate multiple paths.
Developer info: The field should be named as one of the following:
Category
,Kategorie
.
Example: Bicycle/Lighting|Accessories/Bicycle Lamps
A product is assigned to the paths "bicycle/lighting" and "accessories/bicycle lamps"
Sales Rank
Description/rules: A numeric ranking used to prioritize products in search results.
Availability
Description/rules: Indicates whether the product is in stock, influencing its ranking in search results
Margin
Description/rules: Represents the product margin
Developer info: Can be passed in real numerical values or specified in clustered form
Examples: 42%
or 0-5%=a
ISBN, EAN, GTIN
Description/rules: Standardized product identifiers
Developer info:
The field should be named as one of the following:
GTIN
,EAN
,ISBN
Supported formats:
ISSN-8
,ISBN-10
,ISMN-10
,ISSN-13
,ISMN-13
, andISBN-13
Deeplink
Description/rules: A URL that directs the user to the product detail page
Developer info: The field should be named as one of the following:
Deeplink
,ProductURL
,ProduktURL
Examples: www.exampleshop.de/picture/article/123
ImageURL
Description/rules:
The link to the product image
Preview image for the search result, not the high-resolution image that is displayed on the product detail page
In case there is no image available at the moment, a dummy URL with the same name or the link to an image that shows "no image for this item yet" should be used here
Developer info:
Do not leave this field blank
The field should be named as one of the following:
ImageURL
,ImgURL
,BildURL
,BildLink
,PictureURL
,PicURL
Examples: www.exampleshop.de/picture/brand/bild.jpg
Accessory
Description/rules: An indicator for accessory products (typically a True/False or 0/1 value)
Developer info: The field should be named as one of the following:
Accessory
,Zubehor
Promotion/Sale
Description/rules: Indicates whether the product is part of a promotion or sale
Developer info: The field should be named as one of the following:
Sale
,Aktion
Brand URL
Description/rules: Directs users to a brand store page
Developer info: The field should be named as
BrandURL
Brand Image
Description/rules: Displayed in brand filters and search suggestions
Developer info: The field should be named as one of the following:
BrandImage
Examples: www.exampleshop.de/picture/brand/bild.jpg
Stock
Description/rules: Used to rank products lower if stock is limited
Developer info: The field should be named as one of the following:
Quantity
,StockQuantity
,Stock
,StockStatus
Rating
Description/rules:
Display user ratings (e.g., 1-5 stars)
Use this data field only in conjunction with RatingCount
Developer info: The field should be named as one of the following:
RatingScore
,Rating
Rating Count
Description/rules: Integer value indicating the number of ratings (see Rating).
Developer info: The field should be named as
RatingCount
Saison/ Event
Description/rules: Devalue items that are not currently in season or that do not belong to a particular event so that they are displayed far down in the search
Developer info: The field should be named as one of the following:
Saison
,Event
Return rate
Description/rules: Used to devalue the items with a high return rate
Developer info: The field should be named as one of the following:
ReturnData
,RetourCount
,Retour