TKK CSV Injector — Référence du format de fichier

1. Périmètre

Cette spécification définit le format CSV accepté par l’importeur Trakkit de Track CSV.

Ce document est destiné aux développeurs et contient des informations et des spécifications techniques. Il n’a pas vocation à constituer la source principale de documentation. Pour une introduction et des indications d’utilisation générales, veuillez vous référer à la TKK – Trakkit General Documentation.

Un fichier CSV représente une séquence de positions GPS associées à un bateau existant. Chaque enregistrement doit contenir un horodatage, une latitude et une longitude. Des données de navigation telles que la vitesse, le cap, le vent, le heading, la profondeur, la température, la pression, le régime moteur (RPM) et l’altitude peuvent être fournies en option.


2. Exigences du fichier

Propriété Exigence
Type de fichier CSV texte
Encodage UTF-8 ou UTF-8 avec BOM
Séparateur de champs virgule (,), point-virgule (;), barre verticale (|), ou TAB
En-tête Requis
Colonnes minimales 3
Champs requis DATE, LAT, LON
Séparateur décimal . ou ,

Le fichier DOIT contenir au moins un enregistrement avec une date, une latitude et une longitude valides.


3. Fichier minimal valide

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. Correspondance des en-têtes

Les noms d’en-tête ne sont pas sensibles à la casse.

Avant de faire correspondre un en-tête, l’importeur :

  1. supprime les espaces en début et fin ;
  2. convertit le nom en minuscules ;
  3. supprime les espaces ;
  4. supprime les underscores (_) ;
  5. supprime les tirets (-).

Les noms d’en-tête suivants sont donc équivalents :

SpeedOverGround
speed over ground
speed_over_ground
speed-over-ground
SPEEDOVERGROUND

Chaque nom de champ canonique est lui-même un en-tête valide.


5. Champs requis

DATE

Horodatage de la position GPS (UTC implicite en l’absence de fuseau horaire)

Noms d’en-tête acceptés :

DATE
date
ts
timestamp
datetime
time
horaire
utc

LAT

Latitude.

Noms d’en-tête acceptés :

LAT
lat
latitude

LON

Longitude.

Noms d’en-tête acceptés :

LON
lon
long
longitude
lng

Un enregistrement est rejeté si DATE, LAT ou LON ne peut pas être analysé.


6. Champs de navigation optionnels

Champ Description Alias acceptés
AWS Vitesse du vent apparent aws, apparentwindspeed, windspeedapparent
AWA Angle du vent apparent awa, apparentwindangle, windangleapparent
COG Route sur le fond (COG) cog, courseoverground
SOG Vitesse sur le fond (SOG) sog, speedoverground
TWA Angle du vent réel twa, truewindangle
TWS Vitesse du vent réel tws, truewindspeed
MTW Température de l’eau mtw, watertemperature, tempwater, seatemperature
MTA Température de l’air mta, airtemperature, tempair
HDG Heading hdg, heading
AWSMIN Vitesse minimale du vent apparent awsmin, minaws, apparentwindspeedmin
AWSMAX Vitesse maximale du vent apparent awsmax, maxaws, apparentwindspeedmax
TWD Direction du vent réel twd, truewinddirection
CTW Route dans l’eau (CTW) ctw, coursethroughwater
MBP Pression barométrique mbp, baropressure, pressure, pressurebaro, barometer
STW Vitesse dans l’eau (STW) stw, speedthroughwater
DEPTH Profondeur d’eau depth, profondeur, waterdepth, sonde
RPM Régime moteur (RPM) rpm, enginerpm, motorrpm
ELEV Élévation / altitude elev, elevation, alt, altitude

Tous les champs listés ci-dessus sont acceptés pour l’import en base de données.

Une valeur optionnelle vide ou non numérique est stockée comme une valeur nulle et n’entraîne pas le rejet de l’enregistrement.


7. Formats de date et d’heure

DATE accepte les timestamps Unix, les timestamps ISO 8601 et plusieurs formats de date conventionnels.

7.1 Timestamp Unix

Époque Unix en secondes :

1786694400

Époque Unix en millisecondes :

1786694400000

Les chaînes de timestamp numériques contenant 10 à 17 chiffres sont reconnues.

Les valeurs supérieures à 10^12 sont traitées comme des millisecondes.

7.2 ISO 8601

Exemples :

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

Les valeurs avec fuseau horaire sont converties en UTC.

Les timestamps ISO sans information de fuseau horaire sont interprétés comme UTC.

7.3 Formats conventionnels

Les formats suivants sont acceptés :

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

Exemples :

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

Les dates conventionnelles sans information de fuseau horaire sont interprétées comme UTC.


8. Valeurs numériques

Les champs numériques acceptent soit un point soit une virgule comme séparateur décimal, mais cela ne DOIT PAS entrer en conflit avec le séparateur de champs.

Les champs peuvent être protégés par des guillemets doubles (").

Exemples valides :

5.7
5,7
"43.69520"
43,69520

9. Coordonnées

La latitude et la longitude doivent être numériques.

Les coordonnées négatives sont acceptées.

Exemple :

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

Les coordonnées sont arrondies à cinq décimales avant stockage.

Exemple :

43.6952347 -> 43.69523
7.2846128  -> 7.28461

10. Valeurs manquantes

Les champs requis doivent contenir des valeurs valides.

Invalide :

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

Les champs optionnels peuvent être vides :

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

Une valeur numérique optionnelle invalide est traitée comme nulle.


11. Colonnes inconnues

Les colonnes qui ne correspondent pas à un champ ou à un alias reconnu sont ignorées pour l’import des données de navigation.

Exemple :

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

COMMENT est un champ inconnu.

Les noms d’en-tête inconnus sont enregistrés par l’importeur dans :

fields_unknown.txt

Le fichier est conservé dans le même répertoire que le CSV importé.


12. Validation du fichier

Un fichier est accepté uniquement si toutes les conditions suivantes sont satisfaites :

Vérification Exigence
Le fichier existe Requis
Non vide Requis
Détection binaire Doit être du texte
Encodage Doit pouvoir être lu en UTF-8
Délimiteur virgule (,), point-virgule (;), barre verticale (|), ou TAB sans conflit
En-tête Au moins 3 colonnes
Champs requis DATE, LAT, LON doivent se résoudre via des noms canoniques ou des alias
Data Au moins un enregistrement doit contenir une date, une latitude et une longitude valides

Un fichier ne contenant aucun enregistrement GPS valide est rejeté.


13. Validation des enregistrements

Pour chaque enregistrement CSV :

Condition Résultat
DATE + LAT + LON valides Enregistrement accepté
DATE invalide Enregistrement rejeté
LAT invalide Enregistrement rejeté
LON invalide Enregistrement rejeté
Champ optionnel invalide Enregistrement accepté ; champ stocké à null
Champ optionnel vide Enregistrement accepté ; champ stocké à null

14. Exemples de formats

14.1 Position uniquement

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 Vitesse et cap GPS

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 et vent apparent

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 Noms d’en-tête longs

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 Variantes d’en-tête lisibles par un humain

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 Virgules décimales

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 Timestamps Unix

timestamp;lat;lon;sog;cog
1786694400;43.69520;7.28460;5.4;82
1786694700;43.70110;7.29130;5.7;85

14.8 Données de navigation étendues

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. Lot d’import

Si au moins deux enregistrements sont acceptés, l’importeur crée un lot avec :

name = Uploaded from CSV

L’heure de début du lot est l’horodatage le plus ancien parmi les enregistrements acceptés.

L’heure de fin du lot est l’horodatage le plus récent parmi les enregistrements acceptés.

Tous les enregistrements acceptés d’un même import CSV partagent le même identifiant de lot.