To ensure the search experience, you need to index your product catalogue in the search engine. The first step for transmitting your product catalogue information to Empathy Platform is creating a feed, that's a structured inventory of your product catalogue.

For the Index microservice to process your data, it must be able to recognize the feed's format and content. For uploading feeds, the Index microservice requires files in JSON, XML, or CSV format. Compressed collections are not supported.

Tip

When you create the feed file, you translate your catalogue data into JSON format. To do so, you first need to gather your data. Regardless of your source data format, you can run a script to fetch your data, map it into JSON, and use the resulting file as a base to work on your feed file.

The file you need to create is a flat collection of objects, where each JSON object contains all the fields necessary to describe a product. Accordingly, to map products existing in more variants, for example a t-shirt existing in more sizes and prices, you need to create a separate object per variant, each object referring to the product and containing a different set of properties.

To get started with your feed, follow these guidelines:

• Planning your search and discovery experience
• Building the architecture of your product catalogue
• Describing your products
• Providing images for your products
• Understanding the feed fields
• Uploading your first feed
• Updating your feed

Planning your search and discovery experience

Before you start developing your feed file, have a look at the catalogue's data model. The data model maps the fields supported by the feed file and how they serve Empathy Platform's tools and features. Based on the search experience you want to provide to your shoppers, use the data model as a guideline to define your feed file's content.

interact

Explore the Empathy Platform features to make the most of your search and discovery experience!

In case your commerce store is available in more than one language, you upload as many product catalogues as supported languages. As a result, you need to index one feed file per language. The feed file supports over 40 languages.

note

For further inquiries about the supported languages, contact your Key Account Manager.

Building the architecture of your product catalogue

The first step to creating a feed file is defining the architecture of your product catalogue data. The feed file supports several fields that help you organize your products in categories, and consequently structure your categories into hierarchies.

By developing your categories you not only structure your catalogue, but also define the way shoppers navigate it during the search and discovery experience. Note that categories are used for search and navigation as facets, or rather criteria suggested by the search engine for the shoppers to further filter the query results. Read the tips about object labeling to define your product categories.

Describing your products

Once the target feed architecture is ready, you can translate your products into JSON objects. Each product can be unique or can exist in more variants, for example a t-shirt existing in more sizes and prices. In the feed file, each product variant corresponds to a separate object referring to the product and containing a different set of properties. To determine the fields included in your objects, refer to both the data model and field list. Custom fields are supported.

By defining parent-child relationships between the objects, you lay the groundwork for using search features such as Query Suggestions, Next Queries, Recommendations, etc. When you define the fields' properties and values, you also design which product information to show to shoppers and how to display it during the search and discovery experience. To define your JSON objects, read the tips about object labeling.

Providing images for your products

Every good product catalogue not only provides the product's description, but also a nice image representing the product. In the feed file, you can add images for your products to offer a joyful search and discovery experience to your shoppers. The Images field only requires URLs, so you need to ensure the chosen images are available for browsing at all times. For your images to perform right in your commerce store:

• Try to use absolute URLs.
• Choose valid web formats, preferably JPG or WEBP.
• Optimize the image size as compressed for web.

Understanding the feed fields

For the feed file to be valid for indexing, its structure needs to follow a specific schema. The feed file supports then both required and optional JSON fields, where:

• The required fields define product categories and identify products.
• The optional fields provide business information about the products.

interact

Check the complete list of supported fields to start translating your product catalogue into JSON.

Feed file example: Architecture of a feed file

Here's an example of a valid architecture of a feed file. The hierarchical organization of JSON objects is highly customizable as it varies based on your commerce store needs.

{
  "products": [
    {
      "id": "unique_string_12345",
      "externalId": "any external reference",
      "name": "name of the product",
      "description": "description of the product",
      "shortDescription": "short description of the product",
      "categories": [
         {
           "id": "id12345",
           "name": "Root Category Name",
           "children": [
             {
               "id": "id12345",
               "name": "Parent Name"
             }
           ]
         }
      ],
      "type": "product",
      "images": [
         "http://your.domain/image-12345.jpeg"
      ],
      "url": "http://your.domain/item",
      "price": {
         "currency": "EUR",
         "current": {
           "value": 11
         },
         "previous": {
           "value": 5.54
         },
         "future": {
           "value": 12.0
         }
      },
      "stock": 8,
      "colours": [
         {
           "name": "Light Blue",
           "id": "121499"
         }
      ],
      "sizes": [
         "EU 44"
      ],
      "dimensions": {
         "width": "125cm",
         "heigth": "34cm",
         "depth": "25cm"
      },
      "brand": "Product Brand Name",
      "collection": "summer-2022",
      "tags": [
         {
           "name": "ring",
           "icon": "http://your.domain/ring.png"
         }
      ],
      "stores": [
         "Store-0",
         "Store-1"
      ]
    }
  ]
}

Uploading your first feed

During your onboarding in Empathy Platform, you need to create a feed file following this page's guidelines. When your feed file is ready, you can start the indexing process via an API request to the Index API endpoint.

note

When you're preparing a multilingual project, you need to index as many feed files as supported languages. To do so, send only one feed file per request.

When you request the Empathy Platform Index Builder to index your feed, the indexing process only starts if the feed file is valid, or rather, if it meets the Index microservice's requirements about format and codification. Feed validation assesses the file format (i.e. JSON) and its internal codification (e.g. non-empty fields are full, the value syntax is correct based on the field's data type), or both based on the field:

• For mandatory fields, the Feed Validator tests both the format and the codification.
• For optional fields, the Feed Validator tests the format only.

interact

For technical specifications about Index API endpoint for starting the indexing process, see Index API.

Validation ignores custom fields and properties. When the validation is performed within the indexing process, the feed is automatically indexed after validation. In case of an invalid feed, the indexing process is interrupted. In this case, validation results and an error log are always returned to help you debug your feed file.

Updating your feed

Each time you need to modify your product catalogue, you need to index a feed file. This also applies to updating only selected values of your product catalogue that are likely to change frequently, even several times a day, for example, the storage stocking of products.

To update selected values of an already uploaded catalogue, you can schedule frequent API requests with updates, or rather, set the automatic indexing of delta feeds. Delta feeds only include indexed fields whose values need modification. Note that to add or delete fields, you need to index full feeds.

warning

In case of inconsistency between the set of fields already indexed and the one to be indexed, the former is overwritten by the latter.