Consuming Newmetrix Metrics via API

Objective & Audience

The purpose of this document is to familiarize Newmetrix customers and partners with using the metrics available via API. It is intended for business and technical audiences interested in making Newmetrix metrics available in their Business Intelligence (BI) systems, Dashboards and other bespoke solutions.

This document is meant as a general “how-to”, please refer to these additional resources for a more in-depth overview:

API Documentation - a technical API reference
Newmetrix Metrics - a detailed list and descriptions of all available metric

Newmetrix Metrics

Metrics Available

Newmetrix provides the following metrics by product.

Safety Monitoring

Activity Metrics

GENERAL

Number of Uploads
Average number of uploads per day
Number of Active Users
Number of Unique Uploaders
By Integration: Number of Uploads
Tag Count

BY USER

Asset Count By User
Tag Count By User
Comment Count By User

Safety Metrics

WORK AT HEIGHT

Work at Height per 100 photos
Ladders Last (Ladder-to-Lift Ratio)

SLIP and TRIP

Housekeeping & Standing Water per 100
Housekeeping per 100 photos
Standing Water per 100 photos

PPE COMPLIANCE

Average PPE Compliance (overall)
Glasses Compliance
Gloves Compliance
Hard Hat Compliance
Hi-Vis Compliance

Safety Observations

Activity Metrics

GENERAL

Observations Count
Observation Count By Type (positive, risk)
Positive-to-Risk Observation Ratio
Observation Count by Hazard Category by type
Observation Count by Method of Identification by type
Great Catch Count
Great Catch Count By Type (positive, risk)

BY USER

Observation Creator With Observation Count
Observation Creator With Observation Count By Type (positive, risk)
Count of Unique Observation Creators
Count of Unique Observation Assignees

Safety Metrics

Average Risk Score (for risk observations)
Maximum Risk Score (for risk observations)
Observation Count by Risk Band (for risk observations)
Observation Count by Risk Score (for risk observations)
Great Catch Average Risk Score (for risk observations)

Workflow Metrics

Observation Count By Open vs Closed (for risk observations)
Average Days To Close Risk Observation (that was opened in a non-Closed state)
Open Observation Count By Status (for risk observations)
Average Days Open For Open Observations (for risk observations)
Average Days Open for Open Observations, By Risk Band (for risk observations)
Count of Past Due Observations (for risk observations)
Average Lateness (in days) For Past Due Observations (for risk observations)

Note: in addition to these aggregated metrics, Newmetrix provides access to raw Observations data in this API call.

Levels and Date Ranges

Where appropriate Newmetrix metrics are provided at these three levels

Per Project
Per Project Group (if configured)
Per Organization
Per User

With a few exceptions, the metrics are calculated for the following date ranges (or “buckets”)

1 day
7 days
30 days
60 days
90 days
All

Please refer to the API Documentation for the details on which metrics are supported at what level.

Metric Calculation

The metrics are calculated nightly and the fresh ones are available by 7am ET.

Accessing Metrics via API

Getting Started

To use metrics, you need an admin user account with access to at least one organization with project(s). To learn how to use the API, refer to API Documentation.

To get started with the API, you need to authenticate and receive a token. Here is a code snippet:

<span class="c5">POST <SMARTVID-ENVT>/api/v1/authenticate HTTP/1.1<br></span>Content-Type: application/json<br>Host: api-public.smartvid.io<br>Content-Length: 59<br>{<br>  "username" : "vgorsky@newmetrix.com",<br>  "password" : "************"<br>}

Use the token it returns for all subsequent API calls.

Using the Metrics API

To retrieve metric(s) use the following API call. Be sure to specify the desired metric, detail, level and time bucket:

<span class="c5">POST <SMARTVID-ENVT>/api/v1/authenticate HTTP/1.1<br></span>{<br>  "organizationId" : "3fd00465-c09e-4913-bbd6-16e23bb9adac",<br>  "metricRequests" : [ {<br>    "objectType" : "PROJECT_METRIC",<br>    "objectIds" : {<br>      "projectId" : "9a7bb22d-192a-4998-b923-ff21fba1a4a4",<br>      "useExternalProjectId" : false<br>     },<br>  "metricName" : "OBSERVATION_COUNT_BY_TYPE",<br>  "timeFrame" : "ALL_TIME",<br>  "details" : {<br>        "observationType" : [ "NEGATIVE" ]<br>   },<br>   "startDate" : 1585180800000,<br>   "endDate" : 1585267200000,<br>   "page" : 0,<br>   "pageSize" : 60<br>   } ]<br>  }

For more on this call please refer to the API Reference Documentation.