Welcome to the BrandIndex API

Version 0

Here we have some basic documentation for basic API usage. If you're confused about what an "API" is, and what it can be used for in our context, check out this explanation. Also, make sure you know what are the usage limits of the API.

Or, if you feel like inspecting the API results directly, just login with your BrandIndex credentials here and have fun:

(If you already logged in, just click here.)

Documentation

Overall, you should expect the endpoints to return relevant HTTP status codes; for protected endpoints, for example, you will receive HTTP status 401 if you haven't logged in, or 400 if the request has wrong parameters, but 200 if it was successful.

Also, we try to leverage client-side caching as much as possible. So you should expect some endpoints to respond with a Cache-Control header with the cache max age. We highly recommend you to use them, when available, in order to optimize your application.

Pages

Here's an overview of the documentation pages we have available:

Auth
This page documents how to do authentication and authorization with the BrandIndex API (simple login or OAuth2), so that the client can use the user's protected data.
Company
This page documents some basic company information - mainly default values assigned to the user's company.
Filters
This page documents how to list the available filters in the API, so that you can use them later when retrieving timeline data.
Timeline
This page documents how to retrieve timeline data, both by single brands and by multiple brands at once.
Taxonomy
This page documents how to get the API data taxonomy, like how the brands are structured inside categories, specific data for a single brand and so on.

"What's an API?"

An API ("Application Program Interface") is a group of things that makes it easier to use a certain computer program (or set of programs): a programming specification, a protocol with which a API user can access a certain program (or set of programs), and the underlying program(s) that provide data and/or behavior. In other words, it's a programming interface through which another program can access the software application that is provided by this API.

One of the basic meanings of this is that an "API" is not something made for human users to use directly. It's not a user interface (UI) with buttons that the user can press and make something happen; rather than that, an API intends to be a software layer provided by an application which another application (normally running in another computer) will use. The reason for this is so that the API doesn't make any assumptions about the UI that is going to be used for accessing this application, hence leaving the UI decisions to however implements a piece of software that "consumes" this API.

"What about the BrandIndex API?"

Now let's translate this explanation into an example tangible to BrandIndex; the way we provide our product called "BrandIndex API" is through a webservice - that is, the application that contains the data which the user will be interested in lives in another computer (which we call "server" - because it serves the application for other computers to use). When another program, running in another computer, connects to this API server, in order to use its data and behavior, we call this other program "API client" (or, in the context of webservices, a "webservice consumer"). Just be double-clear, then: an "API client" is another computer program which uses the "API server".

As to the BrandIndex API itself, it was made to provide data that is already available through the BrandIndex UI, but, instead of targeted to humans, targeted to API clients which other developers will develop in order to display the data in whatever way they want or need. For example, if another company wants to access our data in order to display another kind of chart (composed by this data) in their own website, they can create an API client to be able to retrieve the data.

The data that we provide through the BrandIndex API, then, is provided under different formats, but as close as possible to the already-processed data that we use to generate the charts - rather than providing raw data (respondent-level data). This way, we can send along the scores, volumes and other pieces of information that we generate as a result from aggregating the data, matching the numbers displayed in the BrandIndex UI charts.

Usage limits

In order to provide reliable access for all users of the API service we need to ensure that no one API client makes too many requests or downloads too much data over a short period of time. Extraordinarily high levels of usage can negatively impact other users of the BrandIndex API and the BrandIndex portal as well.

Currently, we limit the API usage to a maximum of 10.0MiB of data (measured on the HTTP response raw body size, uncompressed) or 200 requests every 60 seconds, whichever comes first. Usage is calculated for the previous 600 seconds when a new request is received. Therefore the practical limit for a single subscriber’s API client is a few more bytes or a few more requests than the formal limits. A client that exceeds the limits will have to reduce the amount of data requested or wait a few minutes before making further requests in order to bring their average data usage or request frequency back under the limits.

Whenever your API client surpasses these limits and access is restricted, the API server responds with an HTTP 429 status code, providing the reason and a Retry-After response header as well. Your API client may use this header to determine the time in seconds it should wait to ensure that the next request does not get blocked again. The value in this header is currently fixed at 600, but it is better to rely on the value returned in the response header as this might change in the future.

Good luck using the API!