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 Request 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/{jobRunId}URL example
get
URL example
https://api.tomtom.com/maps/orbis/platform/gem/jobs/job-abc123-def456curl command example
get
curl command example
curl -X GET "https://api.tomtom.com/maps/orbis/platform/gem/jobs/job-abc123-def456" \ -H "tomtom-api-key: YOUR_API_KEY" \ -H "Authorization: Bearer YOUR_AUTH_TOKEN" \ -H "X-Version: 1"Request headers
| Header | Required | Description |
|---|---|---|
tomtom-api-key | Yes | Your TomTom API key |
Authorization | Yes | Bearer token from Azure CLI |
X-Version | Yes | API version (use 1) |
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
jobRunId | string | Yes | The unique identifier of the job |
Response data
Response example (completed job)
{ "jobRunId": "job-abc123-def456", "storageId": "storage-001", "inputFileName": "your_data.parquet", "outputFileName": "your_data_matched.parquet", "matchingType": "road", "overtureRelease": "<latest-overture-release>", "status": "finished", "createdAt": "2026-01-20T10:00:00Z", "modifiedAt": "2026-01-20T10:25:00Z", "statistics": { "roads_matched": "84.68%", "roads_unmatched": "15.31%", "roads_fully_matched": "67.5%", "roads_partially_matched": "17.18%", "confidence_threshold": 60, "execution_time_sec": 9751.75, "kms_processed": 141977.62151907186, "num_roads_processed": 32456 }}Response example (running job)
{ "jobRunId": "job-abc123-def456", "storageId": "storage-001", "inputFileName": "your_data.parquet", "matchingType": "road", "overtureRelease": "<latest-overture-release>", "status": "running", "progress": 65, "createdAt": "2026-01-20T10:00:00Z", "modifiedAt": "2026-01-20T10:15:00Z"}Response fields
| Field | Type | Description |
|---|---|---|
jobRunId | string | Unique identifier for the job |
storageId | string | Storage where files are located |
inputFileName | string | Name of the input file |
outputFileName | string | Name of output file (when finished) |
matchingType | string | Type of matching performed |
overtureRelease | string | Overture Maps release version used |
status | string | Current job status |
progress | number | Percentage complete (0-100) |
createdAt | string | ISO 8601 timestamp of job creation |
modifiedAt | string | ISO 8601 timestamp of last update |
statistics | object | Matching statistics (when finished) |
statistics.roads_matched | percent | Successfully matched records |
statistics.roads_unmatched | percent | Records without matches |
statistics.roads_fully_matched | percent | Records with full 1-2-1 matches |
statistics.roads_partially_matched | percent | Percentage of partially matched records |
statistics.confidence_threshold | number | Confidence threshold |
statistics.execution_time_sec | float | Execution time |
statistics.kms_processed | float | Amount of processed kilometers |
statistics.num_roads_processed | number | Amount of processed roads |
Job status values
| Status | Description | Next Steps |
|---|---|---|
queued | Waiting to be processed | Wait for processing to begin |
running | Currently executing | Poll for progress updates |
finished | Completed successfully | Download results from storage |
failed | Encountered an error | Check error message and retry |
cancelled | Cancelled by user | Submit a new job if needed |
Output file
When a job completes successfully, the output file is available in your storage location. The output filename follows this pattern:
{original_filename}_matched.parquetFor example, if you submitted roads_data.parquet, the output file will be roads_data_matched.parquet.
Output file structure
The output Parquet file contains all original columns plus additional columns with GERS matching results:
| Column | Type | Description |
|---|---|---|
| (original columns) | varies | All columns from your input file |
gers_id | string | Matched GERS identifier |
match_confidence | float | Confidence score (0.0-1.0) |
match_status | string | matched or unmatched |
Error responses
| HTTP Status | Error | Cause | Solution |
|---|---|---|---|
| 401 | Unauthorized | Invalid credentials | Refresh API key or token |
| 404 | Not Found | Job not found | Verify job ID |
| 500 | Internal Server Error | Server-side issue | Retry the request |