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

GPS data can be retrieved in various ways:

Note

GPS data retrived 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

Retreive 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 latitude. 34.91901649
lat The GPS longitude. 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 longitude. 32.17380468
lon The GPS latitude. 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 retreived 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 clients 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 longitude. 32.17380468
lon The GPS latitude. 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 longitude. 32.17380468
lon The GPS latitude. 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 of 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 longitude. 32.17380468
lon The GPS latitude. 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 -> offest 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.