1- API Overview
InReality’s measurement subscription packages (Awareness, Audience, or Engagement) allow the end user to see the data via formulas setup in InReality’s Analytics Portal via Dashboard, Funnel or At a Glance Cards. In addition the data is also available in several other formats via API that allow end users to input the data into their own BI tool for manipulation and visualization. This guide is an overview of the API options available.
InReality offers an extensive data extraction API (Application Programming Interface) for our customers and partners to access your venue metrics from InReality's platform and integrate into your own Business Intelligence (BI) platform or Visualization tools.
Our API calls are RESTful API and JSON objects as the data input and output formats. JSON is a lightweight data-interchange format. Our platform uses the RESTful rules by using GET, POST, PUT, DELETE for data exchange. The API requests require HTTPS connections and authentication with API keys.
2- Data Types: Aggregated and Non-Aggregated
When data is aggregated, it is combined or compiled into data summaries. When data is non-aggregated, you view each transaction. API Data can be extracted in both of these formats.
Using InReality's Analytics package, when a visitor is identified, they are given a Unique ID#. If the person returns at a later time, they may be given the same Unique ID#. In this scenario, if the person visits multiple times, the Dwell Time values are combined, in Aggregated Data.
Aggregated Data is grouped or aggregated on a daily basis. This means that if a Unique ID is seen multiple times, the sum of their dwell times (Presence and Demographics) is presented in a single event record.
Non-Aggregated Data is not grouped or aggregated at all. This means that if a Unique ID is seen multiple times, each unique event will be shown as a new record, but will retain the same Unique ID.
3- Aggregated Data API
Data aggregation is the process where raw data is gathered and expressed in a summary form for statistical analysis. For example, raw data can be aggregated over a given time period to provide statistics such as average, minimum, maximum, sum, and count. After the data is aggregated and written to a view or report, you can analyze the aggregated data to gain insights about particular resources or resource groups.
For metrics based upon Awareness (Demographic Data), Audience (Traffic & Presence) or Engagement (Interaction Event), an API is available for each data source. Included in each event are:
- Traffic: A unique event record is available for each traffic occasion
- Record ID
- Record Version
- Store Name
- Store ID
- InReality Store ID
- Date/Time
- Sensor Code
- Presence: A unique event record is available for each presence event
- Record ID
- Record Version
- Store Name
- Store ID
- InReality Store ID
- Date Time
- Sensor Code
- Unique ID
- Dwell Time
- Demographics: A unique identifier is available for each unique face seen
- Record ID
- Record Version
- Store Name
- Store ID
- InReality Store ID
- Date Time
- Sensor Code
- Unique ID
- Dwell Time
- Mood
- Proximity
- Age
- Age Group
- Gender
- Exclusion Tag
- Interaction: A unique identifier is available for each unique interaction
- Record ID
- Record Version
- Store Name
- Store ID
- InReality Store ID
- Date Time
- Sensor Code
- Unique ID
- Input Type
- Duration
In the Aggregated Data API, the data is grouped/aggregated on a daily basis. This means that if a Unique ID is seen multiple times, the sum of their dwell times (for Presence or Demographics) is presented in a single event record.
For Demographics, this means that if a person is seen multiple times during the day and assigned the same unique ID, their cumulative dwell time will be shown as 1 event with the Date/Time listed as the time of the beginning of their first event.
For Presence, this API will operate so that if a person/body is seen multiple times in the frame of view, their cumulative dwell time in the larger zone (or smaller zone) will be shown as 1 event within the event record. If a person moves between a larger zone and a smaller zone multiple times and retains the same Unique ID, there will be an event record for each zone that is the sum of the dwell time in each zone with a count of 1 for each zone. Anyone that leaves the frame of view and comes back in will create a new unique event.
4- Non-Aggregated Data API
Non-Aggregated Data is not grouped or aggregated at all. This format reveals underlying trends, patterns, or insights that would not be observable in aggregated data sets.
For metrics based upon Awareness (Demographic Data), Audience (Traffic & Presence) or Engagement (Interaction Event), Non-Aggregated Data API is also available for each data source. Included in each event from each data source are:
- Traffic: A unique event record is available for each traffic occasion
- Record ID
- Record Version
- Store Name
- Store ID
- InReality Store ID
- Date/Time
- Sensor Code
- Presence: A unique event record is available for each presence event
- Record ID
- Record Version
- Store Name
- Store ID
- InReality Store ID
- Date Time
- Sensor Code
- Unique ID
- Dwell Time
- Demographics: A unique identifier is available for each unique face seen
- Record ID
- Record Version
- Store Name
- Store ID
- InReality Store ID
- Date Time
- Sensor Code
- Unique ID
- Dwell Time
- Mood
- Proximity
- Age
- Age Group
- Gender
- Exclusion Tag
This data is not grouped/aggregated at all. This means that if a Unique ID is seen multiple times, each unique event will be shown as a new record but will retain the same Unique ID.
For Demographics, this means that if a person is seen multiple times during the day and assigned the same unique ID, there would be a unique record for each event but would show the same Unique ID. This will allow end users to count total records and manage multiple events by the same Unique ID as they see fit.
For Presence, this API will operate the same as the Aggregated API, meaning that if a person/body is seen multiple times in the frame of view, their cumulative dwell time in the larger zone (or smaller zone) will be shown as 1 event within the event record. If a person moves between a larger zone and a smaller zone multiple times and retains the same Unique ID, there will be an event record for each zone that is the sum of the dwell time in each zone with a count of 1 for each zone. Anyone that leaves the frame of view and comes back in will create a new unique event.
5- User Defined Formula API
The User Defined Formula API sums the count of events for Traffic, Presence, Demographics and Engagement into hourly totals, with each event record representing the count of events in that hour period. This feature is for channel partners who have their own portal or dashboard and will use the raw data to drive that dashboard.
- Traffic:
- Formula ID
- Store ID
- Area of Interest ID
- Record Date/Time
- Count
- Presence:
- Formula ID
- Store ID
- Area of Interest ID
- Record Date/Time
- Count
- Total Dwell Time
- Average Dwell Time
- Demographics
- Formula ID
- Store ID
- Area of Interest ID
- Record Date/Time (Beginning hour & date)
- Total Dwell Time
- Average Dwell Time
- Mood
- Age
- Age Group
- Gender
6- Third Party Data Import / Export
Importing data with the Import Wizard allows you to map the fields which are most important. The fields can also be given custom names. Data can be easily imported through the User Interface, and through the Restful API.
Exporting of data is provided via the Restful API, and CSV files with headers. Different types of data such as Sensor event logs and Correlated may be exported.
7- Technical Documentation
InReality offers two different Message Broker API protocols. Developer User Guides are available for both.
The first uses Node.JS which is an open-source, cross-platform, runtime environment. We use AMQP TCP connection and JSON objects as the data input and output formats. JSON is a lightweight data-interchange format. The application should have permission to establish an AMQP TCP connection.
The second uses JavaScript, along with a WebSocket connection and JSON objects as the data input and output formats. JSON is a lightweight data-interchange format. The application should have permissions to establish a websocket connection.
An InReality representative can provide this technical documentation once an NDA is executed by all parties involved.