Category Display
Returns categories and related data.
Only API keys on our Conversations platform are eligible to use this API version. Refer to the Platforms section of our Platform & API Concepts documentation to learn which platform your API keys are on.
Try out Category Display API reference here.
Examples
The following examples demonstrate common Conversations API display requests. For a complete overview of using the Conversations API to display data, refer to the Display tutorials.
Demonstration purposes only. Do not reuse the API passkeys below in your application.
Requesting all categories
https://stg.api.bazaarvoice.com/data/categories.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4
Requesting all categories sorted alphabetically by name
https://stg.api.bazaarvoice.com/data/categories.json?apiversion=5.4&sort=Name:asc&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4
Requesting all active categories
https://stg.api.bazaarvoice.com/data/categories.json?apiversion=5.4&filter=IsActive:eq:true&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4
Requesting a category by ID
https://stg.api.bazaarvoice.com/data/categories.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=id:data-gen-t3jxodbtmy8n9fzn1vm88yjec
You can request for multiple categories by ID by separating the IDs with a comma.
- e.g. filter=id:1234,5678,3456
Requesting categories by category ancestor ID
https://stg.api.bazaarvoice.com/data/categories.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=ancestorid:data-gen-p1ctf5q98ok8vbe88fqncwahl
Parameters
| Name | Description | Required | Default Value |
|---|---|---|---|
ApiVersion |
The API version, e.g. 5.4. | Yes | |
[FORMAT] |
Response format (json) | Yes | |
PassKey |
API key is required to authenticate API user and check permission to access particular client's data. | Yes | |
Callback |
Callback function name used with JSONP. Value is a string consisting of the following characters: a-z,A-Z,0-9,_ (excluding comma). See the JSONP tutorial for more information. |
No | |
Filter |
Filter criteria for primary content of the query. Multiple filter criteria are supported. | No | |
Limit |
Max number of records returned. An error is returned if the value passed exceeds 100. | No | 10 |
Locale |
Locale to display Labels, Configuration, Product Attributes and Category Attributes in. The default value is the locale defined in the display associated with the API key. | No | |
Offset |
Index at which to return results. By default, indexing begins at 0 when you issue a query. Using Limit=100, Offset=0 returns results 0-99. When changing this to Offset=1, results 1-100 are returned. The maximum supported value is 300000. | No | 0 |
Sort |
Sort criteria for Categories. Multi-attribute sorting is supported. |
No | Id |
Filter options
- Each filter argument specifies the attribute to filter on followed by a comma-separated list of values. For instance, "Filter=Id:eq:5,6" will match all categories with Id 5 OR 6.
- Advanced operators can be used to define filters. For instance, "Filter=Id:lte:50" will match all categories with an Id value of less than or equal to 50. All advanced operators are documented on the Conversations API page.
- If a filter value contains a comma or a colon, that character needs to be escaped with a backslash (, or :). If a filter value contains an ampersand (&), the ampersand must be encoded in the filter value by replacing & with %26.
- Multiple filters are allowed as URL parameters in which case filters are AND'ed. For instance, "Filter=AncestorId:eq:5&Filter=IsDisabled:eq:false" will match all categories that are not disabled and that have an ancestor category with Id 5.
The following table lists the attributes available for filtering.
| Name | Description |
|---|---|
Id |
The identifier of the Product Category.
|
AncestorId |
Id of the Ancestor of the Category.
|
IsActive |
Boolean flag indicating whether the Category is Active.
|
IsDisabled |
Boolean flag indicating whether the Category is Disabled.
|
Name |
The Name of the Category.
|
ParentId |
The Id of the Parent of the Category.
|
Sort options
- Sort order is required (asc or desc). There is no default.
- Multi-attribute sorting is supported by using a comma separated list of sort criteria.
- e.g. Sort=ParentId:asc,SubmissionTime:desc
The following table lists the attributes that are available for sorting.
| Name | Description |
|---|---|
Id |
The identifier of the Product Category.
|
IsActive |
Boolean flag indicating whether the Category is Active.
|
IsDisabled |
Boolean flag indicating whether the Category is Disabled.
|
Name |
The Name of the Category.
|
ParentId |
The identifier of the Parent of the Category.
|
Response format
This is a sample response for requesting reviews. Use the links above to see live examples.
{
"Includes": { },
"HasErrors": false,
"Offset": 0,
"TotalResults": 224775,
"Locale": "en_US",
"Errors": [ ],
"Results": [
{...}
{...}
],
"Limit": 2
}
Response elements
| Name | Description |
|---|---|
Includes |
Included results related to primary results. For example, with the request
reviews.json?include=Comments, the Include node will be populated with comments associated with the reviews in the Results node.
|
HasErrors |
Boolean value indicated if one of more errors have occurred. See Errors below.
|
Offset |
Dataset offset used for pagination (passed as URL parameter in a query request). The maximum supported value is 300000.
|
TotalResults |
Total number of records matched.
|
Locale |
Indicates the language by region (language_region) associated with the client instance. This is the value used for field labels returned by the API, not the region from which the reviews originate.
|
Errors |
Error section is populated instead of other fields if there is an error with a query syntax or problem executing a query.
|
Results |
Section containing an array of primitive type object references matched by a query.
|
Limit |
The total number of results returned, specified by user in the URL. Defaults to 10 and has a maximum of 100.
|
Error codes
| Value | Description |
|---|---|
ERROR_ACCESS_DENIED |
Insufficient privileges to perform the operation |
ERROR_PARAM_INVALID_API_KEY |
Invalid API Key value |
ERROR_PARAM_INVALID_CALLBACK |
Invalid JsonP callback function name |
ERROR_PARAM_INVALID_FILTER_ATTRIBUTE |
Invalid filter attribute name |
ERROR_PARAM_INVALID_INCLUDED |
Invalid parameter value |
ERROR_PARAM_INVALID_LIMIT |
Invalid limit value |
ERROR_PARAM_INVALID_LOCALE |
Invalid locale code |
ERROR_PARAM_INVALID_OFFSET |
Invalid offset value |
ERROR_PARAM_INVALID_SORT_ATTRIBUTE |
Invalid sort attribute name |
ERROR_UNKNOWN |
Unknown error (internal server error, for instance) |
By default, for all the form errors occurred during the API calls, the HTTPS response code 200 OK is returned, with the error information in the JSON response body.
curl --location 'https://stg.api.bazaarvoice.com/data/categories.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4k&Filter=ProductId%3Adata-gen-moppq9ekthfzbc6qff3bqokie&Include=Products'
If the clients wish to receive 4xx, 5xx kind of error codes in HTTPS response, a small addition needs to be made to the api call. In the request header of the API call, add "bv-version" with value "5.4.1", this will generate appropriate 4xx, 5xx error codes in the HTTPS response. The JSON response still contains the detailed description of the error.
Example curl with header:
curl --location 'https://stg.api.bazaarvoice.com/data/categories.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4k&Filter=ProductId%3Adata-gen-moppq9ekthfzbc6qff3bqokie&Include=Products' \
--header 'bv-version: 5.4.1'
Updated about 1 month ago