TKK CSV Injector — Referentie voor bestandsformaat
1. Toepassingsgebied
Deze specificatie definieert het CSV-formaat dat wordt geaccepteerd door de Trakkit CSV track-importer.
Dit document is bedoeld voor ontwikkelaars en bevat technische informatie en specificaties. Het is niet bedoeld als primaire bron van documentatie. Voor een introductie en algemene gebruiksrichtlijnen, raadpleeg de TKK – Trakkit General Documentation.
Een CSV-bestand vertegenwoordigt een reeks GPS-posities die gekoppeld zijn aan een bestaande boat. Elk record moet een tijdstempel, latitude en longitude bevatten. Navigatiegegevens zoals snelheid, koers, wind, heading, diepte, temperatuur, druk, motortoerental (RPM) en elevatie kunnen optioneel worden meegegeven.
2. Bestandsvereisten
| Eigenschap | Vereiste |
|---|---|
| Bestandstype | Tekst CSV |
| Encoding | UTF-8 of UTF-8 met BOM |
| Veldscheidingsteken | komma (,), puntkomma (;), pipe (|), of TAB |
| Header | Vereist |
| Minimum aantal kolommen | 3 |
| Verplichte velden | DATE, LAT, LON |
| Decimaalscheidingsteken | . of , |
Het bestand MOET minstens één record bevatten met een geldige datum, latitude en longitude.
3. Minimaal geldig bestand
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
Headernamen zijn niet hoofdlettergevoelig.
Vóór het matchen van een header doet de importer het volgende:
- verwijdert leidende en afsluitende witruimte;
- zet de naam om naar lowercase;
- verwijdert spaties;
- verwijdert underscores (
_); - verwijdert koppeltekens (
-).
De volgende headernamen zijn daarom equivalent:
SpeedOverGround
speed over ground
speed_over_ground
speed-over-ground
SPEEDOVERGROUND
Elke canonieke veldnaam is op zichzelf ook een geldige header.
5. Verplichte velden
DATE
Tijdstempel van de GPS-positie (UTC impliciet als er geen tijdzone is)
Geaccepteerde headernamen:
DATE
date
ts
timestamp
datetime
time
horaire
utc
LAT
Latitude.
Geaccepteerde headernamen:
LAT
lat
latitude
LON
Longitude.
Geaccepteerde headernamen:
LON
lon
long
longitude
lng
Een record wordt afgewezen als DATE, LAT, of LON niet kan worden geparsed.
6. Optionele navigatievelden
| Veld | Beschrijving | Geaccepteerde aliassen |
|---|---|---|
AWS |
Schijnbare windsnelheid | aws, apparentwindspeed, windspeedapparent |
AWA |
Schijnbare windhoek | awa, apparentwindangle, windangleapparent |
COG |
Course Over Ground | cog, courseoverground |
SOG |
Speed Over Ground | sog, speedoverground |
TWA |
Ware windhoek | twa, truewindangle |
TWS |
Ware windsnelheid | tws, truewindspeed |
MTW |
Watertemperatuur | mtw, watertemperature, tempwater, seatemperature |
MTA |
Luchttemperatuur | mta, airtemperature, tempair |
HDG |
Heading | hdg, heading |
AWSMIN |
Minimale schijnbare windsnelheid | awsmin, minaws, apparentwindspeedmin |
AWSMAX |
Maximale schijnbare windsnelheid | awsmax, maxaws, apparentwindspeedmax |
TWD |
Ware windrichting | twd, truewinddirection |
CTW |
Course Through Water | ctw, coursethroughwater |
MBP |
Barometrische druk | mbp, baropressure, pressure, pressurebaro, barometer |
STW |
Speed Through Water | stw, speedthroughwater |
DEPTH |
Waterdiepte | depth, profondeur, waterdepth, sonde |
RPM |
Motortoerental (RPM) | rpm, enginerpm, motorrpm |
ELEV |
Elevatie / altitude | elev, elevation, alt, altitude |
Alle hierboven vermelde velden worden geaccepteerd voor database-import.
Een lege of niet-numerieke optionele waarde wordt opgeslagen als een null-waarde en zorgt er niet voor dat het record wordt afgewezen.
7. Datum- en tijdformaten
DATE accepteert Unix-tijdstempels, ISO 8601-tijdstempels en verschillende conventionele datumformaten.
7.1 Unix-tijdstempel
Unix epoch in seconden:
1786694400
Unix epoch in milliseconden:
1786694400000
Numerieke tijdstempelstrings met 10 tot 17 cijfers worden herkend.
Waarden groter dan 10^12 worden behandeld als milliseconden.
7.2 ISO 8601
Voorbeelden:
2026-08-14T08:00:00Z
2026-08-14T08:00:00+00:00
2026-08-14T10:00:00+02:00
Waarden met tijdzone worden omgezet naar UTC.
ISO-tijdstempels zonder tijdzone-informatie worden geïnterpreteerd als UTC.
7.3 Conventionele formaten
De volgende formaten worden geaccepteerd:
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
Voorbeelden:
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
Conventionele datums zonder tijdzone-informatie worden geïnterpreteerd als UTC.
8. Numerieke waarden
Numerieke velden accepteren een punt of een komma als decimaalscheidingsteken, maar dit MAG NIET conflicteren met het veldscheidingsteken.
Velden kunnen worden beschermd met dubbele aanhalingstekens (").
Geldige voorbeelden:
5.7
5,7
"43.69520"
43,69520
9. Coördinaten
Latitude en longitude moeten numeriek zijn.
Negatieve coördinaten worden geaccepteerd.
Voorbeeld:
DATE;LAT;LON
2026-08-14 08:00:00;32.37000;-64.64000
Coördinaten worden vóór opslag afgerond op vijf decimalen.
Voorbeeld:
43.6952347 -> 43.69523
7.2846128 -> 7.28461
10. Ontbrekende waarden
Verplichte velden moeten geldige waarden bevatten.
Ongeldig:
DATE;LAT;LON
2026-08-14 08:00:00;43.69520;
Optionele velden mogen leeg zijn:
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;;
Een ongeldige optionele numerieke waarde wordt behandeld als null.
11. Onbekende kolommen
Kolommen die niet matchen met een herkend veld of alias worden genegeerd voor import van navigatiegegevens.
Voorbeeld:
DATE;LAT;LON;COMMENT
2026-08-14 08:00:00;43.69520;7.28460;Departure
COMMENT is een onbekend veld.
Onbekende headernamen worden door de importer vastgelegd in:
fields_unknown.txt
Het bestand wordt onderhouden in dezelfde directory als de geïmporteerde CSV.
12. Bestandsvalidatie
Een bestand wordt alleen geaccepteerd als aan alle volgende voorwaarden is voldaan:
| Controle | Vereiste |
|---|---|
| Bestand bestaat | Vereist |
| Niet leeg | Vereist |
| Binaire detectie | Moet tekst zijn |
| Encoding | Moet leesbaar zijn als UTF-8 |
| Delimiter | komma (,), puntkomma (;), pipe (|), of TAB zonder conflict |
| Header | Minstens 3 kolommen |
| Verplichte velden | DATE, LAT, LON moeten resolven via canonieke namen of aliassen |
| Data | Minstens één record moet een geldige datum, latitude en longitude bevatten |
Een bestand dat geen enkel geldig GPS-record bevat, wordt afgewezen.
13. Recordvalidatie
Voor elk CSV-record:
| Voorwaarde | Resultaat |
|---|---|
| Geldige DATE + LAT + LON | Record geaccepteerd |
| Ongeldige DATE | Record afgewezen |
| Ongeldige LAT | Record afgewezen |
| Ongeldige LON | Record afgewezen |
| Ongeldig optioneel veld | Record geaccepteerd; veld opgeslagen als null |
| Leeg optioneel veld | Record geaccepteerd; veld opgeslagen als null |
14. Voorbeeldformaten
14.1 Alleen positie
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-snelheid en koers
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 en schijnbare 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 headernamen
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 Mensleesbare 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 Decimale komma's
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-tijdstempels
timestamp;lat;lon;sog;cog
1786694400;43.69520;7.28460;5.4;82
1786694700;43.70110;7.29130;5.7;85
14.8 Uitgebreide navigatiegegevens
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. Importbatch
Als minstens twee records worden geaccepteerd, maakt de importer een batch met:
name = Uploaded from CSV
De starttijd van de batch is de vroegste geaccepteerde recordtijdstempel.
De stoptijd van de batch is de laatste geaccepteerde recordtijdstempel.
Alle geaccepteerde records van één CSV-import delen dezelfde batch identifier.