Create matching job
Request accessPurpose
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
https://api.tomtom.com/maps/orbis/platform/gem/jobsURL example
post
URL example
https://api.tomtom.com/maps/orbis/platform/gem/jobscurl command example
post
curl command example
curl -X POST "https://api.tomtom.com/maps/orbis/platform/gem/jobs" \ -H "tomtom-api-key: YOUR_API_KEY" \ -H "Authorization: Bearer YOUR_AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "storage_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "filename": "your_data.parquet", "job_type": "ROAD_MATCHING", "overture_release": "2026-01-21.0" }'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
{ "storage_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "filename": "your_data.parquet", "job_type": "<type-of-job>", "overture_release": "<overture-release-version>"}Request body parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
storage_id | string (uuid) | Yes | ID of the storage containing your data |
filename | string | Yes | Name of the input file. Accepted extensions: .parquet (both job types) or .csv (LANE_LEVEL_MATCHING only) |
job_type | string | Yes | Type of matching to perform: ROAD_MATCHING or LANE_LEVEL_MATCHING |
overture_release | string | Only if job_type is ROAD_MATCHING | Overture Maps release version, see Releases |
with_visualization_data | boolean | No | ROAD_MATCHING only. When true, exports additional GeoJSON visualization data after matching. Default: false |
Response data
Response example
{ "job_type": "ROAD_MATCHING", "overture_release": "2026-01-21.0", "input_filename": "test_data.parquet", "job_id": 123456789, "requested_at": "2026-02-18T10:38:59.031762Z", "result_filename": null, "statistics": null, "error_messages": null, "status": "REQUESTED", "storage_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"}Response fields
| Field | Type | Description |
|---|---|---|
job_id | integer (int64) | Unique identifier for the job |
storage_id | string (uuid) | Storage where input/output files are located |
input_filename | string | Name of the input file |
result_filename | string | Name of the output file. null until status is SUCCESS |
job_type | string | Type of matching performed |
overture_release | string | Overture Maps release version for ROAD_MATCHING jobs, see Releases |
status | string | Current job status. See Job status values |
requested_at | string | ISO 8601 timestamp of job creation |
statistics | object | Matching statistics. null unless status is SUCCESS |
error_messages | string[] | List of error messages describing why the job failed. null unless status is FAILED |
Job status values
| Status | Description |
|---|---|
REQUESTED | Job was requested and is waiting to be processed |
IN_PROGRESS | Job has started and is currently being executed |
FAILED | Job encountered an error during the execution |
SUCCESS | Job finished successfully |
CANCELED | Job was canceled before completion |
Error responses
| HTTP Status | Error | Cause | Solution |
|---|---|---|---|
| 400 | Bad Request | Invalid request body (missing required fields, invalid filename format, unknown Overture release) | Check JSON format and required fields |
| 401 | Unauthorized | Invalid credentials | Refresh API key or token |
| 500 | Internal Server Error | Server-side issue | Retry the request |