Path analysis tools

get_discovery_path_analysis

Returns the previous or next paths for one search query or category, as shown on its detail page in the Performance dashboard. Set direction to previous for the events shoppers recorded immediately before the query or category, or to next for the events immediately after it. Rows rank by occurrences, and each carries its previous-period value and percent change.

Choose how far to look with level:

  • page (default): The adjacent page view. Path types are QUERY, CATEGORY, PRODUCT, PAGE, and HOMEPAGE.
  • session: The adjacent search or category session. Path types are QUERY and CATEGORY.

For a query, pass the query text as value. For a category, pass its cat_id, exactly as returned by get_discovery_performance_table with entity set to category. Matching is exact and case-sensitive for both, and stored values are usually lowercase, so copy the value from a table row rather than retyping it. A sub-ID such as cl1/abc is a separate category and isn't included under cl1. When no paths match and the value's casing or a category display name is the likely cause, the response includes a hint.

Narrow the results with these parameters:

  • path_types keeps only the path types you list, and exclude_path_types removes them. Use one or the other.
  • value_contains keeps paths whose value contains a substring, such as a query, category, product ID, or page.
  • url_contains keeps paths whose URL contains a substring, for example /c/.
  • min_occurrences drops paths with fewer occurrences in the current period.

Rows are grouped by value and URL, so one page can appear several times when its tracking parameters differ. Add up those rows when you need a single total, or narrow them with url_contains. change_occurrences is N/A for paths with no previous-period occurrences, and those rows sort last when you sort by it. Path data has a shorter history than the other reports, so an older date range can return an empty table. Paths can also be incomplete when page view pixels are missing.

To scope results to one storefront, pass site_group_id. Results then cover only that group's member sites, and site_scope in the response shows which sites were applied.

Request parameters

NameTypeRequired?Description
environmentstrNoThe target environment: production (default) or staging. The value is case-insensitive, and surrounding whitespace is trimmed. Staging-only accounts always resolve to staging, regardless of this value.
entitystrYesThe item to analyze: query (a search term) or category (by cat_id).
valuestr | intYesThe query text or the category's cat_id, exactly as returned by get_discovery_performance_table. Matching is case-sensitive. At the session level, a category display name also works but covers only rows stored under that exact name, so it undercounts.
directionstrYesprevious for the events just before the item, or next for the events just after it.
levelstrNopage for the adjacent page view, or session for the adjacent search or category session. Defaults to page.
path_typeslist[str] | nullNoInclude only these path types, for example ['CATEGORY', 'PRODUCT']. Case-insensitive. Can't be combined with exclude_path_types.
exclude_path_typeslist[str] | nullNoExclude these path types, for example ['HOMEPAGE']. Case-insensitive. Can't be combined with path_types.
value_containsstr | nullNoA case-insensitive substring the path's value must contain.
url_containsstr | nullNoA case-insensitive substring the path's URL must contain, for example '/c/'.
min_occurrencesint | nullNoDrop paths with fewer occurrences than this in the current period. Must be 1 or higher.
account_namestr | nullNoThe account name. Auto-selected when you have exactly one account. Use list_discovery_accounts to see available accounts.
site_group_idstr | int | nullNoA site group ID (numeric) or site group name. This is the recommended way to scope results to a storefront: results are filtered to the group's member sites. Defaults to -1 (account level). Use list_discovery_sites to discover site groups.
daysintNoThe rolling window in days, from 1 to 730, ending on the last available date. Defaults to 30. Ignored when you pass start_date and end_date.
domain_keystr | nullNoThe domain key for one site, for example 'your_domain_com'. Overrides the site group's scope. Valid by itself for a site with no view ID. Use the exact domainKey from list_discovery_sites.
view_idstr | nullNoThe view ID for one site, for example '472'. Pass it with domain_key, and only when list_discovery_sites shows a viewId for that site. A wrong view ID returns the wrong data or none.
start_datestr | nullNoThe start of a custom current period, as YYYYMMDD or YYYY-MM-DD. Pass it with end_date to override days. The period can span up to 730 days.
end_datestr | nullNoThe end of a custom current period. Pass it with start_date. An end date before the start date is rejected.
compare_start_datestr | nullNoThe start of a custom comparison period. Pass it with compare_end_date to override the automatic comparison window. The period can span up to 730 days.
compare_end_datestr | nullNoThe end of a custom comparison period. Pass it with compare_start_date. An end date before the start date is rejected.
sortstr | nullNoThe column to sort by: occurrences, prev_occurrences, or change_occurrences. Defaults to occurrences.
sort_directionstr | nullNoThe sort direction, asc or desc. Defaults to desc.
searchstr | nullNoA case-insensitive substring that filters the path value column. To combine a value filter with the other narrowing parameters, use value_contains instead.
pageintNoThe page number, 1-based. Defaults to 1.
page_sizeintNoRows per page, from 1 to 100. Defaults to 20. Use page to fetch more rows.

Response parameters

The tool returns a CompassResponse object with the following parameters:

ParameterTypeDescription
successboolWhether the request succeeded.
datadict | nullThe requested page of paths.
errorstr | nullError message if the request failed, including the reason the request was rejected.
environment_usedstr | nullThe environment actually queried: production or staging. This can differ from the environment you requested, because staging-only accounts always resolve to staging.

The data object has the following fields:

FieldTypeDescription
rowslist[dict]One record per path. Previous paths hold src_type, src_value, and src_url, and next paths hold tgt_type, tgt_value, and tgt_url. Every row also holds occurrences, prev_occurrences, and change_occurrences.
total_rowsint | nullThe total number of paths matching the filters, across all pages.
pageintThe page number returned.
page_sizeintThe number of rows per page.
hintstrReturned when total_rows is 0 and the casing of value, or a category display name at the page level, is the likely cause.
windowdictThe exact date ranges queried, as ISO dates: start_date, end_date, compare_start_date, and compare_end_date.
site_scopedictThe site scope applied: site_group_id, domain_keys, view_ids, and account_level, which is true when no site filter was applied.
metadictReport metadata, including the report ID and the date ranges the backend used.


Did this page help you?

© Bloomreach, Inc. All rights reserved.