TKK CSV Injector — File Format Reference
1. Scope
This specification defines the CSV format accepted by the Trakkit CSV track importer.
This document is intended for developers and contains technical information and specifications. It is not intended to serve as the primary source of documentation. For an introduction and general usage guidance, please refer to the TKK – Trakkit General Documentation.
A CSV file represents a sequence of GPS positions associated with an existing boat. Each record must contain a timestamp, latitude, and longitude. Navigation data such as speed, course, wind, heading, depth, temperature, pressure, engine RPM, and elevation may optionally be supplied.
2. File Requirements
| Property | Requirement |
|---|---|
| File type | Text CSV |
| Encoding | UTF-8 or UTF-8 with BOM |
| Field separator | comma (,), semicolon (;), pipe (|), or TAB |
| Header | Required |
| Minimum columns | 3 |
| Required fields | DATE, LAT, LON |
| Decimal separator | . or , |
The file MUST contain at least one record with a valid date, latitude, and longitude.
3. Minimal Valid File
DATE;LAT;LON
2026-08-14 08:00:00;43.69520;7.28460
2026-08-14 08:05:00;43.70110;7.29130
2026-08-14 08:10:00;43.70840;7.29880
4. Header Matching
Header names are case-insensitive.
Before matching a header, the importer:
- removes leading and trailing whitespace;
- converts the name to lowercase;
- removes spaces;
- removes underscores (
_); - removes hyphens (
-).
The following header names are therefore equivalent:
SpeedOverGround
speed over ground
speed_over_ground
speed-over-ground
SPEEDOVERGROUND
Each canonical field name is itself a valid header.
5. Required Fields
DATE
Timestamp of the GPS position (UTC implicit if no timezone)
Accepted header names:
DATE
date
ts
timestamp
datetime
time
horaire
utc
LAT
Latitude.
Accepted header names:
LAT
lat
latitude
LON
Longitude.
Accepted header names:
LON
lon
long
longitude
lng
A record is rejected if any of DATE, LAT, or LON cannot be parsed.
6. Optional Navigation Fields
| Field | Description | Accepted aliases |
|---|---|---|
AWS |
Apparent Wind Speed | aws, apparentwindspeed, windspeedapparent |
AWA |
Apparent Wind Angle | awa, apparentwindangle, windangleapparent |
COG |
Course Over Ground | cog, courseoverground |
SOG |
Speed Over Ground | sog, speedoverground |
TWA |
True Wind Angle | twa, truewindangle |
TWS |
True Wind Speed | tws, truewindspeed |
MTW |
Water Temperature | mtw, watertemperature, tempwater, seatemperature |
MTA |
Air Temperature | mta, airtemperature, tempair |
HDG |
Heading | hdg, heading |
AWSMIN |
Minimum Apparent Wind Speed | awsmin, minaws, apparentwindspeedmin |
AWSMAX |
Maximum Apparent Wind Speed | awsmax, maxaws, apparentwindspeedmax |
TWD |
True Wind Direction | twd, truewinddirection |
CTW |
Course Through Water | ctw, coursethroughwater |
MBP |
Barometric Pressure | mbp, baropressure, pressure, pressurebaro, barometer |
STW |
Speed Through Water | stw, speedthroughwater |
DEPTH |
Water Depth | depth, profondeur, waterdepth, sonde |
RPM |
Engine RPM | rpm, enginerpm, motorrpm |
ELEV |
Elevation / Altitude | elev, elevation, alt, altitude |
All fields listed above are accepted for database import.
An empty or non-numeric optional value is stored as a null value and does not cause the record to be rejected.
7. Date and Time Formats
DATE accepts Unix timestamps, ISO 8601 timestamps, and several conventional date formats.
7.1 Unix Timestamp
Unix epoch in seconds:
1786694400
Unix epoch in milliseconds:
1786694400000
Numeric timestamp strings containing 10 to 17 digits are recognized.
Values greater than 10^12 are treated as milliseconds.
7.2 ISO 8601
Examples:
2026-08-14T08:00:00Z
2026-08-14T08:00:00+00:00
2026-08-14T10:00:00+02:00
Timezone-aware values are converted to UTC.
ISO timestamps without timezone information are interpreted as UTC.
7.3 Conventional Formats
The following formats are accepted:
YYYY-MM-DD HH:MM:SS
YYYY-MM-DD HH:MM
YYYY/MM/DD HH:MM:SS
YYYY/MM/DD HH:MM
YYYY-MM-DD
YYYY/MM/DD
DD/MM/YYYY HH:MM:SS
DD/MM/YYYY HH:MM
DD/MM/YYYY
YYYYMMDD HHMMSS
YYYYMMDD HHMM
YYYYMMDD
Examples:
2026-08-14 10:35:12
2026-08-14 10:35
2026/08/14 10:35:12
14/08/2026 10:35:12
14/08/2026 10:35
14/08/2026
20260814 103512
20260814 1035
20260814
Conventional dates without timezone information are interpreted as UTC.
8. Numeric Values
Numeric fields accept either a dot or a comma as the decimal separator, but this MUST NOT conflict with the field separator.
Fields can be protected by double quotes (").
Valid examples:
5.7
5,7
"43.69520"
43,69520
9. Coordinates
Latitude and longitude must be numeric.
Negative coordinates are accepted.
Example:
DATE;LAT;LON
2026-08-14 08:00:00;32.37000;-64.64000
Coordinates are rounded to five decimal places before storage.
Example:
43.6952347 -> 43.69523
7.2846128 -> 7.28461
10. Missing Values
Required fields must contain valid values.
Invalid:
DATE;LAT;LON
2026-08-14 08:00:00;43.69520;
Optional fields may be empty:
DATE;LAT;LON;SOG;COG;AWS
2026-08-14 08:00:00;43.69520;7.28460;5.4;82;13.2
2026-08-14 08:05:00;43.70110;7.29130;;85;
2026-08-14 08:10:00;43.70840;7.29880;6.0;;
An invalid optional numeric value is treated as null.
11. Unknown Columns
Columns that do not match a recognized field or alias are ignored for navigation-data import.
Example:
DATE;LAT;LON;COMMENT
2026-08-14 08:00:00;43.69520;7.28460;Departure
COMMENT is an unknown field.
Unknown header names are recorded by the importer in:
fields_unknown.txt
The file is maintained in the same directory as the imported CSV.
12. File Validation
A file is accepted only if all of the following conditions are satisfied:
| Check | Requirement |
|---|---|
| File exists | Required |
| Non-empty | Required |
| Binary detection | Must be text |
| Encoding | Must be readable as UTF-8 |
| Delimiter | comma (,), semicolon (;), pipe (|), or TAB with no conflict |
| Header | At least 3 columns |
| Required fields | DATE, LAT, LON must resolve through canonical names or aliases |
| Data | At least one record must contain a valid date, latitude, and longitude |
A file containing no valid GPS record is rejected.
13. Record Validation
For each CSV record:
| Condition | Result |
|---|---|
| Valid DATE + LAT + LON | Record accepted |
| Invalid DATE | Record rejected |
| Invalid LAT | Record rejected |
| Invalid LON | Record rejected |
| Invalid optional field | Record accepted; field stored as null |
| Empty optional field | Record accepted; field stored as null |
14. Example Formats
14.1 Position Only
DATE;LAT;LON
2026-08-14 08:00:00;43.69520;7.28460
2026-08-14 08:05:00;43.70110;7.29130
14.2 GPS Speed and Course
DATE;LAT;LON;SOG;COG
2026-08-14 08:00:00;43.69520;7.28460;5.4;82
2026-08-14 08:05:00;43.70110;7.29130;5.7;85
14.3 GPS and Apparent Wind
DATE;LAT;LON;SOG;COG;AWS;AWA
2026-08-14 08:00:00;43.69520;7.28460;5.4;82;13.2;41
2026-08-14 08:05:00;43.70110;7.29130;5.7;85;14.1;38
14.4 Long Header Names
datetime;latitude;longitude;speedoverground;courseoverground;apparentwindspeed;apparentwindangle;truewindspeed;truewindangle;truewinddirection
2026-08-14T08:00:00Z;43.69520;7.28460;5.4;82;13.2;41;11.5;36;225
2026-08-14T08:05:00Z;43.70110;7.29130;5.7;85;14.1;38;12.0;34;228
14.5 Human-Readable Header Variants
Timestamp;Latitude;Longitude;Speed Over Ground;Course-Over-Ground;Apparent_Wind_Speed
2026-08-14 08:00:00;43.69520;7.28460;5.4;82;13.2
2026-08-14 08:05:00;43.70110;7.29130;5.7;85;14.1
14.6 Decimal Commas
DATE;LAT;LON;SOG;COG
14/08/2026 08:00;43,69520;7,28460;5,4;82
14/08/2026 08:05;43,70110;7,29130;5,7;85
14.7 Unix Timestamps
timestamp;lat;lon;sog;cog
1786694400;43.69520;7.28460;5.4;82
1786694700;43.70110;7.29130;5.7;85
14.8 Extended Navigation Data
DATE;LAT;LON;SOG;COG;STW;HDG;AWS;AWA;TWS;TWA;TWD;MTW;MTA;MBP;DEPTH;RPM;ELEV
2026-08-14 08:00:00;43.69520;7.28460;5.4;82;5.1;80;13.2;41;11.5;36;225;24.7;28.1;1013.2;18.4;1850;0
2026-08-14 08:05:00;43.70110;7.29130;5.7;85;5.4;83;14.1;38;12.0;34;228;24.8;28.2;1013.1;19.1;1870;0
16. Import Batch
If at least two records are accepted, the importer creates a batch with:
name = Uploaded from CSV
The batch start time is the earliest accepted record timestamp.
The batch stop time is the latest accepted record timestamp.
All accepted records from one CSV import share the same batch identifier.