TomTom LogoDocs
Products
Resources
Pricing
Sign in
Global Entity Matcher (GEM)

Quick reference

Request access

Quick reference

A one-page reference for GEM commands, endpoints, and common operations.

API endpoints

Private Data Gateway API

MethodEndpointDescription
GET/maps/orbis/platform/private-gateway/storagesList all storages
GET/maps/orbis/platform/private-gateway/storages/{id}Get storage details
GET/maps/orbis/platform/private-gateway/storages/{id}/filesList storage files
GET/maps/orbis/platform/private-gateway/storages/{id}/credentialsGet storage credentials

Base URL: https://api.tomtom.com

GEM API

MethodEndpointDescription
POST/maps/orbis/platform/gem/jobsCreate matching job
GET/maps/orbis/platform/gem/jobsList all jobs
GET/maps/orbis/platform/gem/jobs/{job_id}Get job details
PATCH/maps/orbis/platform/gem/jobs/{job_id}Cancel matching job

Base URL: https://api.tomtom.com

Required headers

Every API request must include:

-H "tomtom-api-key: YOUR_API_KEY"
-H "Authorization: Bearer YOUR_AUTH_TOKEN"

For POST and PATCH HTTP methods, include the Content-Type header:

-H "Content-Type: application/json"

Azure CLI commands

Authentication

Get authorization token

az account get-access-token --scope https://gem.core.orbis.tomtom.com/user_impersonation

Authorize to access storage with obtained credentials

az login --service-principal \
  --username <CLIENT_ID> \
  --password <CLIENT_SECRET> \
  --tenant <TENANT_ID>

Data upload

az storage blob upload \
  --account-name <STORAGE_ACCOUNT> \
  --container-name default \
  --name <FILENAME>.parquet \
  --file /path/to/local/file.parquet \
  --auth-mode login

Results download

az storage blob download \
  --account-name <STORAGE_ACCOUNT> \
  --container-name default \
  --name <FILENAME>.results.parquet \
  --file /path/to/destination/<FILENAME>.results.parquet \
  --auth-mode login

<STORAGE_ACCOUNT> is the first part of the storage url host, for example mystorageaccount001 in https://mystorageaccount001.blob.core.windows.net/default/.

Road matching data

Input

FieldTypeRequiredDescription
idinteger or string✅Unique road segment identifier
geometrystring (WKT)✅LineString geometry in WGS84, longitude first
is_navigableboolean—Whether road is navigable. Without this column, all roads count as navigable

Example:

{"id": 5707295, "geometry": "LINESTRING (4.8952 52.3702, 4.8960 52.3710)", "is_navigable": true}

Results

FieldTypeDescription
idstringYour original road segment ID
gersstringMatched GERS ID (UUID format)
confidenceintegerMatch confidence score (0-100)
lr_idstringMatched part of your road, as <start>-<end>#<gers> in percent of its length
lr_gersstringMatched part of the GERS segment, as <start>-<end>#<id> in percent of its length

Example:

{"id":"5707295","gers":"0b5c2f4e-8d3a-4c1e-9f6b-2a7d5e8c1b34","confidence":97,"lr_id":"0.0-100.0#0b5c2f4e-8d3a-4c1e-9f6b-2a7d5e8c1b34","lr_gers":"12.5-64.1#5707295"}

→ Details: Road matching data

Lane-level matching data

ItemFormat
Parquet inputid (string) and points: a list of structs with coord (x longitude, y latitude), heading, lane, timestamp, and velocity
CSV inputRoad profile: uuid, shape (WKT LINESTRING). Road events: uuid, heading, coordinate (WKT POINT)
ResultstraceId, mapRevisionId, and roads: matched road areas with their connectors and the matched lane

→ Details: Lane-level matching data

Job statuses

StatusDescription
REQUESTEDJob was requested and is waiting to be processed
IN_PROGRESSJob has started and is currently being executed
FAILEDJob encountered an error during the execution
SUCCESSJob finished successfully
CANCELEDJob was canceled before completion

Common curl examples

List storages

curl -X GET "https://api.tomtom.com/maps/orbis/platform/private-gateway/storages" \
  -H "tomtom-api-key: $TOMTOM_API_KEY" \
  -H "Authorization: Bearer $AUTH_TOKEN"

Get storage credentials

curl -X GET "https://api.tomtom.com/maps/orbis/platform/private-gateway/storages/$STORAGE_ID/credentials?type=READ_WRITE" \
  -H "tomtom-api-key: $TOMTOM_API_KEY" \
  -H "Authorization: Bearer $AUTH_TOKEN"

Create matching job

curl -X POST "https://api.tomtom.com/maps/orbis/platform/gem/jobs" \
  -H "tomtom-api-key: $TOMTOM_API_KEY" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "storage_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "filename": "my_data.parquet",
    "job_type": "ROAD_MATCHING",
    "overture_release": "2026-01-21.0"
  }'

Check job status

curl -X GET "https://api.tomtom.com/maps/orbis/platform/gem/jobs/$JOB_ID" \
  -H "tomtom-api-key: $TOMTOM_API_KEY" \
  -H "Authorization: Bearer $AUTH_TOKEN"

Cancel matching job

curl -X PATCH "https://api.tomtom.com/maps/orbis/platform/gem/jobs/$JOB_ID" \
  -H "tomtom-api-key: $TOMTOM_API_KEY" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "CANCEL"}'

Processing time estimates

Dataset sizeEstimated time
< 10,000 roadsMinutes
10,000 - 100,0001-2 hours
100,000 - 1M10-15 hours
> 1M roadsContact support

Rate limits

  • Default: 10 requests per second
  • Exceeded: Returns 429 Too Many Requests

Quality thresholds

Match rateQuality
> 85%Excellent
70-85%Good
< 70%Review data quality

Error codes

CodeMeaningSolution
400Bad RequestCheck the request body, the file path and extension, and the Overture release
401UnauthorizedCheck API key and token
403ForbiddenVerify permissions
404Not FoundCheck resource ID
409ConflictAn identical job is still running, or the job already finished and cannot be canceled
429Rate limitedWait and retry
503Service UnavailableTemporary issue when creating a job; retry

Resources