TKK CSV Injector — Dateiformat-Referenz

1. Geltungsbereich

Diese Spezifikation definiert das CSV-Format, das vom Trakkit CSV Track-Importer akzeptiert wird.

Dieses Dokument richtet sich an Entwickler und enthält technische Informationen und Spezifikationen. Es ist nicht als primäre Dokumentationsquelle gedacht. Für eine Einführung und allgemeine Hinweise zur Nutzung siehe bitte die TKK – Trakkit General Documentation.

Eine CSV-Datei stellt eine Sequenz von GPS-Positionen dar, die einem bestehenden Boat zugeordnet sind. Jeder Datensatz muss einen Zeitstempel, Breitengrad und Längengrad enthalten. Navigations-Data wie Geschwindigkeit, Kurs, Wind, Steuerkurs, Tiefe, Temperatur, Druck, Motordrehzahl und Höhe können optional mitgeliefert werden.


2. Dateianforderungen

Eigenschaft Anforderung
Dateityp Text-CSV
Kodierung UTF-8 oder UTF-8 mit BOM
Feldtrenner Komma (,), Semikolon (;), Pipe (|) oder TAB
Header Erforderlich
Minimale Spaltenanzahl 3
Pflichtfelder DATE, LAT, LON
Dezimaltrennzeichen . oder ,

Die Datei MUSS mindestens einen Datensatz mit gültigem Datum, Breitengrad und Längengrad enthalten.


3. Minimal gültige Datei

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-Abgleich

Header-Namen sind nicht case-sensitiv.

Vor dem Abgleich eines Headers führt der Importer Folgendes aus:

  1. entfernt führende und nachfolgende Whitespaces;
  2. konvertiert den Namen in Kleinbuchstaben;
  3. entfernt Leerzeichen;
  4. entfernt Unterstriche (_);
  5. entfernt Bindestriche (-).

Die folgenden Header-Namen sind daher äquivalent:

SpeedOverGround
speed over ground
speed_over_ground
speed-over-ground
SPEEDOVERGROUND

Jeder kanonische Feldname ist selbst ein gültiger Header.


5. Pflichtfelder

DATE

Zeitstempel der GPS-Position (UTC implizit, wenn keine Zeitzone angegeben ist)

Akzeptierte Header-Namen:

DATE
date
ts
timestamp
datetime
time
horaire
utc

LAT

Breitengrad.

Akzeptierte Header-Namen:

LAT
lat
latitude

LON

Längengrad.

Akzeptierte Header-Namen:

LON
lon
long
longitude
lng

Ein Datensatz wird abgelehnt, wenn DATE, LAT oder LON nicht geparst werden können.


6. Optionale Navigationsfelder

Feld Beschreibung Akzeptierte Aliase
AWS Scheinbare Windgeschwindigkeit aws, apparentwindspeed, windspeedapparent
AWA Scheinbarer Windwinkel awa, apparentwindangle, windangleapparent
COG Kurs über Grund cog, courseoverground
SOG Geschwindigkeit über Grund sog, speedoverground
TWA Wahrer Windwinkel twa, truewindangle
TWS Wahre Windgeschwindigkeit tws, truewindspeed
MTW Wassertemperatur mtw, watertemperature, tempwater, seatemperature
MTA Lufttemperatur mta, airtemperature, tempair
HDG Steuerkurs hdg, heading
AWSMIN Minimale scheinbare Windgeschwindigkeit awsmin, minaws, apparentwindspeedmin
AWSMAX Maximale scheinbare Windgeschwindigkeit awsmax, maxaws, apparentwindspeedmax
TWD Wahre Windrichtung twd, truewinddirection
CTW Kurs durchs Wasser ctw, coursethroughwater
MBP Barometrischer Druck mbp, baropressure, pressure, pressurebaro, barometer
STW Geschwindigkeit durchs Wasser stw, speedthroughwater
DEPTH Wassertiefe depth, profondeur, waterdepth, sonde
RPM Motordrehzahl (RPM) rpm, enginerpm, motorrpm
ELEV Höhe / Altitude elev, elevation, alt, altitude

Alle oben aufgeführten Felder werden für den Datenbankimport akzeptiert.

Ein leerer oder nicht-numerischer optionaler Wert wird als Null-Wert gespeichert und führt nicht dazu, dass der Datensatz abgelehnt wird.


7. Datums- und Zeitformate

DATE akzeptiert Unix-Timestamps, ISO-8601-Timestamps und mehrere konventionelle Datumsformate.

7.1 Unix Timestamp

Unix-Epoche in Sekunden:

1786694400

Unix-Epoche in Millisekunden:

1786694400000

Numerische Timestamp-Strings mit 10 bis 17 Ziffern werden erkannt.

Werte größer als 10^12 werden als Millisekunden behandelt.

7.2 ISO 8601

Beispiele:

2026-08-14T08:00:00Z
2026-08-14T08:00:00+00:00
2026-08-14T10:00:00+02:00

Werte mit Zeitzone werden nach UTC konvertiert.

ISO-Timestamps ohne Zeitzoneninformation werden als UTC interpretiert.

7.3 Konventionelle Formate

Die folgenden Formate werden akzeptiert:

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

Beispiele:

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

Konventionelle Datumsangaben ohne Zeitzoneninformation werden als UTC interpretiert.


8. Numerische Werte

Numerische Felder akzeptieren entweder einen Punkt oder ein Komma als Dezimaltrennzeichen, dies darf jedoch NICHT mit dem Feldtrenner kollidieren.

Felder können durch doppelte Anführungszeichen (") geschützt werden.

Gültige Beispiele:

5.7
5,7
"43.69520"
43,69520

9. Koordinaten

Breitengrad und Längengrad müssen numerisch sein.

Negative Koordinaten werden akzeptiert.

Beispiel:

DATE;LAT;LON
2026-08-14 08:00:00;32.37000;-64.64000

Koordinaten werden vor dem Speichern auf fünf Dezimalstellen gerundet.

Beispiel:

43.6952347 -> 43.69523
7.2846128  -> 7.28461

10. Fehlende Werte

Pflichtfelder müssen gültige Werte enthalten.

Ungültig:

DATE;LAT;LON
2026-08-14 08:00:00;43.69520;

Optionale Felder dürfen leer sein:

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;;

Ein ungültiger optionaler numerischer Wert wird als null behandelt.


11. Unbekannte Spalten

Spalten, die keinem bekannten Feld oder Alias entsprechen, werden für den Import von Navigations-Data ignoriert.

Beispiel:

DATE;LAT;LON;COMMENT
2026-08-14 08:00:00;43.69520;7.28460;Departure

COMMENT ist ein unbekanntes Feld.

Unbekannte Header-Namen werden vom Importer protokolliert in:

fields_unknown.txt

Die Datei wird im selben Verzeichnis wie die importierte CSV gespeichert.


12. Dateivalidierung

Eine Datei wird nur akzeptiert, wenn alle folgenden Bedingungen erfüllt sind:

Prüfung Anforderung
Datei existiert Erforderlich
Nicht leer Erforderlich
Binär-Erkennung Muss Text sein
Kodierung Muss als UTF-8 lesbar sein
Trennzeichen Komma (,), Semikolon (;), Pipe (|) oder TAB ohne Konflikt
Header Mindestens 3 Spalten
Pflichtfelder DATE, LAT, LON müssen über kanonische Namen oder Aliase auflösbar sein
Data Mindestens ein Datensatz muss ein gültiges Datum, einen gültigen Breitengrad und einen gültigen Längengrad enthalten

Eine Datei ohne gültigen GPS-Datensatz wird abgelehnt.


13. Datensatzvalidierung

Für jeden CSV-Datensatz:

Bedingung Ergebnis
Gültiges DATE + LAT + LON Datensatz akzeptiert
Ungültiges DATE Datensatz abgelehnt
Ungültiges LAT Datensatz abgelehnt
Ungültiges LON Datensatz abgelehnt
Ungültiges optionales Feld Datensatz akzeptiert; Feld wird als null gespeichert
Leeres optionales Feld Datensatz akzeptiert; Feld wird als null gespeichert

14. Beispiel-Formate

14.1 Nur Position

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-Geschwindigkeit und Kurs

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 und scheinbarer 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 Lange Header-Namen

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 Menschenlesbare Header-Varianten

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 Dezimalkommas

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 Erweiterte Navigations-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

Wenn mindestens zwei Datensätze akzeptiert werden, erstellt der Importer einen Batch mit:

name = Uploaded from CSV

Die Batch-Startzeit ist der früheste Zeitstempel eines akzeptierten Datensatzes.

Die Batch-Stopzeit ist der späteste Zeitstempel eines akzeptierten Datensatzes.

Alle akzeptierten Datensätze aus einem CSV-Import teilen sich denselben Batch-Identifier.