CSV Format
The ztrack app allows you to export a track in CSV format. This page explains how to interpret the data in a CSV file.
CSV, which stands for Comma-Separated Values, is a common data storage format that is both easily machine readable, and easily human readable (well, almost easily human readable).
The zrack CSV format uses one record per line. Each record contains multiple fields, separated by commas, and each field holds a value. The first field of a record identifies the record type. The following record types exist.
- start - identifies the start of a track
- end - identifies the end of a track
- suspend - indicates that a track was suspended due to the background service being deleted
- resume - indicates that the track was resumed due to the background service being restarted
- point - contains data captured from the GNSS receiver
start Record
The start record idenfies the start of a track, and it must be the first record in a ztrack CSV file. A well-formed track has only one start record. The start record has from two to four fields:
| Field Name | M/O | Format | Interpretation |
|---|---|---|---|
| Record Type | Mandatory | The string start | Identifies this record as the start record |
| Timestamp | Mandatory | See Timestamp Values | Identifies the time at which ztrack started recording the track |
| Start Reason | Optional | See Reason Values | Identifies how the track was started. Older tracks (before about May 18, 2017) may not contain this field. |
| Creator | Optional | string | Identifies the application that created the track. Older tracks (before about June 10, 2017) may not contain this field. |
end Record
The end record identifies the end of a track, and ztrack ignores all data after an end record. The end record has from two to three fields.
| Field Name | M/O | Format | Interpretation |
|---|---|---|---|
| Record Type | Mandatory | The string end | Identifies this record as the end record |
| Timestamp | Mandatory | See Timestamp Values | Identifies the time at which ztrack stopped recording the track |
| End Reason | Optional | See Reason Values | Identifies how the track was ended. Older tracks (before about May 18, 2017) may not contain this value. |
suspend Record
The suspend record indicates that the Android operating system invoked the background service onDestroy callback while a recording was in progress. This can happen if memory presssure causes Android to stop or evict ztrack's background service in favor of a foreground activity. However, Android does not guarantee that it will invoke onDestroy when it kills a background service, so you may see resume records without seeing a suspend record.
| Field Name | M/O | Format | Interpretation |
|---|---|---|---|
| Record Type | Mandatory | The string suspend | Identifies this record as a suspend record |
| Timestamp | Mandatory | See Timestamp Values | Identifies the time at which Android invoked onDestroy |
resume Record
The resume record indicates that the Android operating system invoked the background service onCreate callback while a recording was in progress. This can occur when the Android operating system resumes a previously killed background service.
| Field Name | M/O | Format | Interpretation |
|---|---|---|---|
| Record Type | Mandatory | The string resume | Identifies this record as a resume record |
| Timestamp | Mandatory | See Timestamp Values | Identifies the time at which Android invoked onCreate |
point Record
The point record contains data captured from the GNSS receiver.
| Field Name | M/O | Format | Interpretation |
|---|---|---|---|
| Record Type | Mandatory | The string point | Identifies this record as a point record |
| Timestamp | Mandatory | See Timestamp Values | Identifies the time at which the GNSS receiver captured the data |
| Latitude | Mandatory | double-precision floating point | The captured latitude in the range -90 to +90 degrees |
| Longitude | Mandatory | double-precision, floating point | The captured longitude in the range -180 to +180 degrees |
| Altitude | Mandatory | double-precision, floating point | The captured WGS84 altitude in meters. May be zero if altitude was not captured. |
| Accuracy | Mandatory | single-precision, floating point | The captured accuracy in meters. May be zero if accuracy was not captured. |
| Speed | Mandatory | single-precision, floating point | The captured speed in meters per second. May be zero if speed was not captured. |
| Heading | Mandatory | single-precision, floating point | The captured heading in degrees (0 = north, 90 = east, 180 = south, 270 = west). May be zero if heading was not captured. |
Timestamp Values
A timestamp is a 64-bit signed integer number of milliseconds since January 1, 1970, midnight, UTC.
Reason Values
A reason value is one of the following strings.
- no_data - The reason is not specified (may appear if you import a track from MyTracks, and then export to CSV).
- service_destroyed - Recording stopped because the background service was destroyed. This reason is no longer used.
- gps_disabled - Recording stopped because the user disabled GPS.
- map_ui - Recording started (or stopped) because the user pressed the record (or stop) button on the map user interface.
- tracks_ui_deleted - Recording stopped because the user deleted the track from the track list user interface.
- notification - Recording started (or stopped) because the user invoked start (or stop) from the notification user interface.
- wear_client - Recording started (or stopped) because the user invoke start (or stop) from an Android Wear watch.
- enter_geofence - Recording stopped because the user entered a geofence.
- exit_geofence - Recording started because the user exited a geofence.
- ongoing - The recording is in progress (used internally, not stored in CSV files).