Create matching job

Request access

Purpose

Submit a new matching job to process your uploaded data and align it with GERS identifiers.

Request data

HTTP method: `POST`

See the following Request body section with the required and optional parameters tables for these values.

URL format

post

URL format

1
https://api.tomtom.com/maps/orbis/platform/gem/jobs

URL example

post

URL example

1
https://api.tomtom.com/maps/orbis/platform/gem/jobs

curl command example

post

curl command example

1
curl -X POST "https://api.tomtom.com/maps/orbis/platform/gem/jobs" \
2
  -H "tomtom-api-key: YOUR_API_KEY" \
3
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
4
  -H "Content-Type: application/json"
5
  -d '{
6
    "storage_id": "storage-001",
7
    "filename": "your_data.parquet",
8
    "job_type": "ROAD_MATCHING",
9
    "overture_release": "2026-01-21.0"
10
  }'

Request headers

Header	Required	Description
`tomtom-api-key`	Yes	Your TomTom API key
`Authorization`	Yes	Bearer token from Azure CLI
`Content-Type`	Yes	Must be `application/json`

Request body

1
{
2
  "storage_id": "storage-001",
3
  "filename": "your_data.parquet",
4
  "job_type": "<type-of-job>",
5
  "overture_release/orbis_version": "<overture-release-version>/<orbis-version>"
6
}

Request body parameters

Parameter	Type	Required	Description
`storage_id`	string	Yes	ID of the storage containing your data
`filename`	string	Yes	Name of the uploaded Parquet file (including `.parquet` extension)
`job_type`	string	Yes	Type of matching to perform (currently only `ROAD_MATCHING` or `LANE_LEVEL_MATCHING`)
`overture_release`	string	Yes (only if `job_type` is `ROAD_MATCHING`)	Overture Maps release version, see Releases
`orbis_version`	string	Yes (only if `job_type` is `LANE_LEVEL_MATCHING`)	Orbis Map version with format `<LAYER_ID>`.`<REVISION>`, example 123456.1

Response data

Response example

1
{
2
    "job_type": "ROAD_MATCHING",
3
    "overture_release": "2026-01-21.0",
4
    "input_filename": "test_data.parquet",
5
    "job_id": 123456789,
6
    "requested_at": "2026-02-18T10:38:59.031762Z",
7
    "result_filename": null,
8
    "statistics": null,
9
    "status": "REQUESTED",
10
    "storage_id": "storage-001"
11
}

Response fields

Field	Type	Description
`job_id`	integer	Unique identifier for the job
`storage_id`	string	Storage where input/output files are located
`input_filename`	string	Name of the input file
`job_type`	string	Type of matching performed
`overture_release`	string	Overture Maps release version for `ROAD_MATCHING` job type, see Releases
`orbis_version`	string	Orbis Map version for `LANE_LEVEL_MATCHING` job type with format `<LAYER_ID>`.`<REVISION>`, example 123456.1
`status`	string	Current job status (`REQUESTED`)
`requested_at`	string	ISO 8601 timestamp of job creation
`statistics`	object	Matching statistics, available only when `status` is `SUCCESS`

Error responses

HTTP Status	Error	Cause	Solution
400	Bad Request	Invalid request body	Check JSON format and required fields
401	Unauthorized	Invalid credentials	Refresh API key or token
404	Not Found	Storage not found	Verify storage ID
422	Unprocessable Entity	Invalid parameters	Check input file name and matching type

Create matching job

Purpose

Request data

HTTP method: POST

URL format

URL example

curl command example

Request headers

Request body

Request body parameters

Response data

Response example

Response fields

Error responses

HTTP method: `POST`