Usage


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.

Endpoints

The BrandIndex API follows the OpenAPI 3.0.2 standard, and has its endpoints exposed through Swagger UI, which is a JavaScript library that lets users experiment with APIs. Here's the link to our Swagger UI: https://api.brandindex.com/v1/

You can see the endpoints we expose, but in order to actually experiment with them through the Swagger UI you need to login: https://api.brandindex.com/v1/login

How to use

To reiterate, APIs as webservices are built with developers in mind, so it's expected that our API users have enough experience with consuming RESTful APIs. With that in mind, this section provides some guidelines on how to use the BrandIndex API.

Authentication

The very first thing that the API client you're building needs to do is to authenticate. This can be done in a number of different ways, and is explained here.

Having decided the authentication method you want to use, make sure all the requests you do the API are authenticated (except for the login one, if you choose for the "simple login" method).

Requests

As you'll notice in the Swagger UI, some endpoints use the GET HTTP method and others use POST. Even though some endpoints use POST, this doesn't mean they necessarily include new resources on the server; For example, the /analyses/execute POST endpoint only uses POST because it requires a request body with the analysis definition. This is a departure from the REST architecture style, but a necessary one since the GET method, by standard, doesn't accept a request body (which means servers and clients aren't required to implement the handling of a GET body - and many actually don't), so a client wouldn't be able to execute an analysis by its definition.

All our expected request bodies are expected in JSON format, and most of our response bodies are also in JSON format, except for a few export endpoints.