Developer

API overview

Request Access

GEM API overview

In addition to the GEM User Interface, you can programmatically interact with Global Entity Matcher through a set of REST APIs. This enables automation of data workflows, integration with CI/CD pipelines, and building custom applications on top of GEM capabilities.

API architecture

GEM APIs are exposed through the TomTom API Gateway under api.tomtom.com. The system consists of two main API components:

Orbis Private Data Gateway API

The Private Data Gateway API manages secure cloud storage for your geospatial data. Use this API to:

  • List available storage locations
  • Retrieve storage details and configuration
  • Obtain credentials for data upload/download operations

Base URL:

https://api.tomtom.com/maps/orbis/platform/private-gateway

GEM API

The GEM API handles the matching operations that align your data with GERS identifiers. Use this API to:

  • Create new matching jobs
  • Monitor job progress and status
  • Retrieve job results and statistics

Base URL:

https://api.tomtom.com/maps/orbis/platform/gem

API vs. UI comparison

CapabilityUIAPI
Upload data to storage✅✅ (via Azure CLI with credentials from API)
Trigger matching jobs✅✅
Monitor job status✅✅
View job details✅✅
Download results✅✅ (via Azure CLI with credentials from API)
Batch operations❌✅
Automation & scripting❌✅
CI/CD integration❌✅

When to use the API

The API approach is ideal when you need to:

  • Automate recurring workflows: Schedule regular data matching jobs
  • Integrate with existing systems: Connect GEM to your data pipelines
  • Process multiple datasets: Submit batch jobs programmatically
  • Build custom applications: Create tailored interfaces for your users
  • Implement CI/CD: Include GEM matching in your deployment processes

API workflow overview

A typical API-based workflow follows these steps:

  1. Authentication

    • Obtain TomTom API key from my.tomtom.com
    • Generate authorization token via Azure CLI

  2. Storage Access

    • List available storages (GET /storages)
    • Get storage credentials (GET /storages/{id}/credentials)
    • Upload data using Azure CLI with credentials

  3. Job Execution

    • Create matching job (POST /jobs)
    • Poll job status (GET /job/{job_run_id})
    • Retrieve results when complete

  4. Results Download

    • Download results using Azure CLI with storage credentials

Prerequisites for API usage

Before using the GEM APIs, ensure you have:

1. Access requirements

  • TomTom account: Active account at my.tomtom.com
  • API key: A valid API key with GEM API access enabled
  • Project assignment: Assigned to a project with GEM access

2. Required API products

When creating your API key at my.tomtom.com/keys, ensure you enable:

  • Orbis Private Data Gateway API - For storage management
  • Orbis GEM API - For matching operations

3. Technical tools

  • HTTP client: curl, Postman, or any HTTP library
  • Azure CLI: Required for authentication and data upload/download
  • Terminal access: Command-line interface on your machine

4. Data requirements

Same as UI-based workflow:

  • Format: Apache Parquet (.parquet extension)
  • Required fields:
    • id (integer): Unique identifier
    • is_navigable (boolean): Navigability flag
    • geometry (LineString WKT): Road geometry

Next steps