Frequently Asked Questions (FAQ)

Introduction

Find answers to common questions about Global Entity Matcher (GEM) and the Global Entity Reference System (GERS).

General questions

What is a GERS ID?

A GERS ID (Global Entity Reference System Identifier) is a unique, persistent identifier assigned to geospatial features such as road segments, intersections, and other map entities. It's part of the Overture Maps Foundation's initiative to create a standardized, open reference system for geospatial data.

GERS IDs provide:

• Unique identification for each geospatial entity
• Persistent references that remain stable over time
• Global interoperability across different mapping systems
• Open standard that's vendor-neutral

For more details, see Understanding GERS IDs.

How do GERS IDs help with geospatial conflation challenges?

GERS IDs dramatically simplify geospatial conflation by providing a common reference system. Instead of manually matching and aligning datasets from different sources, you can use GERS IDs as the standard identifier. This:

• Eliminates manual conflation between systems that both use GERS
• Reduces errors from manual matching processes
• Accelerates integration of new data sources
• Maintains consistency across map updates
• Enables data sharing without custom integration

The result is significantly lower costs and faster time-to-market for data integration projects.

What is GEM?

Global Entity Matcher (GEM) is a service that automatically aligns your proprietary geospatial datasets with Overture's Global Entity Reference System (GERS) identifiers.

GEM uses AI-driven algorithms to:

• Match your data to the appropriate GERS IDs
• Maintain synchronization as maps are updated
• Provide sub-segment precision using linear referencing
• Handle complex matching scenarios automatically
• Support flexible deployment (cloud or on-premises)

Think of GEM as your automated assistant for adopting and maintaining GERS IDs in your data infrastructure.

What types of use cases does GEM support?

GEM supports a wide range of use cases across multiple industries:

Government & Public Sector:

• Asset management and road maintenance
• Traffic management and analysis
• Emergency response coordination
• Public transportation planning

Commercial Applications:

• Fleet management and logistics
• Navigation services
• Insurance risk assessment
• Real estate analytics

Smart Cities:

• Urban planning and development
• Environmental monitoring
• Infrastructure management

Technology & Data:

• Geospatial data enhancement
• Location-based services
• Data marketplace participation

For detailed use case information, see our Use Cases page.

How can I access the GEM service?

GEM is available through direct engagement with our sales team. To get started:

1. Contact Sales via the GEM product page
2. Discuss your requirements including use cases, data types, and deployment preferences
3. Choose your deployment model (cloud or on-premises)
4. Work with our team to configure and onboard GEM for your organization

See our Getting Started guide for more information.

What makes GEM different from other conflation tools?

GEM stands out in several key ways:

AI-Driven Accuracy:

• Advanced machine learning algorithms trained on diverse datasets
• Handles complex matching scenarios automatically
• Continuous improvement through feedback

GERS Integration:

• Direct integration with Overture's GERS standard
• Future-proof approach using open standards
• Enables global interoperability

Sub-Segment Precision:

• Linear referencing for fine-grained accuracy
• Supports detailed data attribution
• Better than simple point-to-road matching

Flexible Deployment:

• Cloud or on-premises options
• Customizable to meet privacy requirements
• Scalable architecture

Continuous Sync:

• Automatic updates as maps change
• Reduces ongoing maintenance burden
• Keeps your data current

Expertise:

• Built on decades of mapping experience
• Supported by our technical team
• Integration with TomTom Orbis Maps

When will GEM be available?

GEM is currently available. To get started:

• Contact our sales team through the GEM product page
• Discuss your specific requirements and timeline
• Work with us to plan your implementation

Availability may vary by region and deployment type, so we encourage you to reach out to discuss your specific needs.

Who can benefit from GEM?

GEM is valuable for any organization that works with geospatial data, including:

Government Agencies:

• Transportation departments
• Emergency services
• Public works departments
• Urban planning offices

Transportation Providers:

• Logistics and fleet companies
• Public transit authorities
• Ride-sharing and delivery services
• Navigation service providers

Smart City Initiatives:

• City governments
• Urban planners
• Sustainability programs
• Infrastructure managers

Commercial Organizations:

• Insurance companies
• Real estate firms
• Telecommunications providers
• Automotive companies

Data and Technology Companies:

• Geospatial data providers
• Location-based service platforms
• Analytics companies
• Software vendors

If you work with location data and face challenges in data integration, maintenance, or interoperability, GEM can help.

Can I see a demo or learn how GEM fits into my specific use case?

Yes! We encourage potential customers to:

1. Request a demo by contacting our sales team
2. Discuss your use case in detail with our experts
3. See examples relevant to your industry
4. Explore pilot options to validate the approach

During these discussions, we can:

• Show you how GEM works with sample data
• Discuss technical integration approaches
• Estimate costs and timelines
• Answer specific technical questions
• Provide reference customers in similar industries

Contact us through the GEM product page to set up a consultation.

Will GEM support other data domains beyond road geometry in the future?

While GEM currently focuses on road network data and linear features, the GERS framework is designed to be extensible. As the Overture Maps Foundation and the broader geospatial community expand GERS to cover additional entity types, GEM will evolve to support these new domains.

Potential future expansions could include:

• Points of interest (POIs)
• Building footprints
• Administrative boundaries
• Transit infrastructure
• Pedestrian networks

We recommend contacting our team to discuss your specific data domain needs and learn about our roadmap.

Technical questions

What data formats does GEM support?

Input Format:

• Required: Apache Parquet format with .parquet file extension
• Size: No limit when using Azure CLI (recommended method)
• Alternative upload methods: May be restricted by system memory and network limitations

Required Schema: Your Parquet file must contain these fields:

Example valid record:

1{
2  "id": 5707295,
3  "is_navigable": true,
4  "geometry": "LINESTRING (145.18156715700002 -37.87340530899996, 145.1809221540001 -37.87356512499997)"
5}

Important Notes:

• Files in other formats can be uploaded to storage but will not trigger the matching process
• All three required fields must be present in every record
• IDs must be unique across your dataset
• Geometry must be valid WKT LineString format

How accurate is the matching?

GEM uses AI-driven algorithms to achieve high matching accuracy:

Performance Metrics:

• Matching Accuracy: >85% confidence scores for high-quality input data
• Processing Speed: ~100,000 road segments matched per hour
• System Uptime: ≥99% availability

Confidence Scoring:

• Each match receives a confidence score
• Confidence Threshold: Typically >60% for filtering
• Higher quality input data → higher confidence scores
• Quality metrics provided for validation

Matching Results Breakdown:

Accuracy depends on:

• Input Data Quality: Clean geometries and complete records yield better results
• Geographic Region: Coverage varies by location
• Data Type: Road networks match better than complex features
• Complexity: Simple road segments match more accurately than complex intersections

Quality Guidelines:

• 85% matched: Excellent quality

• 70-85% matched: Good quality, review unmatched roads
• Less than 70% matched: May indicate data quality issues - investigate

What are the system performance and availability metrics?

Current System Status:

Operational Metrics:

• System Uptime: ≥99% (continuously monitored)
• Processing Speed: ~100,000 road segments per hour
• Database Connectivity: 100% operational
• Storage Integration: 100% operational
• Authentication: Azure Entra ID integrated
• Authorization: Role-based access control enforced

Quality Assurance:

• Code Quality: Enterprise-grade quality standards
• Security Scan: No critical vulnerabilities
• Security: Regular vulnerability scanning active
• Deployment: Production-grade infrastructure

Monitoring: Real-time performance tracking ensures high availability and reliability

Processing Time Estimates:

Note: Times are approximate and may vary based on data complexity and system load

How does GEM handle map updates?

GEM automatically handles map updates through:

1. Monitoring: Tracks GERS ID changes as Overture Maps are updated
2. Change Detection: Identifies when features have been modified
3. Reference Updates: Uses the latest Overture Maps release (currently 2024-09-24.0)
4. Persistent IDs: GERS IDs remain stable across updates when features don't change
5. Transition Mapping: Provides linkage when IDs must change

Overture Maps Integration:

• Current Release: 2024-09-24.0 (automatically applied)
• Update Schedule: Follows Overture Maps Foundation release cycles
• Future Releases: System will support new versions as they become available

This ensures your data stays aligned with the latest maps without manual intervention.

What are the job statuses and what do they mean?

GEM jobs progress through the following states:

Status Details:

In Progress:

• GEM is actively matching your data to GERS IDs
• Processing happens in the backend
• No user action required
• Check back periodically for completion

Success:

• All processing completed without errors
• Results file generated and available for download
• Matching statistics calculated
• Ready to download via Azure CLI

Failed:

• An error occurred during processing
• Possible causes:
  • Invalid input file format
  • Missing required fields
  • Corrupted data
  • System error
• Action: Contact support team with job ID

What permissions do I need to use GEM?

GEM uses role-based access control for authorization:

Permission Scope:

• Job Runs: You can only access jobs you created
• Storage: Access controlled by your organization's permissions
• Credentials: Temporary tokens scoped to specific operations

Who Manages Permissions:

• Permissions are managed by your organization administrator
• Contact your system administrator if you need additional permissions

Can GEM work with my existing system?

Yes, GEM is designed for integration flexibility:

Deployment Options:

• Cloud-based SaaS
• On-premises installation
• Hybrid configurations

Integration Patterns:

• Azure CLI for data upload and download
• ETL pipeline integration with file-based workflows
• Database synchronization using GERS IDs
• Batch processing through Dashboard

Our team will work with you to design an integration approach that fits your existing architecture.

What about data privacy and security?

We take data privacy and security seriously:

Deployment Options:

• Cloud: Secure, compliant cloud infrastructure
• On-Premises: Full control within your environment
• Hybrid: Flexible combination based on sensitivity

Security Measures:

• Encryption in transit and at rest
• Access controls and authentication
• Audit logging
• Compliance with industry standards (SOC 2, ISO 27001, etc.)

Data Handling:

• Your data remains your data
• No data sharing without explicit permission
• Configurable retention policies
• Support for data residency requirements

We can customize security configurations to meet your specific compliance and regulatory requirements.

Comparison questions

What's the difference between Orbis Maps and Overture Maps?

TomTom Orbis Maps:

• TomTom's next-generation map product
• High-quality, commercially supported map data
• Optimized for automotive and enterprise applications
• Regular updates and comprehensive coverage
• Includes support for GERS IDs

Overture Maps:

• Open mapping data initiative
• Collaborative effort by multiple organizations
• Includes GERS as a reference system standard
• Community-driven and open source
• Foundation for interoperability

The Relationship:

• Orbis Maps data contributes to Overture Maps
• Both support GERS IDs for interoperability
• GEM helps you work with both through GERS
• Complementary rather than competing offerings

GEM enables you to benefit from both: you can adopt Orbis Maps while maintaining interoperability with Overture Maps and other GERS-enabled systems.

How does GEM compare to traditional conflation software?

Can I use GEM with maps from other providers?

Yes! Because GEM uses GERS IDs (an open standard), your GERS-enabled data can work with:

• TomTom Orbis Maps
• Overture Maps data
• Other GERS-compatible map providers
• Your own proprietary maps (with GERS IDs)

This is one of the key benefits of the GERS approach: true interoperability across different map sources.

Business questions

What is the typical ROI for implementing GEM?

ROI varies by organization and use case, but customers typically see value through:

Cost Reduction:

• 70-90% reduction in manual conflation effort
• Lower ongoing maintenance costs
• Reduced data quality issues
• Fewer integration project costs

Time Savings:

• Faster time-to-market for new integrations
• Accelerated data updates
• Reduced development cycles

Quality Improvements:

• Higher data accuracy
• Better consistency across systems
• Improved decision-making
• Enhanced service quality

New Opportunities:

• Ability to participate in data ecosystems
• New partnership opportunities
• Enhanced product offerings

Most customers see positive ROI within 6-12 months of implementation.

What are the costs involved?

GEM pricing is customized based on:

• Data Volume: Amount of data to be matched
• Update Frequency: How often synchronization is needed
• Deployment Model: Cloud vs. on-premises
• Support Level: Standard or premium support
• Geographic Coverage: Regions covered

Contact our sales team for a detailed quote based on your requirements.

How long does implementation take?

Typical timeline:

• Initial consultation: 1-2 weeks
• Configuration and setup: 2-4 weeks
• Pilot implementation: 4-6 weeks
• Production deployment: Varies by scope

Factors affecting timeline:

• Data complexity and volume
• Integration requirements
• Deployment model
• Internal approval processes

We work with you to develop a realistic timeline for your specific situation.

What support is available?

We provide comprehensive support:

During Onboarding:

• Dedicated implementation team
• Technical consultation
• Integration guidance
• Training for your team

Ongoing Support:

• Technical support team
• Regular check-ins
• Performance monitoring
• Update notifications

Resources:

• Technical documentation
• User guides and workflow documentation
• Best practices guides
• Community forums

Training:

• Webinars and workshops
• Custom training sessions
• Documentation and guides
• Video tutorials

Support level can be customized based on your needs.

Troubleshooting

What should I do if authentication fails?

Problem: az login command fails or returns an error

Common Causes and Solutions:

Step-by-Step Fix:

1. Return to GEM UI
2. Click Unwrap button again to get fresh credentials
3. Carefully copy the entire command (no extra spaces)
4. Paste and execute in terminal
5. Verify successful authentication message

What should I do if file upload fails?

Problem: az storage blob upload command fails or times out

Troubleshooting Steps:

Check 1: Verify File Path

1# Check if file exists (macOS/Linux)
2ls -lh /path/to/your/data.parquet
3
4# Check if file exists (Windows)
5dir C:\path\to\your\data.parquet

Check 2: Verify Authentication

# Test Azure CLI authentication
az account show

Check 3: Verify Storage Permissions

• Ensure you have Full Access permissions
• Check with system administrator if unsure

Check 4: Verify File Format

• Must be .parquet extension
• File must be valid Parquet format
• Check file isn't corrupted

Check 5: Network Stability

• Use stable internet connection
• Try smaller file for testing
• Consider upload during off-peak hours for large files

Common Solutions:

What should I do if job submission fails?

Problem: Cannot submit matching job, error appears in UI

Validation Checklist:

Filename Validation

• Matches exactly (case-sensitive)
• Includes .parquet extension
• No typos or extra spaces
• Example: my_data.parquet not my_data or My_Data.parquet

Storage Validation

• Selected same storage used for upload
• Storage has necessary permissions
• Storage is accessible and online

File Upload Confirmation

• File upload completed successfully
• File exists in storage container
• File is valid Parquet format with required fields

Required Fields Present

• id (integer) column exists
• is_navigable (boolean) column exists
• geometry (LineString WKT) column exists

Error Responses:

If form validation passes but submission returns error:

Next Steps:

1. Review error message carefully
2. Verify all checklist items above
3. Try with a small test file
4. Contact support with job details if issue persists

What should I do if my job fails?

Problem: Job status shows "Failed"

Immediate Actions:

1. Access Job Details

• Click details arrow (→) for the failed job
• Review any error messages or logs displayed

2. Check Common Issues

3. Validate Your Data

Run these checks on your input file:

1import pandas as pd
2
3# Read Parquet file
4df = pd.read_parquet('your_data.parquet')
5
6# Check required fields exist
7required_fields = ['id', 'is_navigable', 'geometry']
8missing_fields = [f for f in required_fields if f not in df.columns]
9print(f"Missing fields: {missing_fields}")
10
11# Check for null values
12print(f"Null values:\n{df[required_fields].isnull().sum()}")
13
14# Check data types
15print(f"Data types:\n{df[required_fields].dtypes}")
16
17# Sample records
18print(f"Sample records:\n{df.head()}")

4. Contact Support

If you cannot resolve the issue:

• Note the Job ID
• Copy any error messages
• Prepare a data sample (if possible)
• Contact support team

Include in your support request:

• Job ID and timestamp
• Exact error message
• Data format details
• Steps you've already tried

What should I do if results download fails?

Problem: Cannot download matching results

Troubleshooting Steps:

Step 1: Verify Job Status

• Ensure job status is "Success"
• Results only available for successful jobs
• Failed jobs don't produce results

Step 2: Check Authentication

1# Verify you're still authenticated
2az account show
3
4# If not authenticated, run login again
5az login --service-principal --username <client_id> --password <client_secret> --tenant <tenant_id>

Step 3: Verify Destination Path

1# Ensure directory exists (macOS/Linux)
2mkdir -p /path/to/destination
3
4# Ensure directory exists (Windows)
5mkdir C:\path\to\destination

Step 4: Check Storage Permissions

• Verify you have at least Read Access permissions
• Credentials may have expired - get fresh ones from UI

Step 5: Verify Disk Space

1# Check available space (macOS/Linux)
2df -h /path/to/destination
3
4# Check available space (Windows)
5wmic logicaldisk get size,freespace,caption

Common Solutions:

Why don't I see "Global Entity Matcher" in my sidebar?

Problem: GEM option is hidden or not available in dashboard

Possible Reasons:

1. Organization Access Your organization must have GEM access enabled.

2. Project Not Configured

• Your selected project may not have GEM enabled
• Try selecting a different project from the dropdown
• Contact administrator to enable GEM for your project

3. Permissions Issue

• You may not have necessary permissions
• Contact your system administrator
• Request access to GEM resources

4. Authentication Problem

• Ensure you're logged in with Microsoft Entra ID
• Try logging out and back in
• Clear browser cache if needed

Solution: Contact your system administrator or support team to:

• Verify your organization has GEM access
• Enable GEM for your project
• Assign appropriate permissions
• Complete onboarding process

What do I need to prepare before starting with GEM?

Before engaging with GEM, prepare:

Data Inventory:

• List of datasets you want to match
• Data formats and schemas
• Current data volumes
• Update frequencies

Use Case Definition:

• Primary objectives
• Success criteria
• Key stakeholders
• Budget and timeline

Technical Requirements:

• Deployment preferences (cloud/on-premises)
• Integration points in your architecture
• Security and compliance requirements
• Performance expectations

Organizational:

• Project sponsor
• Technical team members
• Decision-making process
• Approval requirements

Don't worry if you don't have everything—our team will help you through the discovery process.

Can I try GEM with a pilot project?

Absolutely! We encourage pilot projects to:

• Validate the approach with your data
• Demonstrate value to stakeholders
• Refine integration approach
• Establish success metrics

A typical pilot:

1. Selects a representative dataset
2. Runs matching process
3. Reviews results and quality
4. Assesses integration feasibility
5. Measures against success criteria

Pilots usually run 4-6 weeks and provide clear go/no-go decision criteria.

Who should I involve from my organization?

Key stakeholders typically include:

Executive Sponsor:

• Provides strategic direction
• Approves budget
• Ensures organizational alignment

Technical Lead:

• Oversees integration
• Reviews architecture
• Makes technical decisions

Data Team:

• Prepares datasets
• Reviews match quality
• Defines data requirements

End Users:

• Provides requirements
• Validates results
• Accepts final solution

IT/Security:

• Reviews deployment model
• Ensures compliance
• Manages infrastructure

Project Manager:

• Coordinates activities
• Tracks timeline
• Manages communication

Still have questions?

If you have additional questions not covered here:

• Contact Sales: Visit the GEM product page
• Explore Documentation:
  • Introduction
  • Getting Started
  • Features & Benefits
  • Use Cases
  • Understanding GERS IDs
• Request a Demo: Reach out to see GEM in action
• Technical Consultation: Discuss your specific technical requirements

We're here to help you succeed with geospatial data management!