Create matching job
Purpose
Submit a new matching job to process your uploaded data and align it with GERS identifiers.
Request data
HTTP method: POST
- Constants and parameters enclosed in curly brackets
{}must be replaced with their values. - See the following Request parameters section with the required and optional parameters tables for these values.
URL format
post
URL format
https://api.tomtom.com/maps/orbis/platform/gem/jobs
URL example
post
URL example
https://api.tomtom.com/maps/orbis/platform/gem/jobs
curl command example
post
curl command example
1curl -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 |