Getting Started with GEM
Getting started
Global Entity Matcher (GEM) is designed to simplify the process of aligning your geospatial data with standardized identifiers. This guide helps you understand the prerequisites and choose the right approach for your needs.
Overview
GEM enables you to match your proprietary transportation network data against Overture Maps reference datasets. You can interact with GEM through two methods:
| Approach | Best for | Key benefits |
|---|---|---|
| UI (Dashboard) | Interactive use, exploration, manual jobs | Visual interface, guided workflows, no coding required |
| API | Automation, integration, batch processing | Programmatic access, CI/CD integration, scripting |
Both approaches provide the same core functionality—the choice depends on your workflow preferences and integration needs.
Prerequisites
Before using GEM, ensure you have the following:
1. Account access
- TomTom account: Active account at my.tomtom.com
- Project assignment: Assigned to a project with GEM access enabled
- Microsoft Entra ID: Authentication credentials configured
2. Technical tools
- Azure CLI: Required for data upload/download operations (both UI and API)
- Install from Microsoft Azure CLI
- Supports files of any size with no memory limitations
- Terminal access: Command-line interface on your machine
- Stable internet: For uploading/downloading datasets
3. Data requirements
Input files must meet these specifications:
| Requirement | Details |
|---|---|
| Format | Apache Parquet (.parquet extension) |
| Required fields | id (integer [unique]), is_navigable (boolean), geometry (LineString WKT) |
Example record:
1{2 "id": 5707295,3 "is_navigable": true,4 "geometry": "LINESTRING (145.18156715700002 -37.87340530899996, 145.1809221540001 -37.87356512499997)"5}
Choose your approach
Option 1: UI (Dashboard)
The web-based interface is ideal for:
- First-time users exploring GEM capabilities
- Manual, one-off matching jobs
- Visual monitoring of job progress
- Teams preferring guided workflows
Get started: UI Documentation
Option 2: API
The REST API is ideal for:
- Automated recurring workflows
- Integration with existing data pipelines
- Batch processing of multiple datasets
- CI/CD pipeline integration
Get started: API Documentation
Quick start paths
UI quick start
- Install Azure CLI
- Go to my.tomtom.com and log in
- Select your project and click Global Entity Matcher
- Follow the UI workflow guide
API quick start
- Install Azure CLI
- Create an API key at my.tomtom.com/keys with GEM APIs enabled
- Follow the API authentication guide
- Use the GEM API to create matching jobs
System status
GEM is fully operational in production:
| Metric | Value |
|---|---|
| Uptime | ≥99% |
| Processing speed | ~100,000 road segments per hour |
| Matching accuracy | >85% confidence for high-quality input |
Getting access
If you don't have GEM access yet:
- Contact sales: Reach out to discuss your needs
- Define your use case: Share requirements and business objectives
- Onboarding: Work with our team to configure GEM for your workflows
Dashboard portal: my.tomtom.com
Next steps
Choose your documentation path:
- UI Documentation - Web interface guide
- API Documentation - Programmatic access guide
- Understanding GERS IDs - Learn about the reference system
- Use Cases - Industry applications
- FAQ - Common questions