Category Display
Only API keys on our Conversations PRR 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
Returns categories and related data.
Examples
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=kuy3zj9pr3n7i0wxajrzj04xo
Requesting all categories sorted alphabetically by name
https://stg.api.bazaarvoice.com/data/categories.json?apiversion=5.4&sort=Name:asc&passkey=kuy3zj9pr3n7i0wxajrzj04xo
Requesting all active categories
https://stg.api.bazaarvoice.com/data/categories.json?apiversion=5.4&filter=IsActive:eq:true&passkey=kuy3zj9pr3n7i0wxajrzj04xo
Requesting a category by ID
https://stg.api.bazaarvoice.com/data/categories.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&filter=id:testCategory1011
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=kuy3zj9pr3n7i0wxajrzj04xo&filter=ancestorid:testCategory1050
Category text search
https://stg.api.bazaarvoice.com/data/categories.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&search=%22Retail%22
The results returns categories that contain the word "Retail".
Parameters
| Name | Description | Required | Default Value |
|---|---|---|---|
ApiVersion | The API version, e.g. 5.4. | Yes | |
[FORMAT] | Response format ( xml This feature will not be available or will behave differently in future versions of the Conversations API. Click for more information. or 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 | |
Include | This parameter is used to specify related data to be included, e.g., Products, Questions, Answers . | No | Will only return Answers |
Limit | Max number of records returned. An error is returned if the value passed exceeds 100. | No | 10 |
Limit_TYPE | Limit option for the nested content type returned. TYPE can be any nested content. e.g. Answers for Questions. An error is returned if the value passed exceeds 20. | 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 |
Search | Full-text search string used to find UGC. For more information about what fields are searched by default, see the Conversations API page. Note: This invalidates sort options due to the fact that search takes precedence in returned data. | No | |
Search_[Type] | Searching option for included content followed by full-text search string. See the Conversations API page for examples of searching for included data. Note: This invalidates sort options due to the fact that search takes precedence in returned data. | No | |
Sort | Sort criteria for Categories. Multi-attribute sorting is supported. | No | Id |
Stats | The content types for which statistics can be calculated for the category. Available content types are: Stories , Questions, Answers. Note: Statistics can also be calculated on includes. | No |
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.
- Time-based filters can be used for LastAnswerTime, LastQuestionTime. Dates in time-based filters are calculated as the number of seconds since January 1, 1970, 00:00:00 UTC. In a future version, we will be adding support for comparing date/time string values. The following example returns content that has its last question submitted on November 9, 2009: &filter=LastQuestionTime:gt:1257746400&filter=LastQuestionTime:lt:1257832800
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. |
LastAnswerTime | The Submission Time of the latest Answer that was submitted to a Question on the Category. |
LastQuestionTime | The Submission Time of the latest Question that was submitted on the Category. |
Name | The Name of the Category. |
ParentId | The Id of the Parent of the Category. |
TotalAnswerCount | The number of Answers that have been written to Questions on the Category. |
TotalQuestionCount | The number of Questions that have been written on 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. |
LastAnswerTime | The Submission Time of the Answer that was submitted last on the Category. |
LastQuestionTime | The Submission Time of the latest Question that was submitted on the Category. |
Name | The Name of the Category. |
ParentId | The identifier of the Parent of the Category. |
TotalAnswerCount | The number of Answers that have been written to Questions on the Category. |
TotalQuestionCount | The number of Questions that have been written on the Category. |
Response format
Sample response to a Request for all categories limiting the display to 1 entry:
{
"Includes": { },
"HasErrors": false,
"Offset": 20,
"TotalResults": 548,
"Locale": "en_US",
"Errors": [ ],
"Results": [
{
"Name": "Vests",
"Attributes": {
"Department": {
"Values": [
{
"Value": "5",
"Locale": null
}
],
"Id": "Department"
}
},
"ParentId": "WEB_SPECIALS.MENS",
"QuestionIds": [ ],
"AttributesOrder": [
"Department"
],
"ImageUrl": null,
"Id": "WEB_SPECIALS.MENS.VESTS",
"ProductIds": [ ],
"CategoryPageUrl": null
}
],
"Limit": 1
}
Sample response for Errors:
{
"Error": {
"Code": "[ERROR_CODE]",
"Message": "[ERROR_MESSAGE]"
}
}
Response elements
| Name | Description |
|---|---|
Data | Section containing all the data matched by a query grouped by content/subject type. Within each data section there is a map of objects keyed by ids |
Errors | Error section is populated instead of other fields if there is an error with a query syntax or problem executing a query. |
Limit | The total number of results returned, specified by user in the URL. Defaults to 10 and has a maximum of 100. |
Offset | Dataset offset used for pagination (passed as URL parameter in a query request). The maximum supported value is 300000. |
Results | Section containing an array of primitive type object references matched by a query. |
TotalResults | Total number of records matched. |
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) |
Updated 4 months ago