integration_documentation:response_xml

integration_documentation:response_xml

The response format can be set by Findologic only. If the XML response format is used, please refer to the following documentation.

Our library helps requesting the Findologic API and also getting the data from the response and mapping it to corresponding objects. Read more at https://github.com/findologic/findologic-api
You can also find a detailed API specification of the XML 2.1 response on our Findologic API Spec page.

Basic structure of the XML tree


See our xsd scheme for further information.


The XML elements in detail

<servers/>

The servers with which the query was answered. The element need not always be included.

    <servers>
      <frontend>frontend3.findologic.com</frontend>
      <backend>backend17.findologic.com</backend>
    </servers>

<frontend/>

The frontend server with which the query was processed.


<backend/>

The backend server with which the query was processed.


<query/>

Describes the query that is currently being carried out.

    <query>
      <limit first="0" count="10"/>
      <queryString>Test</queryString>
    </query>


Information for Smart Did-You-Mean

Smart Did-You-Mean users receive additional information for better error-tolerant search. A number of constellations listed below are possible, and each variety requires a certain kind of output in the search result visualization.


Did-You-Mean

A possible alternative to the user’s original query. Results in this case are based on the original query.

Response format:


  <queryString>original query</queryString>
  <didYouMeanQuery>alternative query</didYouMeanQuery>


Suggested visualization:

Did you mean “alternative query”?

Note that when sending the did-you-mean query in the search request, an URL parameter forceOriginalQuery=1 URL parameter must be provided. This parameter disables Smart Did-You-Mean functionality.


Improved query

The original query has results, but there is an alternative query that is more relevant to the user.

Response format:


  <queryString type="improved">alternative query</queryString>
  <originalQuery allow-override="1">original query</originalQuery>


Suggested visualization:

Showing results for “alternative query”. Search instead for “original query”.

Note that allow-override=“1” indicates that the original query must be executed with the URL parameter forceOriginalQuery=1. This parameter disables Smart Did-You-Mean functionality.


Corrected query

The original query did not yield any results, so the best alternative with results is shown instead.


  <queryString type="corrected">alternative query</queryString>
  <originalQuery>original query</originalQuery>


Suggested visualization:

No results for “original query”. Showing results for “alternative query” instead.


Forced query

In case the request URL parameter forceOriginalQuery=1 was submitted, Smart Did-You-Mean functionality is disabled, and the search results are based on the user’s query. The response reflects this fact:


  <queryString type="forced">a query</queryString>


No visualization is required for this scenario.


<limit/>

Indicates which area of the results has been requested.

Attributes:

  • first
    • Indicates the first element to be displayed 1).
  • count
    • Indicates the total number of elements to be displayed.

<results/>

Provides information on the query output.

<results>
    <count>2</count>
  </results>

<count/>

Indicates the number of results for the current query.


<products/>

Indicates the query output of the products found. Depending on the values of <first/>- and <count/>-this may include only a partial range of the entire query output.

<products>
    <product id="666" relevance="15.265">
    <product id="123" relevance="14.361">
  </products>

<product/>

<product id="123" relevance="14.361">
      <properties>
        ...
      </properties>
    </product>

Attributes:

  • id
    • Indicates the ID of the respective product transmitted in the export.
  • relevance
    • Indicates the relevance of the respective product.

<properties/>

<properties>
        <property name="propertyName">propertyValue2</property>
      </properties>


<property/>

Shows the contents of the properties that have been imported.

Attributes:

  • name
    • Shows the name of the exported column.

<filters/>

Shows further filter options from the search service that are sensible due to the results found. The filters in the <filter/>-elements are grouped according to categories.

  <filters>
    <main>
        <filter>
        ...
        </filter>
    </main>
    <other>
        <filter>
        ...
        </filter>
    </other>
  </filters>

<main/>

Indicates that the respective filter is configurated as main filter in the customer account.


<other/>

Indicates that the respective filter is configuratedas other filter in the customer account.


<filter/>

Indicates a filter category and contains the various values for this filter category in the <items/> elements.

<filter>
      <name>cat</name>
      <display>Kategorie</display>
      <select>multiselect</select>
      <selectedItems>1</selectedItems>
      <type>label</type>
      <items>
        ...
      </items>
    </filter>

<name/>

The key for this attribute to be submitted to Findologic.


<display/>

If specified, the name of this filter to be displayed; otherwise the value from <name/> is output.


<select/>

Indicates the output mode. Possible values:

  • single
    • Only one value or pair of values can be given for the filter.
    • Example: Price filter
  • multiselect
    • Several values can be given for one filter.
    • These are or-linked.
    • Example: Vendor filter
  • multiple
    • Several values can be given for one filter.
    • These are and-linked.
    • Example: Color filter

<selectedItems/>

Indicates how many items (values) have been selected. Is only output if select = multiselect.


<type/>

Indicates the display format of the filter:

Possible values:

  • label
    • The filter values are to be displayed in text form.
  • color
    • The filter is displayed as a “Color-Picker”.
  • select
    • The filter is displayed as a “Dropdown”.
  • image
    • The filter values are to be displayed in image form. Only available for vendor filter.
  • range-slider
    • The filter values are to be displayed with a range slider.

<attributes/>

Provides more exact information on the range slider. Is only output if type = range-slider.

<attributes>
    <selectedRange>
      <min>24</min>
      <max>27</max>
    </selectedRange>
    <totalRange>
      <min>21</min>
      <max>29</max>
    </totalRange>
    <stepSize>1</stepSize>
    <unit>Zoll</unit>
  </attributes>

—-

<selectedRange>

Indicates the range selected by the user. If the range has not been limited yet, the values of selectedRange and totalRange are the same.

  • <min/>
    • Selected minimum value
  • <max/>
    • Selected maximum value

<totalRange>

Indicates the total possible range.

  • <min/>
    • Minimum possible value of the slider
  • <max/>
    • Maximum possible value of the slider

<stepSize>

Indicates the size of the steps between selectable values. The step size can also be smaller than 1.


<unit>

Indicates the unit of the values.


<items/>

<items>
        <item>
           ...
        </item>
        <item>
           ...
        </item>
      </items>

Contains the individual values for this filter category.


<item/>

Contains further information on this specific filter.

<item selected="1">
      <name>Subgroup</name>
      <display>Subgroup</display>
      <weight>0.863121</weight>
      <frequency>5</frequency>
      <color>#000000</color>
      <image>http://www.example.com/images/Subgroup.jpg</image>
      <items>
        <item>
          <name>Subgroup</name>
          <weight>0.985228</weight>
          <frequency>4</frequency>
            <items>
               ...
            </items>
       </items>
    </item>
  • selected
    • Indicates that this filter is selected.

<item/>-elements can contain further <items/> in turn. For example, this is the case with hierarchical categories if one category contains further subcategories.


<name/>

The value for this attribute to be submitted to Findologic.


<display/>

If specified, the name of this filter value to be displayed; otherwise the value from <name/> is output.


<weight/>

The relevance of the filter2), in the case of an XML response for Findologic Navigation, this value has no significance and should therefore be ignored in the filter output.


<frequency/>

The number of results for this filter3) the element is optional and is not output in certain cases.

  • <type> absolute
    • Indicates that the frequency shown is the total number of results available after clicking the filter value.
  • <type> relative
    • Indicates that the frequency shown is the number of results that will be added after clicking the filter value. (f.e. +3)

<select/>

Indicates whether several values from one filter category can be selected simultaneously (multiple)or whether only one value of this filter may be active (single).


<image/>

Depending on the configuration, one image URL per filter element can be returned, which can be displayed in the results instead of the filter name. The indication of an image URL does not necessarily mean that the image also exists! This element can also be used with colour filters.


<color/>

If it is a colour filter and if an HTML colour value is stored for the corresponding colour, this value is indicated in this element (preceded by a hash). Accordingly, this value is optional.


<parameters/>

With certain filters, there is the optional of indicated the values to be submitted to the search service; please see also Request parameters.


<landingPage/>

Indicates that a landing page has been found for the search term (e.g. for General Terms and Conditions or the imprint page).

<landingPage link="http://www.example.com/legal_information" />

If a landing page has been found, the results and products elements can be empty.

Attribute:

  • link
    • Contains the URL to which one is to be directly redirected.

<promotion/>

Indicates that a promotion has been found for the search term (e.g. for special seasonal campaigns or special sales).

<promotion image="http://www.example.com/images/special-offer.jpg" link="http://www.example.com/special-offer" />

The module should then provide an opportunity to embed the linked image in the search template.
By default, this banner is output over the search results.

Attribute:

  • image
    • Contains the URL for the image that is to be output as the banner.
  • link
    • Contains the URL with which the banner is to be linked.

Example

The following example is fictional and contains all possible elements at the same time.

<searchResult>
    <servers>
      <frontend>frontend9.findologic.com</frontend>
      <backend>backend12.findologic.com</backend>
    </servers>
    <query>
      <limit first="0" count="10"/>
      <queryString>Test</queryString>
    </query>
    <landingPage link="http://www.example.com/imprint" />
    <promotion image="http://www.example.com/special-offer.jpg" link="http://www.example.com/special-offer" />
    <results>
      <count>2</count>
    </results>
    <products>
      <product id="666" relevance="15.311"/>
        <properties>
          <property name="propertyName">propertyValue1</property>
        </properties>
      <product id="123" relevance="14.363"/>
        <properties>
          <property name="propertyName">propertyValue2</property>
        </properties>
    </products>
    <filters>
     <main>
      <filter>
        <name>cat</name>
        <display>Kategorie</display>
        <select>multiple</select>
        <items>
          <item>
            <name>Untergruppe</name>
            <display>Untergruppe</display>
            <weight>0.863121</weight>
            <frequency>5</frequency>
            <image>http://www.example.com/images/Untergruppe.jpg</image>
            <items>
              <item>
                <name>Unteruntergruppe</name>
                <weight>0.985228</weight>
                <frequency type="relative">4</frequency>
                  <items>
                     ...
      </filter>
      <filter>
        <name>vendor</name>
        <display>Hersteller</display>
        <select>multiple</select>
        <items>
          <item>
            <name>Firma Müller</name>
            <weight>0.863121</weight>
            <frequency>2</frequency>
            <image>http://www.example.com/vendor/firma_muller.jpg</image>
          </item>
      </filter>
     </main>
     <other>
      <filter>
        <select>single</select>
        <name>price</name>
        <display>Preis</display>
        <items>
          <item>
            <name>1.23 - 6.66</name>
            <weight>0.863121</weight>
            <frequency>2</frequency>
            <parameters>
              <min>1.23</min>
              <max>6.66</min>
            </parameters>
          </item>
          <item>
            <name>6.66 - 8</name>
            <weight>0.591673</weight>
            <frequency>1</frequency>
            <parameters>
              <min>6.66</min>
              <max>8</min>
            </parameters>
          </item>
        </items>
      </filter>
     </other>
    </filters>
  </searchResult>
1)
0-based, i.e. if the first argument is displayed, the value is 0.
2)
between 0 and 1; with 0, no further filters are applied since the filter applies to all current results; 1 is the maximum relevance, this filter applies to 50% of the results
3)
If according to <count/> at least 32767 results have been found, this value is only approximated