The Conversations API lets you programmatically retrieve and submit Bazaarvoice Conversations data for use in your applications. To learn more, go to the Conversations API documentation home page.

Contents

(+ show- hide)

This tutorial introduces developers to Bazaarvoice API rate limiting, explains how to determine the rate limit and offers several suggestions on how to avoid exceeding the rate limit.

Overview

Usage of the Conversations API is rate limited on a per API key, per minute basis. Each key has it's own limit and using one key does not impact the limit of a different key. Initially keys are set to a default limit, which should be sufficient for most of our clients and we will pro-actively raise it during the holiday to accommodate the traffic increase across our network.

Why rate limit

The Bazaarvoice platform is a multi-tenant system in which many clients share the same system resources. As a result it is important that excessive usage is limited to protect the stability of the network for everybody. Without a rate limit, poorly constructed applications or unforeseen circumstances could have negative consequences on network performance and availability.

Determining rate limit

There are two ways to determine rate limit:

Developer Portal

Only keys requested using our API key request process will be accessible in the Developer Portal.

You can find the rate limit for a particular API key by logging into the Developer Portal, then hovering over your user name in the top right and selecting the the My Keys link.

HTTP headers

The Conversations API will return the following headers, which your application can use to ensure that it does not exceed the rate limit.

Name Description
X-Bazaarvoice-QPM-Allotted

The maximum QPM (queries per minute) capacity set on your API key. This is the maximum number of calls that can be made in any given minute.

X-Bazaarvoice-QPM-Current

The current count of calls being applied against the above limit; in this case, it is a representation of how many calls your key is making at that particular minute in time.

X-Bazaarvoice-QPS-Allotted

QPS has been superseded by QPM. New applications should ignore QPS and existing apps to stop relying on it.

The maximum QPS (queries per second) capacity set on your API key. This is the maximum number of calls that can be made in any given second.

X-Bazaarvoice-QPS-Current

QPS has been superseded by QPM. New applications should ignore QPS and existing apps to stop relying on it.

The current count of calls being applied against the above limit; in this case, it is a representation of how many calls your key is making at that particular second in time.

X-Bazaarvoice-Quota-Allotted

The maximum number of calls that can be made on hourly basis.

X-Bazaarvoice-Quota-Current

The current count of calls made in the current limit period.

X-Bazaarvoice-Error-Detail

An error message returned when the QPM or quota is exceeded.

X-Bazaarvoice-Quota-Reset

The time when the rate limit will reset to 0.

In the following example the rate limit has been exceeded (X-Bazaarvoice-QPM-Current is greater than X-Bazaarvoice-QPM-Allotted).

HTTP/1.1 200 OK
"Content-Type":"application/json",
"Date":"Mon, 24 Apr 2017 20:02:46 GMT",
"Server":"Apigee Router",
"X-Bazaarvoice-error-detail":"Account Over Queries Per Second Limit",
"X-Bazaarvoice-QPM-Allotted":"60",
"X-Bazaarvoice-QPM-Current":"60",
"X-Bazaarvoice-QPS-Allotted":"1",
"X-Bazaarvoice-QPS-Current":"1",
"X-Bazaarvoice-Quota-Allotted":"7200000",
"X-Bazaarvoice-Quota-Current":"63",
"X-Bazaarvoice-Quota-Reset":"2017-04-24T21:00:00.000Z",
"Content-Length":"250",
"Connection":"Close"
Do not rely on the order or capitalization of headers.

How to avoid exceeding the limit

Here are some suggestions on how to avoid exceeding the rate limit.

  • Use API keys appropriately

    API keys should be used on a per application basis. For example you may have an API key for an application that shows user generated content (UGC) on a social network and a different API key for your eCommerce site. It is also appropriate to use one API key per locale or region. A client that serves traffic to users in the United States and Europe might have two API keys, one for each region.

  • Make requests efficiently

    Making unnecessary requests is a common reason applications exceed the rate limit. A typical product page should only need one request to load the first page of UGC and then only make subsequent requests as users indicate their desire to see alternate views (e.g. pagination, filtering, sorting, etc). Further, secondary content like review comments and answers to questions can be requested along with the primary content using the &include parameter.

  • Local caching

    If you're already using your API keys appropriately and making efficient requests you might try caching frequently needed resources. The exact implementation is up to each client, but could involve pre-rendering product pages with UGC included, saving UGC in a data store or the users browser as it is requested, or hosting a aching proxy between your application and the Bazaarvoice platform. Refer to our caching tutorial to learn more.

  • Store data you need

    Serve UGC to your end-users from your data store, which is created and updated using data from the Bazaarvoice platform independent of end-user demand. This gives you complete control of the requests you make to Bazaarvoice and how you use your data.

    Approval required
    This option is limited to clients with prior approval. Contact your Bazaarvoice representative or our Support team if you would like to use the Conversations API to create your own UGC data store.
  • Increase the limit

    Finally you may contact your Bazaarvoice representative or our Support team if you feel that the limit is insufficient for your needs. Rate limit increases must be approved and may require additional charges.