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 | Path of the input file in the storage, exactly as List storage files returns it in files[].path, for example input/my_roads.parquet. Case-sensitive. 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 | Existing Overture Maps release in the format YYYY-MM-DD.N, for example 2026-01-21.0. See Releases |
with_visualization_data | boolean | No | ROAD_MATCHING only. When true, GEM also writes GeoJSON files for viewing the matches, see Visualization data. Default: false |
Response data
A successful request returns HTTP status 201 Created with the job details, and a Location header with the URL of the new job. A new job has status REQUESTED.
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 | Path of the results file in the storage. 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 of successful ROAD_MATCHING jobs, see Get job details. Otherwise null |
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. See error_messages |
SUCCESS | Job finished successfully |
CANCELED | Job was canceled before completion |
Error responses
| HTTP Status | Error | Cause | Solution |
|---|---|---|---|
| 400 | Bad Request | One of provided arguments is not valid.: the request body is malformed, or a required field is missing or has a wrong value | Check the JSON format and the required fields |
| 400 | Bad Request | File extension '.<ext>' is not supported for job type '<job_type>'. Allowed extensions: <extensions>. | Use a .parquet file, or a .csv file for LANE_LEVEL_MATCHING |
| 400 | Bad Request | Input file '<filename>' was not found in the storage location. | Upload the file first, and use its exact path from List storage files |
| 400 | Bad Request | Overture release '<release>' does not exist. Latest available releases: [...] | Use one of the listed releases |
| 401 | Unauthorized | Invalid credentials | Refresh API key or token |
| 409 | Conflict | A job with the same parameters is already in progress: <job_id>. A job for the same storage, input file, job type, and Overture release is still REQUESTED or IN_PROGRESS. | Wait for that job to finish, or cancel it |
| 500 | Internal Server Error | Server-side issue | Retry the request |
| 503 | Service Unavailable | Job submission failed due to a temporary issue. Please try again. | Retry the request |