Create and download a virtual event

Virtual events are third-party events that telematics service providers (TSPs) generate from a device's recordings. If TSP or other (non-Surfsight) devices create events without video or images, they can use the timestamps from those events in the API call and retrieve video or snapshots of the third-party event. Virtual events can also be created by a user from any existing trip media.

Prerequisite

These calls must be made by a user who is defined as a partner in the system and therefore, has credentials to access the Partner Portal. If you do not have these partner credentials, reach out to your technical account manager to receive the proper credentials.

The rest of this guide shows you how to use the Surfsight API to create and download a virtual event, following these steps:

Authenticate yourself.
Create a virtual event.
Retrieve the event details.
Download the event media.

Note

For more information about the different API requests, take a look at our reference guide.

1. Authenticate yourself

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

2. Create a virtual event

Create a virtual event with the POST /devices/{imei}/virtual-event call.

Copy

Copied

    curl --request POST https://api-prod.surfsight.net/v2/devices/{imei}/virtual-event
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer {token}'
    --data-raw '{

                  "time": "2020-01-01T14:48:00.000Z",
                  "mediaType": "video",
                  "durationSeconds": 10,
                  "quality": "standard",
                  "cameraId": 1,
                  "metadata": "customString"
                  
                }'

Parameter	Description	Example
imei	The IMEI of the device. The IMEI number can be found on a sticker on the device itself or on the back of the device box.	357660101000198
time	The time of the virtual event, in ISO 8601 format	2020-01-01T14:48:00.000Z
mediaType	The type of media to upload as part of the event. The options include video and snapshot.	video
durationSeconds	The length of the video, in seconds. Only applies to the video mediaType.	10
quality	The quality of of the video. Only applies to the video mediaType. The options include standard and high: standard quality - recordings play in 1 frame per second. high quality - recordings play in the frames per second configured in your data profile. .	standard
cameraId	The ID of the dashcam lens or relevant paired aux cam. 1 - road-facing camera, 2 - in-cabin-facing camera, 50+ - auxiliary cameras. To work with all lenses for the virtual event request, remove the entire parameter line.	1
metadata	Additional text about the virtual event, as a string.	customString

3. Retrieve the event details

Retrieve the virtual event details with the GET /devices/{imei}/events call.

Copy

Copied

    curl --request POST https://api-prod.surfsight.net/v2/devices/{imei}/events
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer {token}'
    --data-raw '{

                  "start": 2020-01-01T14:48:00.000Z,
                  "end": 2020-01-01T14:50:00.000Z
                  
                }'

Parameter	Description	Example
imei	The IMEI of the device. The IMEI number can be found on a sticker on the device itself or on the back of the device box.	357660101000198
start	The start time of the events you want to retrieve, in ISO 8601 format.	2020-01-01T14:48:00.000Z
end	The end time of the events you want to retrieve, in ISO 8601 format	2020-01-01T14:50:00.000Z

Note

Make sure the time of the virtual event is within the range of the start and end parameters.

Get the virtual event cameraId, fileType, and fileId from the returned response:

Copy

Copied

{
  "data": [
    {
      "id": 3,
      "eventType": "virtual event",
      "time": "2020-01-01T14:48:00.000Z",
      "lat": 32.0598671,
      "lon": 34.7827316,
      "speed": 22.51,
      "accuracy": 4,
      "status": "new",
      "severity": 1,
      "eventComments": [
        {
          "id": 125,
          "comment": "string",
          "createdByAudienceName": "surfsight",
          "createdById": 625,
          "createdBy": {
            "id": 32,
            "email": "email@email.com"
          },
          "createdAt": "2019-08-24T14:15:22Z"
        }
      ],
      "files": [
        {
          "cameraId": 1,
          "fileType": "video",
          "fileId": "1595077872"
        }
      ],
      "geoFenceId": 3,
      "metadata": "{type:'Test event', scope:'Some test scope'}"
    }
  ]
}

4. Download the event media

Retrieve the virtual event file link with the GET /devices/{imei}/event-file-link call.

Copy

Copied

    curl --request POST https://api-prod.surfsight.net/v2/devices/{imei}/event-file-link
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer {token}'
    --data-raw '{

                  "fileId": "1595077872",
                  "fileType": "video",
                  "cameraType": 1
                  
                }'

The returned response contains the URL to download the event media:

Copy

Copied

{
  "data": {
    "url": "https://sample.s3.aws.com/123/123.mp4?access_key=1234"
  }
}