Overview

Data points transferred from Composer and Player to the Intuiface Analytics Data Hub can be managed via a REST-based web API query. This web service supports count, export and delete operations. 

NOTE: Up to two minutes can elapse between the Log Event action in a running Intuiface experience and the availability of the associated data for retrieval via web services.

Endpoints for the Data Hub Web API

• Count
  When using the count parameter, the result will be a number representing the number of data points.
  • GET https://api.intuiface.com/analytics/v1/datapoints/count

• Export
  When using the export parameter, the result will be either an XML or JSON-formatted response containing the specified data points.

• • XML:  GET https://api.intuiface.com/analytics/v1/datapoints/export/xml
  • JSON: GET https://api.intuiface.com/analytics/v1/datapoints/export/json

• Delete
  When using the delete parameter, the result will be a number representing the number of deleted data points.

• • GET https://api.intuiface.com/analytics/v1/datapoints/delete

Authentication

Authentication is accomplished by using the header x-api-key. Its value must be an Intuiface credential key with an Analytics scope. This key specifies the Intuiface account and permits access to the data points collected by that account.

To find or create your credential key, head to the Credential Keys page for your Intuiface account. For details, see our article about credential key creation and management.

Request parameters

Required parameters:

• startDate=YYYY-MM-DDThh:mm:ss.000Z: a start date, using ISO 8601 date & time representation
• endDate=YYYY-MM-DDThh:mm:ss.000Z: an end date using ISO 8601 date & time representation

Optional Parameters:

• includeSa: (case-sensitive) set it to 'true' to include data points for all Secondary Accounts; it is 'false' by default 
  • if includeSa is false, other optional parameters are available:
    • deviceName: only retrieve data points for the specified device. Can be combined with the experienceName and/or eventName parameters. Only available if not using the 'includeSa' parameter. You'll get an error if specifying an experience when using the 'includeSa' parameter.
    • experienceName: only retrieve data points for the specified experience. Can be combined with the deviceName and/or eventName parameters. Only available if not using the 'includeSa' parameter. You'll get an error if specifying an experience when using the 'includeSa' parameter.
    • eventName: only retrieve data points for the specified event. Can be combined with the deviceName and/or experienceName parameters. Only available if not using the 'includeSa' parameter. You'll get an error when specifying an event using the 'includeSa' parameter.
• buffer: (only available for the export endpoint) it defaults to 'true', meaning requested data is first placed in a buffer, and retrieval pulls data from that buffer. If the network connection fails for any reason, data retrieval will pull data from the buffer once a connection is reestablished rather than restart retrieval from the beginning.
  This buffer is emptied 30 minutes after it is created. If you intend to make more than one data request in less than a 30-minute time span, set 'buffer' to false.

Example Web Service Requests

NOTE: Credential keys are limited to three simultaneous requests. If this limit is reached, requests are locked for 15 minutes.

• Example for counting data points

  • : curl --location 'https://api.intuiface.com/analytics/v1/datapoints/export/json?startDate=2023-11-20T00%3A00%3A00.000Z&endDate=2023-11-20T23%3A59%3A59.999Z' --header 'x-api-key: [YourApiKey]'

  • Example Response (Json):  {"count": 24}

• Example for exporting data points in the JSON format:
  The following curl request will get all data points collected from all devices and for all Primary Account experiences (no Secondary Accounts) run on those devices between 28-June-2024 and 28-July-2024. The result will be in JSON format.
  curl --header "x-api-key:<Intuiface credential key>" "https://analytics.intuiface.com/analytics/export/json?startDate=2024-06-28T14:00:00.000Z&endDate=2024-07-28T14:00:00.000Z"
• More complex request for exporting data points in the XML format:
  The following curl request will get you the data points for a specific device, for all experiences run on this device for the Primary and all of its Secondary Accounts after October 28 2024 at 2pm UTC. Data in the request buffer will be ignored.
  curl --header "x-api-key:<Intuiface credential key>" "https://analytics.intuiface.com/analytics/export/xml?deviceName={YourDeviceName}&startDate=2024-10-28T14:00:00.000Z&includeSa=true&buffer=false"
• Example for deleting datapoints via API request
  • curl --location 'https://api.intuiface.com/analytics/v1/datapoints/delete?startDate=2024-11-20T00:00:00.000Z&endDate=2024-11-20T23:59:59.999Z' 
--header 'x-api-key: [YourApiKey]
  • Example response (JSON): {"deletedCount": 244}

We recommend you use a tool like Postman to build and test your request.