Moods | DCM User Manual

Retrieves list of mood measurements. DCM_API_DOMAIN will be provided by DCM.

Understanding Mood data

In general the API endpoints use standard metric units and scales, such as average number of people detected per square meter for density. Mood data however uses a custom scale.

The AI model gives each face a score between 0 and 1. With 1 being most negative, 0 being most positive and 0.5 being completely neutral. The dashboard uses the same scale in its graphs, but for useability and clarity translates these scores into an overall ‘Positive’, ‘Neutral’ or ‘Negative’ rating.
The API will return the raw AI model scores. As with all endpoints - the data is aggregated for privacy reasons as DCM does not track individuals, or provide data that may allow tracking when combined with other data - such as individual lat/long co-ordinates.

For each sample period it averages the score of all faces detected and returns a timestamp and average mood score. Sample period is configurable for each camera, with a minimum frequency of five seconds.

Request

URL: <DCM_API_DOMAIN>/moods

Method: POST

Format: application/json

Headers: The following headers must be included in the request

Parameter	Type	Mandatory	Description
content-type	string	Yes	Indicates the media type of the resource. Use `application/json`.
authorization Token	string	Yes	Token to be used when accessing the API. Value is `Bearer <token>`. Use token from Token. `audience` is `ext-api-mood`.

Parameter

Type

Mandatory

Description

content-type

string

Yes

Indicates the media type of the resource. Use application/json.

authorization Token

string

Yes

Token to be used when accessing the API. Value is Bearer <token>.

Use token from Token. audience is ext-api-mood.

Parameters:

Parameter	Type	Mandatory	Default Value	Description
query	string	Yes		A structured string that allows calling application to specify the data that it wants to retrieve.

Query structure:

query {
    moods(calibrationId: <calibration_id>, startTime: <start_time>, endTime: <end_time>, timezone: <timezone>) {
        <data_fields_to_be_retrieved>
    }
}

Query Parameters: The following are parameters to be included in the request.

Parameter	Type	Mandatory	Default Value	Description
calibration_id	Integer	Yes		The Id of the calibration (camera view) that data is required for. The list of valid calibrations can be retrieved with the /calibrations endpoint.
start_time	DateTime	No	Now - 1 hour	The start of the period data is requested for. Time periods are in UTC format and can be a maximum of a 24 hour period.
end_time	DateTime	No	Now	The end of the period data is requested for
timezone	String	No	Etc/UTC	The timezone name for parameters and data (IANA timezone database specification). See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for the list of timezone names. Eg. “Australia/Sydney”, “Europe/London”
data_fields_to_be_retrieved	string	Yes		The fields to be retrieved. Allowed values: timestamp mood

Notes:

If end_time is more than 1 day after start_time an error will occur and no data will be retrieved.

Response

Format: application/json

Parameters:

Name	Type	Description
errors.message	String	Description of the error if one occurred.
data.moods	List	List of mood measurements.

Examples

Retrieve all mood fields

const getMoods = async function(token, calibrationId, startTime, endTime) {
    return new Promise(function(res, rej) {
        const url =  '<DCM_API_DOMAIN>/moods';
        const method = 'POST';
        const headers = { 
            'content-type': 'application/json',
            'authorizationToken': `Bearer ${token}`
        };
        const query = `query {
            moods(calibrationId: "${calibrationId}", startTime: ${startTime}, endTime: ${endTime}) {
                timestamp
                mood
            }
        }`;
        const options = {
            url: url,
            method: method,
            headers: headers,
            body: JSON.stringify({ query })
        };

        const req = request(options, function callback(error, response, body) {
            body = JSON.parse(body);
            ...
            ...
        });
    });
}

Response

{
  "data": {
    "moods": [
      {
        "timestamp": "2021-12-08T06:02:50.476Z",
        "mood": 0.5
      }
    ]
  }
}