EPS API reference

Search API

Endpoint

URI: /api/search
Method: POST
Content-Type: application/json

Request Parameters

Mandatory Parameters

Parameter	Type	Description
`query`	`string`	Search keyword.
`clientId`	`string`	Tenant identifier.
`start`	`integer`	Pagination start index (0-based, default: `0`).
`count`	`integer`	Number of results per page.
`version`	`string`	API version (default: `1`).

Optional Parameters

Parameter	Type	Description
`category`	`string`	Category ID.
`locale`	`string`	Language and region format (`de-DE`, `fr-CH`, etc.).
`filters`	`object`	User-applied filters (price range, size, etc.).
`order`	`string`	Sorting order (e.g., `relevance`, `price-asc`).
`personalization`	`string`	Additional segmentation information (e.g., customer type).
`channel`	`string`	Request channel (`web`, `tab`, `mob`, `app`).
`isBot`	`boolean`	Identifies bot traffic (default: `false`).
`sessionId`	`string`	Session identifier for tracking purposes.

Example Request

{
  "query": "red pants",
  "category": "213456",
  "clientId": "tenantde",
  "locale": "de-DE",
  "start": 0,
  "count": 72,
  "version": "1",
  "filters": {
    "filter_search_price": ["fpd_gen", "61-257"],
    "filter_size": ["fb_DKONG_44_8d", "fb_DKONG_46_d6", "fb_DKONG_48_bd"]
  },
  "order": "relevance",
  "personalization": "",
  "channel": "web",
  "isBot": false,
  "sessionId": "1009:w:b8020214-8621-11ef-9524-2f72013a46a7"
}

Response Structure

1. Request Echo

The API echoes the request data under the "request" object.

2. Search Information

Field	Type	Description
`wasArticleNumberSearch`	`boolean`	Indicates if the query was an article number search.
`cacheLevel`	`integer`	Internal cache level indicator.
`hostName`	`string`	Name of the server handling the request.
`filtered`	`boolean`	Indicates if filters were applied.
`sorted`	`boolean`	Indicates if sorting was applied.
`serviceCallId`	`string`	Unique request identifier.
`fromPageCache`	`boolean`	Indicates if the response was served from cache.
`pageCount`	`integer`	Total number of pages.
`currency`	`string`	Currency for displayed prices.

3. Search Results

Field	Type	Description
`count`	`integer`	Total number of results.
`products`	`array`	List of search results.

Product Object

Field	Type	Description
`id`	`string`	Unique product ID.
`brand`	`string`	Product brand.
`shortDescription`	`string`	Product description.
`scores`	`array`	Sorting scores used by the rule engine.
`displayDataAttributes`	`object`	Additional attributes for display.

Product Variations

Field	Type	Description
`colors`	`array`	Available colors for the product.
`colorName`	`string`	Name of the color.
`colorImage`	`string`	URL of the color thumbnail.
`imageUrl`	`string`	URL of the product image.
`price`	`object`	Price details.
`oldPrice`	`object`	Previous price details (if available).
`basePrice`	`object`	Base price (e.g., per liter).
`link`	`string`	URL to the product page.
`sku`	`string`	SKU of the product variation.

Example Product

{
  "id": "AKLBB1720214081",
  "brand": "MAC",
  "shortDescription": "Bootcut Pants ‘CHIARA’, Bootcut-style in a figure-hugging fit",
  "scores": [99.99, 67.32],
  "displayDataAttributes": {
    "name1": "value1",
    "name2": "value2"
  },
  "colors": [
    {
      "colorName": "ruby red",
      "colorImage": "https://images.tenant.com/red.png",
      "imageUrl": "https://images.tenant.com/product.jpg",
      "price": { "isStartPrice": true, "value": 75.99 },
      "oldPrice": { "value": 99.95, "oldPriceType": "UVP" },
      "basePrice": { "value": 1883.33, "unit": "1 Liter" },
      "link": "/p/AKLBB1720214081?sku=4573664038-44",
      "sku": "4573664038-44-1720214081"
    }
  ]
}

4. Filters

Field	Type	Description
`id`	`string`	Filter ID.
`name`	`string`	Display name of the filter.
`isSearchable`	`boolean`	Whether the filter has a search field (e.g., brand filter).
`isSingleSelection`	`boolean`	Whether multiple values can be selected.
`slider`	`object`	Numeric filter (e.g., price range).
`groupedValues`	`array`	List of filter values.

5. Navigation & Breadcrumbs

Field	Type	Description
`searchCategoryNavigation`	`array`	List of categories with results for a search query.
`categoryNavigation`	`array`	Tree structure of categories for a category-based listing.
`breadCrumb`	`array`	Breadcrumb navigation for the category.

6. Sorting Options

Key	Display Name	Default	Selected
`relevance`	Top Sellers	✅ Yes	✅ Yes
`price-asc`	Price: Lowest First	❌ No	❌ No
`price-desc`	Price: Highest First	❌ No	❌ No
`novelty`	New Arrivals	❌ No	❌ No
`ratings`	By Customer Ratings	❌ No	❌ No

Example Sorting Options

{
  "orders": [
    {
      "key": "relevance",
      "displayName": "Top Sellers",
      "default": true,
      "isSelected": true
    },
    {
      "key": "price-asc",
      "displayName": "Price: Lowest First"
    },
    {
      "key": "price-desc",
      "displayName": "Price: Highest First"
    },
    {
      "key": "novelty",
      "displayName": "New Arrivals"
    }
  ]
}

7. Response

Example Full API Response

{
  "request": { ... },
  "information": {
    "wasArticleNumberSearch": false,
    "cacheLevel": 0,
    "hostName": "server-tenant-search",
    "filtered": true,
    "sorted": true,
    "serviceCallId": "search-1733208917642_620353",
    "fromPageCache": true,
    "pageCount": 1,
    "currency": "EUR"
  },
  "result": {
    "count": 57,
    "products": [
      {
        "id": "AKLBB1720214081",
        "brand": "MAC",
        "shortDescription": "Bootcut Pants ‘CHIARA’",
        "scores": [99.99, 67.32],
        "displayDataAttributes": {
          "name1": "value1",
          "name2": "value2"
        },
        "colors": [
          {
            "colorName": "ruby red",
            "colorImage": "https://images.tenant.com/red.png",
            "imageUrl": "https://images.tenant.com/product.jpg",
            "price": { "isStartPrice": true, "value": 75.99 },
            "oldPrice": { "value": 99.95, "oldPriceType": "UVP" },
            "basePrice": { "value": 1883.33, "unit": "1 Liter" },
            "link": "/p/AKLBB1720214081?sku=4573664038-44",
            "sku": "4573664038-44-1720214081"
          }
        ],
        "variations": [
          {
            "size": "44",
            "deliveryStatement": "In stock - delivered in 3 to 5 business days",
            "link": "/p/AKLBB1720214081?sku=4573664038-44"
          },
          {
            "size": "46",
            "deliveryStatement": "Backorder - available in 2 weeks",
            "link": "/p/AKLBB1720214081?sku=4573664038-46"
          }
        ]
      }
    ]
  },
  "filters": [ ... ],
  "navigation": {
    "searchCategoryNavigation": [ ... ],
    "categoryNavigation": [ ... ]
  },
  "breadCrumb": [ ... ],
  "orders": [ ... ]
}

Suggest API

URI

/api/search/suggest

Hostname

STAGING: https://tenant.empirie.dev
PROD: https://www.tenant.de

Request Parameters

Mandatory Parameters

Parameter	Description
`clientId`	e.g., `Tenant`
`query`	Search query (possibly URL encoded)

Optional Parameters

Parameter	Description
`locale`	Default is `"de_DE"`. For French-speaking Swiss clients, `"fr_CH"` must be provided. Alternatively, specifying `TenantChFr` in `clientId` eliminates the need for `locale`.

Request Method

The request is made using GET parameters.

Response Format

The response is returned as a JSON object.

Example Response

{
  "suggestresult":{
    "result":[
      {
        "suggestCategoryResult":{
          "suggests":[
            {
              "count":3684,
              "suggest":"ober<b>hem<\/b>den",
              "fullUri":"/s/oberhemden?ssuggest=sugg",
              "value":"oberhemden",
              "points":4395
            }
          ],
          "category":{
            "displayName":"Suchvorschläge",
            "name":"searchTerm"
          }
        }
      },
      {
        "suggestCategoryResult":{
          "suggests":[
            {
              "suggest":"Unter<b>hem<\/b>den",
              "fullUri":"/waesche-bademode/damenwaesche/unterhemden?ssuggest=kat",
              "value":"Unterhemden",
              "url":"2015",
              "points":2.5
            }
          ],
          "category":{
            "displayName":"Kategorien",
            "name":"category"
          }
        }
      },
      {
        "suggestCategoryResult":{
          "suggests":[
            {
              "image":"b8ac1f1289a8f2d634385950aa53fca5.jpg",
              "price":"ab 39,99 €",
              "imageUrl":"https://bilder.tenant.de/i/empiriecom/b8ac1f1289a8f2d634385950aa53fca5.jpg?$format_suggest$",
              "suggest":"Tenant <b>Hem<\/b>dbluse",
              "fullUri":"/p/tenant-hemdbluse/AKLBB1356156116?ssuggest=prod",
              "value":"TENANT Hemdbluse",
              "url":"AKLBB1356156116",
              "points":0.6366754486883025
            }
          ],
          "category":{
            "displayName":"Artikel",
            "name":"style"
          }
        }
      }
    ],
    "request":{
      "query":"hem",
      "source":"magellan/tenant-productsearch-d87z"
    }
  }
}

Currently, there are three types of suggestions returned:

Categories of Results

Currently, three types of suggestions are returned:

1. Search Terms

Field	Description
`count`	Expected number of results.
`suggest`	Suggested search term with highlight formatting.
`fullUri`	The search URL for the suggestion.
`value`	The actual search term used if selected.
`points`	A ranking score for sorting search terms.

2. Categories

Example Category Suggestion

{
  "suggests": [
    {
      "suggest": "Unter<b>hem<\/b>den",
      "fullUri": "/waesche-bademode/damenwaesche/unterhemden?ssuggest=kat",
      "value": "Unterhemden",
      "url": "2015",
      "points": 2.5
    }
  ]
}

Fields Explanation

Field	Description
`suggest`	Suggested category with highlight formatting.
`fullUri`	URL of the category page.
`url`	ID of the category.
`value`	Actual search term for this category.
`points`	A ranking score for sorting categories.

3. Articles

Product suggestions based on the search term.

{
  "suggests": [
    {
      "image": "b8ac1f1289a8f2d634385950aa53fca5.jpg",
      "price": "ab 39,99 €",
      "imageUrl": "https://bilder.tenant.de/i/empiriecom/b8ac1f1289a8f2d634385950aa53fca5.jpg?$format_suggest$",
      "suggest": "Tenant <b>Hem<\/b>dbluse",
      "fullUri": "/p/tenant-hemdbluse/AKLBB1356156116?ssuggest=prod",
      "value": "Tenant Hemdbluse",
      "url": "AKLBB1356156116",
      "points": 0.6366754486883025
    }
  ]
}

Fields Explanation

Field	Description
`suggest`	Product suggestion with highlight formatting.
`fullUri`	URL of the product detail page.
`imageUrl`	Full URL of the product image.
`image`	Image name (without URL path).
`price`	Price of the product.
`value`	Actual search term for this product.
`url`	SKU identifier of the product.
`points`	A ranking score for sorting articles.

Optional Return Values

For certain product types, additional details may be returned.

Tire Energy Efficiency Labels

For tires, the response includes efficiency labels.

{
  "tireEnergyEfficiencies": [
    {
      "component": "Kraftstoffeffizienz",
      "componentName": "fuelEfficiency",
      "label": "https://bilder.tenant.de/i/empiriecom/EEK_Kraftstoffeffizienzklasse.png",
      "class": "C"
    },
    {
      "component": "Nasshaftung",
      "componentName": "wetGrip",
      "label": "https://bilder.tenant.de/i/empiriecom/EEK_Nasshaftungsklasse.png",
      "class": "A"
    },
    {
      "component": "Rollgeraeusch",
      "componentName": "externalRollingNoise",
      "label": "https://bilder.tenant.de/i/empiriecom/EEK_Rollgeraeusch.png",
      "class": "B | 73 dB"
    }
  ]
}

Fields Explanation

Field	Description
`component`	The energy efficiency category (e.g., Fuel Efficiency, Wet Grip).
`componentName`	Internal name of the efficiency label.
`label`	URL of the efficiency label image.
`class`	Classification (e.g., `"A"`, `"B"`, `"C"`).

Energy efficiency labels for appliances

For electrical appliances, standard Energy Efficiency (EEK) labels are included.

{
  "energyEfficiencyLabelImgUrl": "https://bilder.tenant.de/i/empiriecom/layer/eek/A_bis_G_A_darkgreen.svg",
  "energyEfficiencyLabelImgName": "A_bis_G_A_darkgreen.svg"
}

Fields Explanation

Field	Description
`energyEfficiencyLabelImgUrl`	URL of the EEK label image.
`energyEfficiencyLabelImgName`	Name of the EEK label file.

Base Price Information

For perfume and other volume-based products, a base price is included.

{
  "basePrice": "1 Liter / 2.174,33 €"
}

Fields Explanation

Field	Description
`basePrice`	Price per unit (e.g., per liter).

Additional Notes

Some fields may be redundant in different sections. This is due to differences in web and mobile app requirements.