Download event media

When an event is triggered, it can be uploaded in video format, as a snapshot, or with no media at all. You can configure these settings in the event settings API.

Important

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

These media files play audio unless otherwise configured to be OFF using the /devices/{imei}/device-config request.

The rest of this guide shows you how to use the Surfsight API, to quickly perform the following steps:

Authenticate yourself.
Get list of available events media files.
Download event media.

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 GET 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"
                },
                {
                    "cameraId": 2,
                    "fileId": "1634391180",
                    "fileType": "video"
                }
            ]
        }

3. Download event media

Request links to download event media files stored on the cloud by using the GET https://api-prod.surfsight.net/v2/devices/{imei}/event-file-link API request.

The required query parameters, cameraId, fileId and fileType, must be entered as they were received by /devices/{imei}/events API response:

Component	Description	Required	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.	Required	357660101000198
`fileId`	Time in UNIX of the event.	Required	1634391180
`cameraId`	The ID of the in-cab or road-facing lens, or any paired auxiliary camera. 1 - road-facing lens, 2 - in-cab lens, 50+ - auxiliary cameras. Use 0 for all cameras, or with the `cameraIds` parameter for a list of specific cameras.	Required	1
`fileType`	Media type of the event	Required	Video
`cameraIds`	A list of the camera IDs, separated by a comma. This may include the in-cab or road-facing lens, or any paired auxiliary camera: 1 - road-facing lens, 2 - in-cab lens, 50+ - auxiliary cameras. The list of cameras can be used only if cameraId=0 is provided.	Optional	1,2,51,52
`conceal`	Parameter to blur images. For more information, see Integrate the Conceal service	Optional	true

Request for one event media file:

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

Returned response:

{
    "data": {
        "url": "https://surfsight-organizations-production.s3.amazonaws.com/2a4837d8-5d88-43dd-94f4-894e81b476f4/{imei}/{imei}_1634391180_1.mp4?
        X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAUAWC3GNZKY7KPK35%2F20211020%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20211020T064221Z&X
        -Amz-Expires=345600&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEEMaCXVzLWVhc3QtMiJHMEUCIQCgFlK1Uu4hH8NRf04jgJeF94RXr0J3nJNr3oRm0e6vdgIgOWu9O0kNXMsqmnYX
        %2FKGjRJD4tx........................
    },
    "requestId": "45778fc6-ad06-400e-af6b-0dbcd8546002"
}

Request for multiple event media files:

curl --request GET v2/devices/{{imei}}/event-file-link?fileId={{eventFileId}}&cameraId=0&fileType={{eventFileType}}&cameraIds=1,2,3,4,5
--header 'Content-Type: application/json'
--header 'Authorization: Bearer {token}'

Returned response:

{ 
  "data": {
    "url": "[{\'camera_id1\': \'www.somepath1.url\'},{\'camera_id2\': \'www.somepath2.url\'}]"
  }
}

Note

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