Understanding the FHR Query Response
Learn how the Fredhopper Query API response delivers the data and components your storefront needs to render dynamic pages by view type.
Introduction
The Fredhopper Query API response powers the dynamic pages of your storefront. When the front end sends a query to Fredhopper, the response returns all the structured data needed to fully render a whole page.
Depending on your implementation, Query API responses can be returned in XML- or JSON-format. You can read more on formats and best practices here.
The response is split into distinct components or sections, each of which is intended to be rendered by your web application in the presentation layer, for example, product results, filters, or breadcrumbs.
Fredhopper does not render UI elements. Your front-end application is responsible for interpreting these sections and rendering the corresponding components.
For examples of FHR responses see Query and Response Examples.
Depending on the view type being requested, the response will include the elements relevant for that context and omit or tailor those that are not needed. The supported view types are:
“home”: a homepage
“summary”: a landing page
“lister”: a product listing page from navigation
“search”: a product listing page from search
“detail”: a product detail page
“compare”: a comparison page including information on multiple items
The view type is determined in the corresponding Fredhopper API Query, i.e. “fh_view”.
This design ensures that each page type receives exactly the right set of data to display the correct products and UI components, enabling a consistent and efficient integration between Fredhopper and your storefront.
Each element of the query result is formally defined and documented in the Fredhopper XSD, WSDL, or the JavaDoc of the SOAP classes, depending on the integration method you are using. If you require access to the relevant schema reference files, please contact your Technical Consultant.
See Fredhopper response components per view type for a table comparing the components included in the response across different view types.
Main components
The Fredhopper response is composed of three main components that your web application uses to build the final page: info, universes, footer. Each component contains specific types of information that your storefront renders in the presentation layer.
When working with Fredhopper responses start with the “info” section to understand the context of the request. Use the “universe”s section to render the actual page content, including navigation elements, filters, product data, and merchandising campaigns. The footer section contains additional technical information that is used for logging.
Fredhopper responses of the view type “search” furthermore include the sections “searchterms” and “searchpass”.
Intro
The “info” section contains metadata about the query and response context. This includes parameters such as the active locale, current universe (catalog), view type (e.g., search or detail), and the encoded query string.
Universes
The “universes” section holds the core content blocks that drive what users see and interact with on the page. Each universe typically contains the following sections:
“link”: Contains the name and URL-parameter of the universe.
“breadcrumbs”: Contains the navigational path taken by the user (e.g., Home > Category > Subcategory).
“facetmap”: Contains a structured list of available filters and refinements (e.g., size, brand, price ranges) that enable interactive filtering on listing pages
“items-section”: Contains a list of products returned by the query.
“themes”: Contains information on all campaigns, i.e. merchandising content such as promotional banners, curated product groups, or special offers.
“display-fields”: Contains the attributes intended for display and the order in which they are shown. Note that this section does not contain information on the actual value of these fields.
Display fields are configured in the Merchandising Studio (System > Display fields).
“attribute-types”: Contains attribute metadata.
The following shows which parts of a navigation-derived product listing page (view type: “lister”) are powered by each section of the Fredhopper Query response:
Footer
The “footer” section contains additional response data that does not directly map to UI content. This may include logs or other technical details that are useful for diagnostics or logging. It is typically not rendered in the storefront UI but can be important for back-end processes or monitoring.
Examples
Which sections are included in the Fredhopper Query API response depends on the view type. We have shown a navigation-derived product listing page above.
You can find more information on best practices here.
The below example shows a search-derived product listing page (view type: “search”).
Note the following:
In addition to the components info, universes, and footer the responses of the view type “search” include the components “searchterms” and “searchpass”.
A response of the view type “search” also includes the section “breadcrumbs”, since a customer may start a search after having navigated to a specific category.
The attribute on which a filter is based is always defined in
universes.universe[*].facetmap.filter[*][“on”].The type of filter is defined in
universes.universe[*].facetmap.filter[*][“display-hint”].The section “display-fields” only determines which attributes are shown for this specific view type. The section does not include information on the specific values for these attributes. You can find the attribute values for each item in the section “items-section”.
The below example shows a product detail page (view type: “detail”).
Note the following:
The part “item-section” in a response of the view type “detail” usually only includes a single item.
If the product detail page was derived from a search, the search term can be found in the section “breadcrumbs”.
Response components by view type
"home" (homepage)
Yes
Yes
No
(Configurable)
Yes
"summary" (landing pages)
Yes
Yes
No
Yes
"lister" (item list for browsing location)
Yes
Yes
Yes
Yes
"search" (Item list for free text search)
Yes
Yes
Yes
Yes
"detail" (details on a single item)
Yes
Yes
(Configurable)
Yes (Just one)
Yes
"compare" (details on multiple items for comparison)
Yes
Yes
(Configurable)
Yes
Yes
Last updated