How to use Lytx Conceal Service API

The Conceal Service blurs license plates and the faces of drivers, passengers, and passersby on event media files that are stored in the cloud. This helps reseller partners and clients minimize access to personal information.

Information that is being concealed:

  • Vehicles’ license plates
  • Faces of drivers
  • Faces of passersby
  • Faces of passengers inside the vehicle
Note

The service scans each frame and blurs the identified objects (faces or license plates.) If no object is detected, the frame remains unaltered.
An object’s size, variation and orientation as well as its location in the image and lighting may affect the performance of the service.

This cloud service is available through an API and can be applied to media that has been generated from all lenses, including the road- and in-cab facing lenses of the dash cam and auxiliary cameras.

As part of the initial release, the Lytx Conceal Service is available only for video clips and snapshots captured as triggered events. This service is only available to reseller partners connected to the EU cloud.

As in all events, these media files include audio unless it is configured to be OFF using the /devices/{imei}/device-config request.

Important

All events are saved on the cloud for 31 days unless configured otherwise using /organizations request

The rest of this guide shows you how to use the Surfsight API to retrieve a concealed media file, with the following steps:

  1. Authenticate yourself.
  2. Get list of available events media files.
  3. Integrate the Conceal service

1. Authenticate yourself

Authenticate yourself before making any calls with the Surfsight API. For more details on authentication, see our authentication overview.

2. Get list of available events media files

Request the available events from the cloud using the GET /devices/{imei}/events with a query parameter relevant to the time range:

curl --request POST https://api-prod.surfsight.net/v2/devices/{imei}/events?start=2021-10-15T09:00:00.000Z&end=2021-10-20T20:59:59.999Z'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer {token}'

The returned response:

Copy
Copied
        {
  "id": 190537212,
  "eventType": "sharpTurnRight",
  "lat": 32.48636437,
  "lon": 34.95381069,
  "speed": 49.319999313354494,
  "time": "2021-10-16T13:33:00.000Z",
  "files": [
    {
      "cameraId": 1,
      "fileId": "1634391180",
      "fileType": "video",
      "mediaAvailable":true,
      "blurredMediaAvailable":true

    },
    {
      "cameraId": 2,
      "fileId": "1634391180",
      "fileType": "video",
      "mediaAvailable":true,
      "blurredMediaAvailable":true

    }
  ]
}

3. Integrate the Conceal service

Request the concealed media file with the GET /devices/{imei}/event-file-link API call.

curl --request GET https://api-prod.surfsight.net/v2/devices/{imei}/event-file-link?fileId=1634391180&cameraId=1&fileType=video&conceal=true
--header 'Content-Type: application/json'
--header 'Authorization: Bearer {token}'

The following query parameters must be entered. fileId, cameraId, and fileType can be received through the /devices/{imei}/events API response. For more information see Download media event.

Component Description Example
fileId Time in UNIX of the event 1634391180
cameraId Lens number of the device 1
fileType Media type of the event Video
conceal Parameter to blur images True
Note
  • Real-time API calls, which involve accessing the blurred video as soon as possible after the event is created, typically take an average of 5-7 seconds for a 10-second video, depending on factors such as the video’s duration, network availability and the volume of real-time requests.
  • The service incorporates a backlog mechanism wherein each uploaded media file of an event is blurred and saved. This mechanism ensures quick access to the blurred media in future requests.

Returned response:

Copy
Copied
{
    "data": {
        "url": "https://surfsight-stage2-device-media.s3.us-east-2.amazonaws.com/3e8e66ba-7a9f-421b-a1c5-49d4909db1c1/357660102684628/deid_backlog_strict_blur_snapshot_357660102684628_1701757654_1.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA5LF37XL5YZUESL5T%2F20231206%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20231206T100933Z&X-Amz-Expires=345600&X-Amz-Security-Token=IQoJb3JpZ2luX2VjECIaCXVzLWVhc3QtMiJGMEQCIEKFZHAsM41JMA462oqmdKS4%2FIjUHBsEL3rd24Jy7yvxAiBVoxpVamiQANi78QTqGVS98LCjhU%2BS5TyK%2FQ7oWonBaCrEBQiL%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAEaDDkxNzM2OTc2NDYwMyIMjx2caf3p44mcBM1HKpgF69yKQdFEg45SvGvA%2FQ4%2BGs21FJWmRoGJd9Xm8mld0KjANmO%2FgvLC5b1IcV3BaqiPSoadC9mRGovSTQ9UsxSY2DLRTQAU9Oh8rSdATsG5BeKkTB3urBWwq1kuOzG6u6OCfVEFCmYevF0wcHh1sPUdUEyVf30F%2Bq1W9jea%2B6A10DUSpsmzwSKbxTJmNW%2BqrcSb%2FY6E6IcuY%2FyCCo506pzKV4AScGTC0fYfYeWdCOaGe5y7dAKfcDOGAXhjEER01mQ6RNnSvB6k74%2B2KGukWwV6kOBvaBjEb3q6AohYMfpNvRTjCH5Y1QQ0okSz0fmu7ivn6%2Fc9FjziREoV%2BjI2GKpWlt%2Be2eqJysrZzWtlvC8Wq2PzQ2G4bG2Yr1x43%2BVIf1pjwesrCS3H0If1kVzUCxjiQmtQzlerYkDFSwl9EIDDsITsJtHxIrXMU4SICD9vYPz95SjpQd3AdVLSB3OOx%2BDRhsT%2FnSoGGXtBxzgi6XmVnon52C4Bj3U1mz584EfZx99TwkL2vGyZ%2FWjJ3n4wm1m7yh8RbJEdWg3Ke6GTogKiyVXbRi6w7unoTLvpbzEAYLxeMWLjwabKFVTDJzFnan9Z2%2FttIV29SNDnhCuH9nS5QdCQssF2vxyAYCYe3Qp%2FvnjICvMihnjfSIb8MCb6so0aVcvqvSGp24sK8KPW%2FdSEFuo8IlaGWZ0GVSFZXfY%2FKltz9R3YsF%2FIFvFgeGfN2ubn6mdn6blEB%2FjP%2FWrN5XKfS8YJLa86Hm5ADzYJq4Iz5po9AsKFG4KH34gp4DplgP7M8HLh18hmae4dulT9Yw8FI8GVRhMEc78%2BOMLeZNr1kG8jIJJIjLmgGsCdu1oAv7%2B5UIQK56o7fl44ObWBd6KgJhvrOSa4KB4ZizDQjMGrBjqyAZqo0dtEO1%2FUhihkXW7ZgnTyXPwg%2FUM%2BUMJJAfwlO7bMsKVcM4GIZgKOxl20tTr0FqwjFH2Fr2kiOu0O%2BLs7wTJj75b8rUUYC%2Fc523pe2ZAykaA61bFIE%2BOBfiVMpg1gl6xmlMMA%2FhZvCVv9P3O9B1SixRCrdF1ON%2BzRqbuTJTwB7HA8fB7t0Lk1RE%2FzQ8%2FssCqn5f94khC1m7ZXptW%2B6AgTK9NLNfSc07NSu8R%2F4oNmKa8%3D&X-Amz-Signature=69d2e6339c00a88cf75ff14e34513b07b40c59cec94557dd0bf0d2b69f4ea246&X-Amz-SignedHeaders=host"
    },
    "requestId": "8c04842d-a133-456c-8879-cf582279f565"
}
Note

The link to the media file will expire after 4 days and a new request must be made in order to access the media file again.

Notice

Variations in the appearance of the blurring in the Lytx Conceal Service may result from such conditions as: poor visibility due to weather, lighting, camera placement, misalignment, obstructions, or orientation; images of persons that are beyond the second row and partially obscured; and fluctuations between clear and blurred imagery from the road-facing lens, which gives the appearance of flickering.