Working with attributes and refinements using the API

This section provides examples of Conversation Web Service requests and responses that work with attributes and refinements.

NavigationMenuConfig
NavigationMenuConfig is the element in the Conversation Web Service request where instructions are specified for how to return refinements and how those refinements should behave. This gives you a lot of control in which information about refinements you would like to retrieve, to build the Guided Navigation experience for the end users. For example, the request can specify whether to compute and return values for all refinements, whether to return a full path of the hierarchical refinements, what should be the maximum number of refinements returned, and whether to retrieve already applied refinements, such as those that were applied implicitly.
RefinementGroupConfig
The RefinementGroupConfig element returns a list of refinements from those attributes that are included in attribute groups.
RefinementConfig
The RefinementConfig element controls the behavior of an individual attribute in a NavigationMenuConfig.
PropertyListConfig
In a query, the PropertyListConfig type returns a list of all available attributes for the data domain.
SelectedRefinementFilter
The SelectedRefinementFilter type allows you to create a refinement navigation query from a specific refinement.
Obtaining a list of available attributes
When configuring attributes for refinements, it is useful to first obtain a list of available attributes. You can do this, utilizing PropertyListConfig request of the Conversation Web Service, or listProperties and RecordKind requests from the Configuration Web Service.
Retrieving refinements with the API: high-level overview
Displaying attribute refinement values is the core concept behind Guided Navigation. This topic provides a high-level overview of the procedure for retrieving and then applying refinements.
Retrieving the full list of refinements (applied and suggested)
By default, once end users make selections from a list of suggested refinements, Endeca Server narrows the result set. It does not return those refinements that have already been selected and returns remaining available, or suggested, refinements. However, in some cases, it may be useful to ask Endeca Server to return both suggested and already-applied refinements, (including both types of applied refinements: explicitly-selected and implicit).
Increasing the number of refinements to be displayed
The number of refinements that are displayed defaults to 10. If this number is not sufficient, you can increase it using NavigationMenuConfig in the Conversation Web Service request.
How refinement counts are returned
The application user interface can display the number of records returned for each refinement. These record counts are returned in a Count attribute.
Retrieving the order of refinements
A core capability of Endeca Server is the ability to dynamically order and present the most popular refinement values to the user.
Retrieving the full path of hierarchical refinements
For managed attribute groups (which are groups of those attributes that contain hierarchy), you can request hierarchy information about a refinement with the ReturnFullPath specified in NavigationMenuConfig. In addition, for managed attribute values, hierarchy information is returned with DimensionHierarchy and DimensionValueWithPath types in any record list request.