Data Ingestion

Input Specifications & TRK Mapping

CSV formatting rules, ZIP archive packaging, and complete .trk column mapping reference. Inbound packages require paired <filename>.zip (containing a single root .csv) and <filename>.trk files sharing the same base name (unless a default .trk is agreed with Egon), with zero-based column indexing and the column delimiter declared in [IN_SEP].

• Copy this page
  • View as Markdown
• Ask an AI assistant
  • Open in ChatGPT
  • Open in Claude
  • Open in Cursor

Packaging Schema

<filename>.zip

Compressed Data Archive

<filename>.csv

Single delimited table (pipe or semicolon separated)

Must match base name

<filename>.trk

Configuration Descriptor

[IN_ISO]Fixed ISO (ITA) or column index

[IN_SEP]Column delimiter

[IN_FUN]Function: NOR / GEO (includes NOR)

[IN_...]0-based index (-1 if unmapped)

Identical Base Names

The archive <filename>.zip, the internal <filename>.csv, and the descriptor <filename>.trk must share the exact case-sensitive base name, unless you use a default .trk agreed with Egon.

Single CSV per ZIP

The .zip archive must contain exactly one delimited text file. Nested folders or multiple files inside the zip are rejected.

Zero-Based Column Indexing

Field positions declared in the .trk file start from index 0 for the first column, 1 for the second column, and so on.

Matching Character Encoding

Ensure the text encoding configured via [IN_ENC] (e.g. UTF8 or cp1252) strictly matches your source CSV byte encoding.

Component	File Name	Location	Requirements
Data Archive	<filename>.zip	./input/	Standard ZIP archive containing only <filename>.csv.
Data File	<filename>.csv	Root of .zip	Delimited text file. Header row optional ([IN_INT]).
Descriptor	<filename>.trk	./input/	Plain text directive file defining country, delimiter, and column mapping.

Recurring Ingestion Jobs

The .trk stays in ./input/ after processing, so later runs with the same name only need the new <filename>.zip. If your CSV column layout is fixed, you can also agree a default .trk with Egon: it applies to every archive you upload, even with a different base name.

---

TRK Directives Reference

Directives are declared on individual lines using an uppercase bracketed identifier, whitespace padding, and the parameter value terminated by a semicolon (;). All column mapping directives use a zero-based column index, or -1; when the corresponding column is absent from your input file:

[DIRECTIVE]            value;

Directive	Parameter / Component	Allowed Values / Format	Description & CSV Formatting Rules	Example
[IN_ISO]	Country	3-letter ISO (ITA;) or column index (1;)	Destination country. Alphabetical ISO in single-country runs; 0-based column index in multi-country batches.	ITA; or 1;
[IN_FUN]	Operations	NOR;, GEO;	NOR; normalizes addresses. GEO; normalizes and also geocodes.	GEO;
[IN_SEP]	CSV Delimiter	|; (Pipe), $; (Semicolon)	Column separator character. Recommended: |;. Note: use $ to declare a semicolon in .trk.	|;
[IN_ENC]	Character Encoding	UTF8;, cp1252;, cp1250;	Source file byte encoding. Must match the input CSV encoding. Recommended: UTF8;.	UTF8;
[IN_INT]	Header Row	S; (Present), N; (No header row)	When S;, row 1 is skipped as column headers. When N;, processing starts from row 1.	S;
[IN_IDN]	Record Unique ID	Column index or -1;	Database primary key, preserved verbatim in its original column. Set to -1; if absent.	0;
[IN_STA]	Country Name	Column index or -1;	Source country name string (e.g. Italia). Set to -1; when unmapped.	1;
[IN_REG]	Region / State	Column index or -1;	Administrative territory / region. Set to -1; when unmapped.	2;
[IN_DPT]	Province Code	Column index or -1;	Two-letter official province abbreviation (Sigla). Set to -1; when unmapped.	3;
[IN_CNL]	Municipality / City	Column index or -1;	Official municipality name (Comune). Set to -1; when unmapped, for example when the full address is in [IN_STR].	4;
[IN_DS1]	Locality / Hamlet	Column index or -1;	Sub-district or hamlet (Frazione). Set to -1; when unmapped.	5;
[IN_ZIP]	Postal Code	Column index or -1;	Postal routing code (CAP / ZIP). Set to -1; when unmapped.	6;
[IN_DUG]	Street Type	Column index or -1;	Urban qualifier (Via, Corso, Viale, Rue, etc.). Set to -1; if unmapped.	7;
[IN_STR]	Street Name / Address	Column index or -1;	Street name. You can also map the full address here, including house number, postal code, and municipality.	8;
[IN_CIV]	House Number	Column index or -1;	Street building / house number (Civico). Set to -1; if unmapped.	9;
[IN_ESP]	Number Exponent	Column index or -1;	House number exponent or suffix (Esponente / Barrato). Set to -1; if unmapped.	10;
[IN_PRE]	Care Of / Interior	Column index or -1;	Building interior, care-of, or additional delivery info. Set to -1; if unmapped.	11;

Country Configuration Precedence & ISO Behavior

The declared country configuration in your batch job is authoritative and strictly dictates how [IN_ISO] is processed.

Single-Country Batches (Fixed ISO): When a specific destination country is declared (e.g. ITA, DEU, USA), [IN_ISO] in .trk is always alphabetical ([IN_ISO] ITA;) and applies to all rows uniformly. No CSV column is mapped to [IN_ISO]. Even if the input CSV contains an ISO or COD_ISO column, the batch strictly honors the declared configuration and leaves that column unmapped.

Multi-Country Batches (Multi-ISO Column): When the dataset contains records from multiple nations, [IN_ISO] is numeric (e.g. [IN_ISO] 1;), pointing to the 0-based column index where each row supplies its 3-letter ISO code. In this mode, [IN_ISO] cannot be -1; (a column mapping is mandatory).

---

Concrete Examples

Example 1: Sample CSV Records (customers_202610.csv)

ID|COUNTRY|REGION|PROVINCE|CITY|LOCALITY|ZIP|STREET_TYPE|STREET_NAME|NUMBER|EXPONENT|CARE_OF
1001|Italia|Lombardia|MI|Milano||20121|Via|Monte Napoleone|8|A|Studio Rossi
1002|Italia|Lazio|RM|Rom|||P.zza|di Spagana|1||
1003|Italia|Veneto|VR|Verona|San Massimo|37139|Corso|Milano|45|B|

Example 2: Single-Country Descriptor File (customers_202610.trk)

In single-country batches, [IN_ISO] is alphabetical (ITA;), and all 12 column directives are defined:

[IN_ISO]            ITA;
[IN_FUN]            GEO;
[IN_SEP]            |;
[IN_ENC]            UTF8;
[IN_INT]            S;
[IN_IDN]            0;
[IN_STA]            1;
[IN_REG]            2;
[IN_DPT]            3;
[IN_CNL]            4;
[IN_DS1]            5;
[IN_ZIP]            6;
[IN_DUG]            7;
[IN_STR]            8;
[IN_CIV]            9;
[IN_ESP]            10;
[IN_PRE]            11;

Example 3: Multi-Country Batch with Unmapped Directives (shipments_eu.trk)

In cross-border datasets, [IN_ISO] is numeric (1;), pointing to the 0-based column index where the country code is located. Directives for columns not present in the CSV are explicitly configured as -1;:

ID|ISO|CITY|ZIP|ADDRESS|CIVIC
501|FRA|Paris|75004|rue de Rivoli|45
502|DEU|Berlin|10117|Friedrichstraße|100
503|ESP|Madrid|28013|Calle Gran Vía|28

[IN_ISO]            1;
[IN_FUN]            GEO;
[IN_SEP]            |;
[IN_ENC]            UTF8;
[IN_INT]            S;
[IN_IDN]            0;
[IN_STA]            -1;
[IN_REG]            -1;
[IN_DPT]            -1;
[IN_CNL]            2;
[IN_DS1]            -1;
[IN_ZIP]            3;
[IN_DUG]            -1;
[IN_STR]            4;
[IN_CIV]            5;
[IN_ESP]            -1;
[IN_PRE]            -1;

Unmapped Directives Rule

Keep all 12 column directives in the .trk file. When your input dataset does not provide a field (such as an ID, province, hamlet, or care-of), set its directive to -1; instead of removing it.

Try in Playground

Want to test your own CSV dataset layout, auto-detect column directives, and generate validated .trk descriptor files interactively? Use the Batch Processing Playground.

---

Next Steps

• Inspect the Output Schema & Codes for the full dictionary of returned fields and coordinates.
• Explore the Quality Indicators Reference for complete diagnostic code definitions.
• Upload your files with SFTP Setup & Workflow.