🚧

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 Question 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 questions for a particular product sorted by submission time

This example call shows how to use multiple filters. The questions are sorted in descending order by Submission Time.

https://stg.api.bazaarvoice.com/data/questions.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&Filter=Productid:data-gen-2s9kaf0ugzn0p2flzl73ahuys&Sort=SubmissionTime:desc

Requesting a question by question ID

https://stg.api.bazaarvoice.com/data/questions.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&Filter=Id:646785

You can request multiple questions by separating the question IDs with a comma

• e.g. filter=id:14801,14802,14902

Requesting a single question by question ID including answers

https://stg.api.bazaarvoice.com/data/questions.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&Filter=Id:646785&Include=Answers

You can request multiple pieces of related information by separating them with a comma.

• e.g. include=products,categories,authors.

Requesting 10 questions, sorted by submission time in descending order for a particular product

https://stg.api.bazaarvoice.com/data/questions.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&Sort=SubmissionTime:desc&Limit=10&Filter=Productid:data-gen-2s9kaf0ugzn0p2flzl73ahuys

You can sort by multiple attributes by separating them with a comma

• e.g. sort=id:desc,submissiontime:asc

Requesting all native (non-syndicated) questions

❗️

Native (non-syndicated) content only. Continue reading for more details.

https://stg.api.bazaarvoice.com/data/questions.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4

Requests for this content type that do not include a ProductId, AuthorId, CategoryAncestorId, SubmissionId, or Question Id filter will only work with API keys that are configured to exclude syndicated content.

We recommend using our Displayable Content Export service to download all of your native and syndicated content. If you still prefer the Conversations API, then you may contact our support team to have your Conversations API keys re-configured.

Parameters

Filter options

• Each filter argument specifies the attribute to filter on followed by a comma-separated list of values. For instance, "Filter=Id:eq:3,4" will match Questions with Ids 3 OR 4.
• Advanced operators can be used to define filters. For instance, "Filter=Id:gt:50" will match Questions with an Id value greater than 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=ProductId:eq:75&Filter=isfeatured:eq:true" will match all featured Questions for the Product with Id 75.
• Time-based filters can be used for SubmissionTime, LastModificationTime and LastModeratedTime. 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 was submitted on November 9, 2009: &filter=SubmissionTime:gt:1257746400&filter=SubmissionTime:lt:1257832800

The following table lists the attributes available for filtering.

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 for a content/subject type.
  • e.g. Sort=rating:asc,submissiontime:desc

The following table lists the attributes that are available for sorting.

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

Error codes

🚧

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/questions.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/questions.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4k&Filter=ProductId%3Adata-gen-moppq9ekthfzbc6qff3bqokie&Include=Products' \
--header 'bv-version: 5.4.1'