Loop54 needs to have the entire product catalogue, including all relevant metadata, indexed. Submitting your product data to Loop54 in the right format is important for creating a successful and relevant search and category navigation experience for your customers.

Loop54 uses the product metadata to:

• make products searchable
• build relationships between products
• incorporate business logic into the search and navigation experience
• enable filtering logic
• build faceted filters

* Optional: many of our customers use Loop54 as their data source for rendering all information displayed on the search results page, product pages, etc. For this reason, they include more information in the product feed than Loop54 requires.

Here are our specifications regarding what data we need. Use this specification to structure your product information for the Loop54 search engine.

Depending on the quality of your existing product feed and the complexity of your catalogue, the effort involved with setting up your product feed can vary immensely.

The exact requirements differ depending on the types of products that you sell, however, there are certain minimum requirements we have for guaranteeing a good search and category navigation experience. We also have some optional, yet strongly suggested, recommendations you can adopt to avoid common mistakes.

The granularity of information and proper structure in your product feed allows you to use the data for different purposes. This can give you critical advantages, such as:

• Data can be used for facetting and filtering
• You can deliver a better, more natural navigation experience
• It will be easier to maintain the data over the long term
• Loop54 can build business logic easily based on any data (e.g. boost/bury rules)
• Loop54's algorithm will not be confused by conflicting data

Below is an example of a typical JSON product feed that contains all required product attributes (Name/Title, ID, Category Path, Brand, ImageURL)

Here is an example of a full product feed in JSON

Here is an example of a product feed in XML

Here is an example of a product feed in CSV 

Definition of terms you will see throughout this document:

• Product: Word that describes the actual product that your potential customers would be searching for on your website.
• Attribute: Anything that stores data on the product, not just distinct data. Often characteristics of a product which make it distinct from other products. Attributes include size, color, functionality, components and features that affect the product's appeal or acceptance in the market.
• Variant: Word that describes a product that comes in different variations. For example, a shirt that comes in different sizes has size variants.
• Entity: Often called Objects. Entities are what the engine uses to store products, categories, brands, etc. Loop54 will save all structural attributes as entities.

Product attributes

The product information you submit using these attributes is the foundation we use to create your search engine. Please make sure everything you submit is of the quality you would show to a customer.

If you don't have a relevant value for any of the attributes listed below, we prefer you leave the attribute container empty (i.e. do not provide a value like: N/A, Generic, No brand, or Does not exist).

The sections below describe what product attributes are required, recommended and optional.

Required product attributes

To create a reliable abstraction of the topology of your product catalogue (i.e. a neural network), Loop54 requires that certain product attributes be available in the product feed. Loop54 uses this information to build relationships between products and understand how statistically similar/dissimilar products are to one another based on their location in the neural network.

• Product identifier: Your product’s unique identifier. This is the number you use in your store to identify a specific item. It’s important that the number is unique in your product feed. You can use your SKU numbers or the ID generated by your store’s e-commerce platform. If you’re setting up feeds for the same country in multiple languages, it’s ok to use the same product ID for the same item in a different language.
• Use a unique value for each product. Use the product's SKU where possible
• Keep the ID the same when updating your data
• Use only valid UTF-8 characters. Avoid invalid characters like control, function, or private area characters
• Use the same ID for the same product - across countries or languages
• Only one field will be used as the ID, however we can index any amount of ID fields, so it is fine, and even encouraged to supply several. If there is an Article number, SKU, EAN and product Id for example, we would take all of them, but only choose one to use as the ID of the product.

• Title: Your product’s name. Accurately describe your product and match the title from your landing page.
• Don’t include promotional text like "free shipping," “Limited offer”, all capital letters, or gimmicky foreign characters (emojis).
• For variants, include a distinguishing feature such as color or size. If possible, avoid HTML or other formatting tokens - the engine will strip them before indexing.

• Brand: Your product’s brand name. Provide the name of the company that created the product (i.e. manufacturer or supplier). Use the brand name of the product generally recognized by consumers.

• Image link: The URL of an image for your product. This is the main product image. If you have multiple images, use the additional_image_link attribute. To increase site load speed, please have small file sizes, anything from 200x200 to 600x600 would reasonable.

• Category: Product categories that you define for your product. This attribute tells Loop54 which category your product belongs to. A product category is not a physical attribute, like color or dimension; nor should it specify that the product is new or on sale (e.g. “Gifts for him” or “Black Friday Sales” are not a categories). 
  
  Include the full category path, don’t just settle for the highest level category. Try to be as specific as possible and make sure to include the full path - starting with the more general and progressing towards the specific, like a funnel. For example: if you sell a jersey for cycling, don’t settle for the general category: Activewear. Be as specific as possible, like: Apparel and Accessories > Clothing > Activewear > Bicycle Activewear > Bicycle Jerseys.

• The engine can support a full path as an array and a list of lists - where outer list is all categories the product belongs to and inner list are the hierarchies for each category.
• If the product falls under multiple categories paths and one path is primary, give it a name like: primary_category_path

Recommended product attributes

We use these attributes to build additional logic, faceted filters and to improve the relevance of search results and/or category listings. The attributes listed below are highly recommended but not required for the proper functioning of your Loop54 engine.

• Description: Your product’s description. This is where you give all the product details a customer cares about: features, dimensions, use cases, etc. The description helps to tell Loop54 what other keywords your product would be relevant to appear for. As with the title, avoid promotional text.

• Clearly explain what the product does or its intended use. Offer added value or benefits. Include all relevant information.
• Match the description found on the product landing page.
• Don’t include promotional text like "free shipping," all capital letters, or gimmicky foreign characters like emojis.
• Include only information about the product. Don’t include links to your store, sales information, details about competitors, other products, accessories or standard text that isn’t exclusively a description of the product.

• Price: Your product’s price (excluding currency). Loop54 uses price for distinct and and range faceting, therefore please don’t include currency in the price value. If you intend to use the same feed (and engine) for several countries and have different prices for different currencies, please use multiple currency attributes instead. For example: PriceEUR:5.99, PriceUSD: 7.99
• Don’t include the currency in the price value (e.g. do not use Price: GBP23.70)

• Variant group id (where applicable): Connection ID between parent SKU and child variants. This attribute groups together different product variants, like items in different colors or sizes. Used to associate articles and products and to make all metadata searchable even if only one variant is displayed in the search response.
• Use a unique value for each group of variants
• Use the parent SKU as the group ID where possible
• Keep the value the same when updating your product data
• Use only valid UTF-8 characters
• Use a variant group ID for a set of products that differ by one or more of these attributes:
• color
• size
• pattern
• material
• age group
• gender
• etc.

• Include the same attributes for each product in the variant group. For example, if a product varies by size and color, submit size and color for every product that shares the same value for variant_group_id

• Color: Your product’s color(s).
• Don’t use a number such as 0 2 4 6 8
• Don’t use characters that aren’t alphanumeric such as #fff000
• Don’t use only one letter such as R
• Don’t reference the product or image such as “see image”
• Don't combine several color names into one word. Instead, either add multiple values in an array or separate them with a /.  RedPinkBlue ---> Red/Pink/Blue.
• Don’t use a value that isn’t a color such as multicolor, various, variety, men's, women's, or N/A
• For variants: On each variant, put the same value for variant_group_id, but a different value for color. If there are multiple variants with similar but differently named color types (e.g. canary, yellow and neon yellow) and color will be used for facetting, group colors into a new attribute called color_group (e.g. color_group: “Yellow”).

• Availability: Availability status of an item (as a string or boolean). It is useful when Loop54 handles paging. We can use it to bury out-of-stock products in results and category listings. Example: Preorder, In Stock, Out of Stock.

• Campaigns: Products on sale or products being promoted for any reason. We can use it to give products on campaign higher weight/prominence in search results and/or category listings.

• New Until: When a new product is added to your catalogue, this is the date that the product is no longer considered new. Should you wish to boost new products, we use this attribute to give new products higher weight/prominence in search results and/or category listings until the date provided. Please use ISO 8601 format.

• Product series name (or similar): Your product’s Global Trade Item Number (GTIN). Gtin or Global Trade Item Numbers are unique product identifiers. Often called barcodes. Depending on where you are located or source your products from, you’ll have a different set of numbers: UPC: 12 digit number mainly used in North-America; EAN/UCC: 8,13 or 14 digit number mainly used outside North America; JAN: 8 or 13 digit number used in Japan; ISBN: unique identifier for books. If you have multiple options, for example a UPC and a EAN number, you can use either one of them. 

• Hidden Keywords: the words that you can supply to help boost discoverability in search results. Use terms that would help someone find a product if they hadn’t searched for what you visibly provided on the search result page.

• Attributes that say something about the relationship between specific products: since Loop54 uses all product metadata to build relationships between products, a product attribute like “Gear Type” for Bicycles could be used to group all bicycles with the same gear type. Any attribute that describes the product and would be used by shoppers to narrow or expand their search should be included.

• Attributes that describe a unique product feature: any other attribute shoppers might use to compare products or use to narrow results through faceting. For example: gender, age group or size. (e.g. Wheel Size for bicycles)

Other useful attributes

• Link: Your product’s landing page. Provide a direct link to the product page (not your homepage). If you have a specific page for mobile traffic, supply that link via the mobile_link attribute.
• Use your verified domain name
• Start with http or https
• Use an in-domain tracking URL if needed. Don't use too many redirects, which can increase latency 

Summary

Below is a table summary of all required, recommended and optional product attributes often found in a product feed. In this summary, we also provide examples for each attribute.

Synchronization

We could theoretically synchronize against the product feed every 5-10 minutes (depending on the size of the feed). But that depends mainly on how resource intensive it is for the platform to generate the feed.

Hybrid solutions in synchronization

There are also hybrid solutions available where delta-information/changes is pushed to our API continuously in real time, but it should always be complemented with a complete feed that Loop54 can synchronize with at least once a day.

Decisions to be made

Synchronization interval

How often should Loop54 sync against the product feed? This is often dependent on the logic that Loop54 should incorporate. E.g. if Loop54 shall filter out of stock items, the synchronization intervals needs to be short.

Value-adding attributes

Which attributes should Loop54 incorporate business logic from? The usual ones are campaigns and news.

Filtering

Should Loop54 filter out results (e.g. out of stock) before the result is sent back?

Faceting

All attributes that are needed for faceting need to be in the feed.

Parent or Children, or both?

Many product catalogues contains a product hierarchy where one product contains several variants or articles (On Magento, these are often called configurable products). Loop54 can be configured to send back either type, depending on how the users interact with the products. It is also possible to return variants/articles on a narrow search (e.g. a model number) and products on broader search phrases (e.g. product category). So depending on the situation it needs to be decided which is most suitable in terms of use case, available meta data and platform capabilities.