Retrieving refinements with the API

Displaying attribute values for your refinements is the core concept behind Guided Navigation.

After a user creates a query using record and/or value search, only valid remaining refinement values are provided to the user to refine that query. This allows the user to reduce the number of matching records without creating an invalid query.

To display refinements, they need to be requested, that is, included in the Conversation Web Service request that describes the navigation menu. If the refinements belong to a group, this group needs to be requested. The following example shows the request in which a group of refinements is requested. This example assumes that the group "Wine Characteristics" exists and includes the refinements WineType, Year and Scope:

<Request xmlns="http://www.endeca.com/MDEX/conversation/2010">
  <State/>
  <ContentElementConfig xsi:type="NavigationMenuConfig"
    Id="NavigationMenu"
    HandlerFunction="NavigationMenuHandler"
    HandlerNamespace="http://www.endeca.com/MDEX/conversation/handlers/2010"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <RefinementGroupConfig Name="Wine Characteristics" Expose="true"/>
  </ContentElementConfig>
</Request>

The refinements WineType, Year and Scope will be returned along with the group "Wine Characteristics" in which they are included.

If you would like to retrieve refinements that are not explicitly included in any user-configured groups, you can request a group system-navigation_InternalGroup. This group exists in the MDEX Engine and includes all refinements that are not members of any other groups.