Category API
What does the category API do?
The category API sends a category query to retrieve results about products within the categories that you specify. It's very similar to the product search API, which sends a keyword query.
Example request
Here’s an example REST API call for a category query, using the category ID, cat000922.
Request
GET http://core.dxpapi.com/api/v1/core/? account_id=<Bloomreach Provided Account ID> &auth_key=jazzhands &domain_key=example_com &request_id=8830241055597 &_br_uid_2=uid=7797686432023:v=11.5:ts=1428617911187:hc=55 &ref_url=http://www.example.com/home &url=http://www.example.com/index.html?q=cat000922 &request_type=search &rows=20 &start=0 &fl=pid,title,brand,price,sale_price,colors,sizes,thumb_image,price_range,sale_price_range &q=cat000922 &search_type=category
Notice that this request is very similar to a product search request except that &search_type is set to category instead of keyword.
For Category Pathways you have to use widget.dxpapi.com instead of above endpoint, rest of the parameters remain the same.
All of the parameters in the call are required parameters for all category calls. Your own category calls might include optional parameters, but must always include these parameters, too. As a category search query, these parameters must be defined with a specific setting:
-
request_type must be set to search
-
search_type must be set to category
Request parameters
These are the parameters used in the example request. Every product search request needs these parameters.
Some of the parameters in your API requests for native mobile apps or non-JS environment need different values from those for your site:
● _br_uid_2: The value should be the same as described on the Cookie page. Generate a br_uid_2 for your app user and store it in the app permanently if a br_uid_2 does not exist. This br_uid_2 should be used on the corresponding API calls for the app. If the user is on iPhone and resets their IDFA, or if the user is on an Android device and resets their advertising settings: the br_uid_2 should be erased and regenerated the next time the app is set.● ref_url: Leave your ref_url parameters empty.
● url: Use a dummy value for your url parameters, such as exampledomain.app.
|
_br_uid_2 |
A first-party cookie created by the Bloomreach tracking pixel library (BrTrk). This cookie creates a unique, anonymous identifier for every browser or device.
The _br_uid_2 cookie is already encoded
Don't encode the cookie parameter value: _br_uid_2. Use this value exactly as it comes. It's already encoded. &_br_uid_2=uid%3D7797686432023%3Av%3D11.5%3Ats%3D1428617911187%3Ahc%3D55 Value typestring Example value
|
||
|
account_id |
Your site's numerical Bloomreach account ID. Your Bloomreach representative gives your site's account ID to you before or during your integration kickoff meeting. Notify your Representative
If you don't have a Bloomreach account ID, then let your Bloomreach Representativeknow immediately. You can't send any API calls without your account ID. Value typeinteger Example value
|
||
|
auth_key |
The Bloomreach-provided authentication key for the Bloomreach account that's sending the request. Leave auth_key parameter values empty for client-side calls
If you use client-side calls for any of your Bloomreach requests, then do not enter an auth_key value in those client-side calls. Pass the auth_key with an empty value in client-side calls. The auth_key value is a private authorization key. If you include your valid auth_key value in client-side calls, then you inadvertently expose that private information to everybody. Value typestring Example value
Your own auth_key value looks very different from this example. We're using an odd example value to reinforce the importance of treating this key like you treat other keys like your email login credentials: don't share it. |
||
|
domain_key |
Your site domain's ID, which is provided by Bloomreach. This ID is for the domain that you want to receive your Bloomreach API requests. This parameter identifies the specific site version when the one account ID hosts multiple site versions with unique characteristics, such as language versions. Bloomreach uses your domain_key parameter value to ensure that only the data that pertains to that site version is used for query and analytics features, such as autosuggestions. Value typestring Example value
|
||
|
fl |
The attributes that you want returned in your API response, such as product IDs and prices. All fl parameters must include pid as one of their values. You can include other attributes from your product feed. Tip
Include all the attributes from your product feed that you want to include in search results, not just the attributes that you want to be returned as objects in your API response. Your search results pages are built from your API responses. Therefore, search results pages can only include attributes that are returned in API responses. Value typestring Example value
Example value for Content
Comma-separated values
Separate multiple attributes with a comma: &fl=pid,title,thumb_image,price |
||
|
q |
Your site's category ID. Value typestring Example value
|
||
|
ref_url |
The URL of the page or HTTP referrer where the request is started. Value typestring Example value
Required Only mandatory if you want to use Targeting |
||
|
request_id |
An ID to track site visitor clicks. We recommend that you generate unique, random values of 13 digits to enable click-tracking. Bloomreach doesn't automatically enforce the requirements for this parameter. For example, you can enter test as your value for each instance of the request_id parameter without triggering an error message. However, using a unique value allows us to help you if you encounter a problem. Value typestring Example value
|
||
|
request_type |
The type of API request. Choose the value that fits your use case:
Value typestring (enum)
Use search for search API calls
The only correct &request_type value for a category search API call is search. |
||
|
rows |
The number of matching items to return per results page in the API response. The maximum value is 200. Tip
To enhance performance, limit this value to the number of items that you think is reasonable for a single page of search results. Value typeinteger Example value
|
||
|
search_type |
The type of search. Choose the value that fits your use case:
Value typestring (enum)
Use category for category API calls
The only correct &search_type value for a category search query is category. |
||
|
start |
The number of the first item on a page of results. For example, the first item on the first page is 0, making the start value also 0. The maximum value is 10000. Value typeinteger Example value
|
||
|
url |
The absolute URL of the page where the request is initiated. Use the absolute URL
Don't use a relative URL for your url parameter value. Value typestring Example value
|
Use case-dependent parameters
These parameters are for specific product search use cases. Each parameter has a section that tells you which use cases require the parameter.
|
callback |
Indicates whether to return data wrapped in the function for cross-origin requests. If you're running a server-side request, then use the value, br_server. If you're running a native-app request, then use the value, br_app. Value typestring (enum) Example value
Use caseReturn data wrapped in the function for cross-origin requests. |
|
| fq |
The fq parameter applies a faceted filter to the returned products, searching for content that fit your parameter values. Any facet that you want to filter must be in your content feed. Read more about using the fq parameter in the "Simple Filtering" section in the Faceting and filtering page. Attributes must be enabled and mapped by Bloomreach
Let your Bloomreach representative know which attributes in your content feed that you want to apply as filters to search results. Value typestring Example value
fq Syntax
To learn about the syntax for fq, to go the "Syntax for fq and efq parameters" section on Faceting and filtering page. Use case Apply filtering to search results. Specify a particular type of non-product content. |
|
|
efq |
Applies a complex boolean filter to search results to include or exclude items that fit your parameter values. Any product attribute in your product feed is valid, such as brand names and sizes. Typically, the efq parameter is used for custom attributes that you include in your product feed to support additional business logic that you might need to filter. Read more about using the efq parameter in the "Complex boolean filtering" section in the Faceting and filtering page. efq or fq?
Values for the efq parameter are similar to values for the fq parameter. The difference between efq and fq is that efq supports complex boolean searches and fq filters on facets. You can use the fq parameter with the efq parameter to apply more complex filtering. Read more in the "Complex boolean filtering" section in the Faceting and filtering page. Value typeString Example value
Use caseApply complex filtering to search results. |
|
|
facet.range |
Return a count of ranged facets, such as price and sale price. Use numeric attributes only. Value typestring Example value
Use caseApply ranged filtering to search results. |
|
|
sort |
Sorts results based on the field value in ascending, descending, or another combination of orders. You can sort any fl field. Some examples are given below:
Value typestring (enum)
Use caseSort search results by certain attributes. |
|
|
user_id |
The universal customer ID of the user. You only need to pass this field if your particular integration tracks customers this way. The parameter captures user IDs from the customer side, and reuses the information when powering apps or enhancing cross-device linking. In this way, Bloomreach recognizes users in a way that's aligned with your system. Use an anonymous string. Don't use email or other personally identifiable information. If you do not track users this way, then omit this field. Value typestring Example value
Track individual site visitor behavior. |
|
|
view_id |
A unique identifier for a specific view of your product catalog. If you have multiple versions of your site, each with their own product catalog characteristics like product titles and prices, then add view_id to your call. Bloomreach uses your view_id parameter value to display the right product information for your customers based on their individual site views. You can enter any string value to identify the specific site catalog view. This string must be consistent in your pixel, API, and product catalog. For example, Abacus Thinking sells different academic products to different grade levels. A first grade teacher looks in their Kindergarten through Grade 3 catalog, which Abacus Thinking assigns the ID, k-3:
Consistent, valid values Your view_id values must be the same in your API, pixel, and product catalog. If Abacus Thinking assigns the value, ACA-MAX, to the view_id parameter in their product feed, then the parameter value, academia maximiliano, doesn't match any catalog view. Value typestring
Use caseSearch a specific view of a site with multiple versions. |
|
|
widget_id |
This widget_id is provided via the brSM dashboard under "Dynamic Widgets" to fulfill certain usecases where the results need to be independently curated by business users. This is an optional feature that can be enabled by discussing with your CSM. Example
Use caseRetrieve a specific Dynamic Widget based result set using a widget_id |
|
|
wt |
Specifies the type of response. Use one of the following values:
Value typestring (enum) Example value
Use caseReturn results in HTML. |
When you use the query '*' as 'q=*' in the API request, the latency of the response will vary depending on your catalog size and it may not adhere to the Bloomreach's standard SLA. Further, please note that except for include/exclude operation, other merchandising operations such as boost/bury or slots do not work on * query parameters.