Data preparation

Every GEM job processes one input file from your storage. This page describes what all input files have in common. The page for each matching type describes its columns, shows how to create and check the file, and explains the results.

Choose a matching type

Matching type	You provide	Input file	GEM returns	Details
Road matching (`ROAD_MATCHING`)	Road segments with an ID and a geometry	`.parquet`	For each road, the matched segments of Overture Maps with their GERS IDs and the matched parts	Road matching data
Lane-level matching (`LANE_LEVEL_MATCHING`)	GPS traces	`.parquet` or `.csv`	For each trace, the matched roads and lanes of TomTom Orbis Maps	Lane-level matching data

File requirements

Upload one file per job. A job processes exactly the file you select.
Use the lowercase extension .parquet or, for lane-level matching, .csv. Extensions are case-sensitive.
Use WGS84 coordinates (EPSG:4326), longitude first.
Give every road or trace a stable ID, so you can join the results back to your data.

Name and place the file

You can upload the file to the root of your storage or to a folder in it. In the API, filename is the full path of the file in the storage, for example input/roads.parquet, exactly as List storage files returns it.

Use descriptive names without spaces or special characters, and with only one dot, before the extension:

1
{region}_{data_type}_{date}_{version}.parquet
2

3
netherlands_roads_20260115_v1.parquet
4
california_highways_20260120_v2.parquet

Upload the file

Upload the file in the UI with Prepare Data, see the UI workflow guide, or with Azure CLI, see the API workflow guide:

1
az storage blob upload --account-name "<STORAGE_ACCOUNT_NAME>" \
2
                       --container-name "default" \
3
                       --name "input/roads.parquet" \
4
                       --file "/path/to/roads.parquet" \
5
                       --auth-mode login

Result files

GEM writes the results next to the input file. The results file is named after the input file, with .results.parquet instead of its extension:

Input file	Results file
`roads.parquet`	`roads.results.parquet`
`input/traces.csv`	`input/traces.results.parquet`

Road matching jobs with visualization data also write a <name>-visualization-data/ folder, see Visualization data.

Before you start

Test with a sample of 1,000–10,000 roads or traces before you process a full dataset.
Check your file with the validation script for your matching type.
Keep your source data, so you can compare it with the results.

Next steps

Road matching data - Input columns, validation script, and results of road matching
Lane-level matching data - Parquet and CSV traces, validation scripts, and results of lane-level matching
UI workflow guide - Upload through the web interface
API workflow guide - Upload and manage data through the API
Quick reference - Command cheat sheet