Retrieve GPS data

GPS coordinates are collected every 5 seconds of a trip and sent to the cloud. The device must be in motion for new GPS coordinates to be sent to the cloud.

Based on these coordinates, the following information is stored in the cloud:

longitude
latitude
speed - when a device is online. The units of measurement vary depending on the API call

Note

The AI-12 dashcam returns longitude and latitude parameters to the 8th decimal point. The AI-14 dashcam returns these parameters to the 15th decimal point.

GPS data can be retrieved in various ways:

From a time range
From a trip
From an event
From the live location of a device
From the live locations of all devices in an organization

Note

GPS data retrieved from a time range or from a trip include an accuracy parameter. This tells you the difference between your devices actual location and its recorded location, in meters.

The accuracy depends on the GPS signal strength. When indoors, such as going through a tunnel or in a parking garage, the signal strength is weaker and the GPS data is less accurate.

A normal accuracy range for the AI-12 dashcam is between 3 and 10 meters.

From a time range

Retrieve the GPS data of a device from a specific time range with the GET /devices/{imei}/gps call. You can use this data to show the trip on a map.

Note

Webhook GPS data can also be used to accomplish this, but the information will be stored on the clients listener server.

Copy

Copied

curl --request GET 'https://api-prod.surfsight.net/v2/devices/{imei}/gps?start={start}&end={end}'
--header 'Authorization: Bearer {token}'

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	Filter by a start date and time, in ISO 8601 format.	2020-01-01T14:48:00.000Z
end	Filter by an end date and time, in ISO 8601 format.	2020-01-01T14:50:00.000Z

The returned response:

Copy

Copied

"data": [
    {
        "lon": 34.91896378,
        "lat": 32.17378071,
        "alt": 64.47662353515625,
        "time": 1634720553,
        "speed": 0.479999989271164,
        "accuracy": 3.216
    },
    {
        "lon": 34.91901649,
        "lat": 32.17380468,
        "alt": 58.77685546875,
        "time": 1634720541,
        "speed": 2.0299999713897705,
        "accuracy": 3.216
    },
]

Parameter	Description	Example
lon	The GPS longitude.	34.91901649
lat	The GPS latitude.	32.17380468
alt	The GPS altitude.	58.77685546875
time	The time, in Unix time.	1634720541
speed	The speed, in meters per second.	2.0299999713897705
accuracy	The accuracy of the GPS, in meters.	3.216

From a trip

Retrieve all the trips of a device during a specific time range with the GET devices/{imei}/trips call. You can use the start and end data returned from that response in the GET /devices/{imei}/gps call to show complete trips on a map.

Copy

Copied

curl --request GET 'https://api-prod.surfsight.net/v2/devices/{imei}/trips?start={start}&end={end}'
--header 'Authorization: Bearer {token}'

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	Filter by a start date and time, in ISO 8601 format.	2020-01-01T14:48:00.000Z
end	Filter by an end date and time, in ISO 8601 format.	2020-01-01T14:50:00.000Z

The returned response:

Copy

Copied

"data": {
        "start": {
            "lat": 32.17444508,
            "lon": 34.91930652,
            "time": 1639216678,
            "subscriptionId": 11978058081,
            "speed": 0,
            "accuracy": 11.792
        },
        "end": {
            "lat": 32.09437866,
            "lon": 34.77290326,
            "time": 1639218738,
            "subscriptionId": 11978435298,
            "speed": 1.919999957084656,
            "accuracy": 4.288
        },
        "duration": 2060,
        "minSpeed": 0,
        "maxSpeed": 35.02000045776367,
        "distance": 15.523432137029667,
        "eventsCount": 2,
        "virtualEventsCount": 0
    }

Parameter	Description	Example
lat	The GPS latitude.	32.17380468
lon	The GPS longitude.	34.91901649
time	The time, in Unix time.	1634720541
subscriptionId	The ID of the GPS point.	11978435298
speed	The speed, in meters per second.	2.0299999713897705
accuracy	The accuracy of the GPS, in meters.	3.216
duration	The trip duration, in seconds.	2060
minSpeed	The minimum speed during the trip, in meters per second.	0
maxSpeed	The maximum speed during the trip, in meters per second.	35.02000045776367
distance	The trip distance, in kilometers.	15.523432137029667
eventsCount	The number of events in the trip.	2
virtualEventsCount	The number of virtual events in the trip.	0

From an event

Show the location of an event on a map. Each event contains GPS data in its metadata. Event data can be retrieved with the GET devices/{imei}/events call. Use the GPS coordinates in the event data to present the event on a map.

Note

Webhook GPS data can also be used to accomplish this, but the information will be stored on the client's listener server.

Copy

Copied

curl --request GET 'https://api-prod.surfsight.net/v2/devices/{imei}/events'
--header 'Authorization: Bearer {token}'

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

The returned response:

Copy

Copied

{
  "id": 247195231,
  "eventType": "sharpTurnLeft",
  "metadata": "[{\"x\":-3.2773001194000244,\"y\":-0.11410520225763321,\"z\":0.00830205250531435,\"time\":1641366374403,\"speed\":19.479999542236328},{\"x\":-3.338042736053467,\"y\":-0.09864255785942078,\"z\":0.017623519524931908,\"time\":1641366374502,\"speed\":19.479999542236328}...........],
  "lat": 32.98581475,
  "lon": 35.14809606,
  "speed": 47.124000549316406,
  "status": "new",
  "severity": 3,
  "eventComments": [],
  "time": "2022-01-05T07:06:19.000Z",
  "files": [
    {
      "cameraId": 1,
      "fileId": "1641366379",
      "fileType": "video"
    },
    {
      "cameraId": 2,
      "fileId": "1641366379",
      "fileType": "video"
    }
  ]
}

Parameter	Description	Example
id	The ID assigned to the event.	247195231
eventType	The type of event.	sharpTurnLeft
metadata -> x	The g-force x-axis value, in meters per second squared.	-3.2773001194000244
metadata -> y	The g-force y-axis value, in meters per second squared.	-0.11410520225763321
metadata -> z	The g-force z-axis value, in meters per second squared.	0.00830205250531435
metadata -> time	The time, in Unix format.	1641366374403
metadata -> speed	The speed, in meters per second.	19.479999542236328
lat	The GPS latitude.	32.17380468
lon	The GPS longitude.	34.91901649
speed	The speed, in kilometers per hour.	47.124000549316406
status	The review status of the event.	new
severity	The severity of the event. 1 - high; 2 - medium; 3 - low.	3
eventComments	Comments added to the event.
time	The time, in UTC format.	2022-01-05T07:06:19.000Z
files -> cameraId	The ID of the camera. 1 - road-facing camera; 2 - in-cabin-facing camera; 50+ - auxiliary cameras.	1
files -> fileId	The ID of the file.	1641366379
files -> fileType	The file type.	video

From the live location of a device

Provide the live location of a device on a map with the GET organizations/{orgId}/devices call. In the query parameters, include the device IMEI:

Copy

Copied

curl --request GET 'https://api-prod.surfsight.net/v2/organizations/{orgId}/devices?{imei}'
--header 'Authorization: Bearer {token}'

Parameter	Description	Example
orgId	The ID of the organization. Obtain this from GET /organizations.	3528
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

The returned response:

Copy

Copied

"data": {
        "imei": "357660101035475",
        "organizationId": 3528,
        "name": "Harry's truck",
        "groupId": 12,
        "status": "online",
        "iccid": "899720201470164615",
        "cameras": [
            {
                "cameraId": 1,
                "name": "Front Camera"
            },
            {
                "cameraId": 2,
                "name": "Rear Camera"
            }
        ],
        "lat": 32.17372413,
        "lon": 34.91889546,
        "alt": 65.38604736328125,
        "speed": 35.0299999713897705
        "lastSeenOnline": "2021-12-14T09:37:57.000Z",
        "firmwareVersion": "3.10.6",
        "deviceModel": "AI-12"
    }
}

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
organizationId	The ID of the organization	3528
name	The name assigned to the device in the POST /organizations/{orgId}/devices call.	Harry's truck
groupId	The ID of the group with which the device is associated.	12
status	The device connection status. When online, the device is fully functional. When in standby, the device is connected to the cloud, but live streaming is not available and speed data are not returned. When offline, the device is not connected to the cloud.	online
iccid	The number of the device's SIM card.	899720201470164615
cameras -> cameraId	The ID of the camera. 1 - road-facing camera, 2 - in-cabin-facing camera, 50+ - auxiliary cameras.	1
cameras -> name	The name assigned to the camera.
lat	The GPS latitude.	32.17380468
lon	The GPS longitude.	34.91901649
alt	The GPS altitude.	58.77685546875
speed	The speed, in kilometers per hour.	35.0299999713897705
lastSeenOnline	The most recent time that the device connected to the cloud, in ISO 8601 format. Updated every five minutes.	2021-12-14T09:37:57.000Z
firmwareVersion	The firmware version of the device.	3.10.6
deviceModel	The model of the device.	AI-12

You can set up polling to continuously show the live location of a device.

From the live locations of all devices in an organization

Provide the current location of all the devices in an organization. Use the GET organizations/{orgId}/devices call to retrieve all the metadata of the devices in an organization.

Copy

Copied

curl --request GET 'https://api-prod.surfsight.net/v2/organizations/{orgId}/devices'
--header 'Authorization: Bearer {token}'

Parameter	Description	Example
orgId	The ID of the organization. Obtain this from GET /organizations.	3528

The returned response:

Copy

Copied

    "data": {
    [
        {
            "imei": "357660101035384",
            "name": "357660101035384",
            "groupId": -1,
            "vehicleType": "Private",
            "cameras": [
                {
                    "cameraId": 1,
                    "name": "Front Camera"
                },
                {
                    "cameraId": 2,
                    "name": "Rear Camera"
                },
                {
                    "cameraId": 51,
                    "name": null
                },
                {
                    "cameraId": 52,
                    "name": null
                },
                {
                    "cameraId": 53,
                    "name": null
                }
            ],
            "iccid": "unknown",
            "status": "standby",
            "lat": 32.65840507,
            "lon": 35.09935336,
            "alt": 128.27801513671875,
            "lastSeenOnline": "2021-12-14T10:03:50.898Z",
            "firmwareVersion": "3.10.4",
            "deviceModel": "AI-12"
        },
        {
            "imei": "357660101034296",
            "name": "Old unit",
            "groupId": -1,
            "vehicleType": "Private",
            "cameras": [
                {
                    "cameraId": 1,
                    "name": "Front Camera"
                },
                {
                    "cameraId": 2,
                    "name": "Rear Camera"
                },
                {
                    "cameraId": 51,
                    "name": null
                },
                {
                    "cameraId": 52,
                    "name": null
                },
                {
                    "cameraId": 53,
                    "name": null
                }
            ],
            "iccid": "unknown",
            "status": "offline",
            "lastSeenOnline": "2021-11-16T16:20:26.914Z",
            "firmwareVersion": "3.10.5",
            "deviceModel": "AI-12"
        }
    ],
    "metadata": {
        "count": 2,
        "limit": 0,
        "offset": 0
    },
    "requestId": "e74b898b-6a17-46aa-9b0a-4bfdfa45925b"
}

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
organizationId	The ID of the organization	3528
name	The name assigned to the device in the POST /organizations/{orgId}/devices call.	Harry's truck
groupId	The ID of the group with which the device is associated.	12
vehicleType	The type of vehicle associated with the device. The type of vehicle affects the sensitivity of the device's motion sensor. Private is the most sensitive to movements, and trailer is the least sensitive.	Private
status	The device connection status. When online, the device is fully functional. When in standby, the device is connected to the cloud, but live streaming is not available and speed data are not returned. When offline, the device is not connected to the cloud.	online
iccid	The number of the device's SIM card.	899720201470164615
cameras -> cameraId	The ID of the camera. 1 - road-facing camera, 2 - in-cabin-facing camera, 50+ - auxiliary cameras.	1
cameras -> name	The name assigned to the camera.
lat	The GPS latitude.	32.17380468
lon	The GPS longitude.	34.91901649
alt	The GPS altitude.	58.77685546875
speed	The speed, in kilometers per hour.	35.0299999713897705
lastSeenOnline	The most recent time that the device connected to the cloud, in ISO 8601 format. Updated every five minutes.	2021-12-14T09:37:57.000Z
firmwareVersion	The firmware version of the device.	3.10.6
deviceModel	The model of the device.	AI-12
metadata -> count	The total number of pagination results received.	2
metadata -> limit	The maximum number of pagination results to receive.	0
metadata -> offset	The number of results to skip over before receiving pagination results.	0

You can set up polling to continuously show the live location of a device.