Skip to main content
GET
/
category_merchandising
/
{hashid}
Get category page results
curl --request GET \
  --url https://{zone}-category-merchandising.doofinder.com/api/1/category_merchandising/{hashid} \
  --header 'Authorization: <api-key>'
{
  "results": [
    {
      "dfid": "abc1234de@product@a1b2c3",
      "id": "SKU-001",
      "title": "Running Shoes Model X",
      "price": 99.99,
      "url": "https://example.com/products/sku-001",
      "image_url": "https://example.com/images/sku-001.jpg"
    },
    {
      "dfid": "abc1234de@product@d4e5f6",
      "id": "SKU-002",
      "title": "Trail Running Shoes Y",
      "price": 129.99,
      "url": "https://example.com/products/sku-002",
      "image_url": "https://example.com/images/sku-002.jpg"
    }
  ],
  "total": 243,
  "page": 1,
  "rpp": 50,
  "facets": {
    "brand": {
      "_type": "terms",
      "buckets": [
        {
          "key": "Nike",
          "doc_count": 42
        },
        {
          "key": "Adidas",
          "doc_count": 38
        }
      ]
    },
    "price": {
      "_type": "range",
      "buckets": [
        {
          "stats": {
            "min": 9.99,
            "max": 499.99,
            "avg": 89.5
          }
        }
      ]
    }
  },
  "base_filter": [
    {
      "field": "category",
      "values": [
        "shoes"
      ]
    }
  ],
  "filter": [],
  "banner": {
    "id": "189523",
    "image": "https://example.com/banners/shoes-banner.jpg",
    "mobile_image": "https://example.com/banners/shoes-banner-mobile.jpg",
    "html_code": null,
    "link": "https://example.com/sale/shoes",
    "target_blank": true
  }
}

Authorizations

​
Authorization
string
header
required

API token in the format Token {your_token}. Required for server-side requests. Browser requests from allowed origins are authenticated automatically via CORS and do not need this token.

Authorization: Token abc123xyz

Path Parameters

​
hashid
string
required

Search Engine ID (also known as hashid).

Example:

"abc1234de"

Query Parameters

​
url
string
required

Full URL of the category page to match against the configured URL patterns. Query string and fragment are stripped before matching.

Example:

"https://example.com/categories/shoes.html"

​
currency
string

ISO 4217 currency code. When provided, prices are converted to this currency using the exchange rates configured in the search engine.

Example:

"EUR"

​
page
integer
default:1

Page number (1-indexed). Defaults to 1.

Required range: x >= 1
Example:

2

​
rpp
integer
default:50

Number of results per page. Defaults to 50.

Required range: x >= 1
Example:

24

​
sort[N][field]
enum<string>

Sort criteria in indexed map format. N is a 0-based integer that defines the sort priority. field is the name of the field to sort by, and the value is the direction (asc or desc).

Example: sort[0][price]=asc&sort[1][brand]=desc sorts first by price ascending, then by brand descending.

If omitted, the sort configured in the category page settings is used.

Available options:
asc,
desc
​
filter[field][]
string[]

Additional filter values to narrow the result set. field is the name of the indexed field. Repeat the parameter with different values to match any of them (OR logic within the same field).

Example: filter[brand][]=Nike&filter[brand][]=Adidas

Fields that conflict with the URL pattern filter are silently ignored.

​
exclude[field][]
string[]

Exclude items with these field values from the results. field is the name of the indexed field. Repeat the parameter to exclude multiple values.

Example: exclude[dfid][]=abc123&exclude[dfid][]=def456

​
results_personalization_dfids[]
string[]

List of Doofinder item IDs (dfid) representing items the user has recently interacted with. When provided, results are reordered to surface contextually relevant items.

Example:
[
  "abc1234de@product@a1b2c3",
  "abc1234de@product@d4e5f6"
]

Response

Search results for the matched category page.

Search results and metadata for the matched category page.

​
results
object[]

Ordered list of result items for the current page.

​
total
integer

Total number of items matching the effective filter (across all pages).

Example:

243

​
facets
object

Aggregations for the result set. Fields used by the URL pattern filter are excluded, as those dimensions cannot be changed by facet navigation.

​
page
integer

Current page number.

Example:

1

​
rpp
integer

Number of results per page.

Example:

50

​
base_filter
object[]

The URL pattern filter applied to this category page, expressed as a list of field/values pairs. This filter is always present and is derived from the matched URL pattern. It cannot be overridden by client-supplied filters.

​
filter
object[]

The additional client-supplied filters applied to the search, expressed as a list of field/values pairs. This reflects only the filters passed by the caller via filter[field][]=value query parameters, excluding any keys that conflict with base_filter.

​
banner
object | null

A promotional banner associated with the current category filter, if one is configured. null when no banner is configured for the matched category.