Getting started with the API

To get started with the API, it's important to understand first what expoze.io does and how it is typically used.

expoze.io is an attention prediction platform that can predict visual attention on and image or video in the form of a heatmap, with no research participants or hardware required. This can be used to predict what will be noticed in any visual setting - whether that be an advertisement, website, billboard or even a physical environment like a store or room. You can think of it as a bit like eye tracking, without the need for real eyes to track!

To help you understand how expoze.io is generally used, we have outlined the typical user flow below. This is not intended to be extensive developer documentation, but more to provide an outline of the typical steps to go through. You can visit this knowledge base article for detailed API developer documentation.

Typical user flow

1. Upload a media item

To be able to create a prediction, users need to upload their media. This can be an image (.jpeg, .png) or video (.mp4, .mov).

To upload a media item, you can use the following endpoint (base64 is also accepted). You will receive a mediaId which you can use in the next step when creating your heatmap.

POST - /developer/upload

2. Load job

Now the media item has been uploaded, it's time to predict visual attention! This can be done in the form of creating a heatmap. You will have the option to customise the settings of your heatmap, you can read more about this in custom heatmap settings and heatmap presets. To create a heatmap, use the following endpoint with your mediaId you received in the last step:

POST - /jobs.json

3. Get the heatmap results

After a few seconds, your heatmap should be generated. There are a couple of ways you can retrieve the heatmap:

Using the mediaId: GET - /media_objects/{mediaId}/jobs.json

Using the job ID: GET - /jobs/35717

The output should look something like this:

4. Set up your areas of interest (AOIs)

AOIs are essential so that users can quantify how much attention certain areas of their image are receiving. There are a few options when it comes to setting up AOI shapes - rectangle, circle, triangle and polygon. Take a look at the below image to get an idea of how an AOI is visualised in the expoze.io web application:

You can create an AOI using the below endpoint:

POST - /a_o_is.json

The body of the request will vary depending on if the shape is a polygon or not. You can find the different variations in your postman collection.

When the AOI has been created, you will receive an AOI id in the response body. You can use this ID to edit your AOI, in this request you can change the name and 'points' of the AOI which determine the size and location.

POST - /a_o_is/{aoi-id}

In the response, you will receive a score value - this is the % of overall attention in the image which falls within your defined area of interest.