Get job details
Request accessPurpose
Retrieve detailed information about a specific matching job, including its current status, progress, and results.
Request data
HTTP method: GET
- Constants and parameters enclosed in curly brackets
{}must be replaced with their values. - See the following Path parameters section with the required and optional parameters tables for these values.
URL format
get
URL format
https://api.tomtom.com/maps/orbis/platform/gem/jobs/{job_id}URL example
get
URL example
https://api.tomtom.com/maps/orbis/platform/gem/jobs/123456789curl command example
get
curl command example
curl -X GET "https://api.tomtom.com/maps/orbis/platform/gem/jobs/123456789" \ -H "tomtom-api-key: YOUR_API_KEY" \ -H "Authorization: Bearer YOUR_AUTH_TOKEN"Request headers
| Header | Required | Description |
|---|---|---|
tomtom-api-key | Yes | Your TomTom API key |
Authorization | Yes | Bearer token from Azure CLI |
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
job_id | integer | Yes | The unique identifier of the job |
Response data
Response example (successful job)
{ "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": "test_data.results.parquet", "status": "SUCCESS", "storage_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "error_messages": null, "statistics": { "confidence_threshold": 60, "execution_time_sec": 9751, "kms_processed": 80208.39, "kms_matched": 67912.45, "num_roads_processed": 397613, "roads_fully_matched_ratio": 0.675, "roads_matched_ratio": 0.8468, "roads_partially_matched_ratio": 0.1718, "roads_unmatched_ratio": 0.1531 }}Response example (running job)
{ "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, "status": "IN_PROGRESS", "storage_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "statistics": null, "error_messages": null}Response example (failed job)
{ "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, "status": "FAILED", "storage_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "statistics": null, "error_messages": [ "Input file 'test_data.parquet' was not found in the storage location." ]}Response fields
| Field | Type | Description |
|---|---|---|
job_id | integer (int64) | Unique identifier for the job |
storage_id | string (uuid) | Storage where 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 used for ROAD_MATCHING jobs |
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. Otherwise null |
statistics.confidence_threshold | integer | Confidence threshold |
statistics.execution_time_sec | integer | Duration of the job run in seconds |
statistics.kms_processed | float | Total length of the roads in the input file, in kilometers |
statistics.kms_matched | float | Total length of the matched parts of the input roads, in kilometers |
statistics.num_roads_processed | integer | Number of distinct road IDs in the input file |
statistics.roads_fully_matched_ratio | float | Share of input roads (0–1) whose whole length matches a single GERS segment |
statistics.roads_matched_ratio | float | Share of input roads (0–1) with at least one match, full or partial |
statistics.roads_partially_matched_ratio | float | Share of input roads (0–1) that match only in part, or across several GERS segments |
statistics.roads_unmatched_ratio | float | Share of input roads (0–1) without a match |
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 |
|---|---|---|---|
| 401 | Unauthorized | Invalid credentials | Refresh API key or token |
| 404 | Not Found | Job not found, or you have no access to the job’s storage | Verify job ID |
| 500 | Internal Server Error | Server-side issue | Retry the request |